Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/scripts/test_alembic_v2_lifecycle.sh
Original file line number Diff line number Diff line change
Expand Up @@ -11,4 +11,5 @@ uv run --frozen --extra dev pytest -q \
tests/integration/test_alembic_v2_saved_item_keys.py \
tests/integration/test_alembic_v2_user_types.py \
tests/integration/test_alembic_v2_withheld_area_codes.py \
tests/integration/test_alembic_v2_shared_report_keys.py
tests/integration/test_alembic_v2_shared_report_keys.py \
tests/integration/test_alembic_v2_user_dynamics.py
1 change: 1 addition & 0 deletions changelog.d/v2-user-dynamics.added.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Let users save named dynamics, as they save policies: `user_dynamics` holds the owner (a signed-in user or a signed-out browser), the country, a dynamic stored in that country, and a name and description. `POST /v2/user-dynamics` saves one (201), refusing an unknown dynamic (404) and another country's (400); `GET /v2/user-dynamics` lists the caller's saved dynamics, optionally for one `dynamic_id`; and `GET`, `PATCH` (rename, or repoint to another dynamic) and `DELETE` `/v2/user-dynamics/{association_id}` act on one, answering 404 for another user's. Saved dynamics are deleted with their user, move to the account at sign-in, and are listed in `dynamics` in `GET /v2/me/export` and the admin saved-items read. A dynamic that users have saved can't be deleted. API v1 doesn't copy v1 saved policies into saved dynamics, since it no longer writes v1 saved policies; the migration of existing rows creates them.
28 changes: 23 additions & 5 deletions docs/engineering/migration-contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi
| Metric | Count |
| --- | ---: |
| route group count | 9 |
| workflow count | 19 |
| request count | 103 |
| workflow count | 20 |
| request count | 113 |
| db entity count | 6 |
| sim flow count | 3 |

Expand All @@ -19,7 +19,7 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi
| `health` | `health`, `simulation-gateway-check`, `liveness-check`, `readiness-check`, `deployment` | `none` | `none` |
| `specification` | `specification` | `none` | `none` |
| `metadata` | `metadata`, `countries`, `datasets`, `economy-options`, `model-catalog`, `parameter-values`, `parameters`, `regions`, `tax-benefit-model-versions`, `tax-benefit-models`, `variables` | `metadata` | `none` |
| `policy` | `policy`, `policies`, `dynamics`, `user-policy`, `user-policies` | `policy` | `none` |
| `policy` | `policy`, `policies`, `dynamics`, `user-policy`, `user-policies`, `user-dynamics` | `policy` | `none` |
| `household` | `household`, `households`, `household-calculations`, `user-household`, `user-households`, `calculate`, `calculate-full` | `household` | `household` |
| `economy` | `economy` | `simulation` | `economy` |
| `simulation` | `simulation`, `simulations`, `user-simulations` | `simulation` | `economy` |
Expand Down Expand Up @@ -77,6 +77,24 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi
| `PATCH` | `/v2/user-policies/{association_id}?country_id=us` | 200 | `policy` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.legacy_policy_id`, `result.item.policy_id`, `result.item.name`, `result.item.description`, `result.item.baseline`, `result.item.provenance`, `result.item.updated_at` |
| `DELETE` | `/v2/user-policies/{association_id}?country_id=us` | 204 | `policy` | `PolicyEngine-Unauthenticated-User` | |

### `user_dynamic_associations_v2`

- Current contract: `typed_v2_resources`
- Future owner: Users' saved dynamics

| Method | Path | Status | Route group | Required headers | Stable response fields |
| --- | --- | ---: | --- | --- | --- |
| `POST` | `/v2/user-dynamics?country_id=us` | 201 | `policy` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.dynamic_id`, `result.item.name`, `result.item.description`, `result.item.created_at`, `result.item.updated_at` |
| `GET` | `/v2/user-dynamics/{association_id}?country_id=us` | 200 | `policy` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.dynamic_id`, `result.item.name`, `result.item.description`, `result.item.created_at`, `result.item.updated_at` |
| `GET` | `/v2/user-dynamics?country_id=us` | 200 | `policy` | `Authorization` | `status`, `message`, `result.items`, `result.offset`, `result.limit`, `result.has_more` |
| `PATCH` | `/v2/user-dynamics/{association_id}?country_id=us` | 200 | `policy` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.dynamic_id`, `result.item.name`, `result.item.description`, `result.item.updated_at` |
| `DELETE` | `/v2/user-dynamics/{association_id}?country_id=us` | 204 | `policy` | `Authorization` | |
| `POST` | `/v2/user-dynamics?country_id=us` | 201 | `policy` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.dynamic_id`, `result.item.name`, `result.item.description`, `result.item.created_at`, `result.item.updated_at` |
| `GET` | `/v2/user-dynamics/{association_id}?country_id=us` | 200 | `policy` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.dynamic_id`, `result.item.name`, `result.item.description`, `result.item.created_at`, `result.item.updated_at` |
| `GET` | `/v2/user-dynamics?country_id=us` | 200 | `policy` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.items`, `result.offset`, `result.limit`, `result.has_more` |
| `PATCH` | `/v2/user-dynamics/{association_id}?country_id=us` | 200 | `policy` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.dynamic_id`, `result.item.name`, `result.item.description`, `result.item.updated_at` |
| `DELETE` | `/v2/user-dynamics/{association_id}?country_id=us` | 204 | `policy` | `PolicyEngine-Unauthenticated-User` | |

### `household_save_read`

- Current contract: `api_v1_compatible`
Expand Down Expand Up @@ -173,8 +191,8 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi
| `GET` | `/v2/me?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.user_type`, `result.item.primary_country`, `result.item.first_name`, `result.item.last_name`, `result.item.email`, `result.item.created_at`, `result.latest_type_change` |
| `GET` | `/v2/me?country_id=us` | 200 | `user_profile` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.user_type`, `result.item.primary_country`, `result.item.first_name`, `result.item.last_name`, `result.item.email`, `result.item.created_at`, `result.latest_type_change` |
| `PATCH` | `/v2/me?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.primary_country`, `result.item.first_name`, `result.item.last_name` |
| `GET` | `/v2/me/export?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.user`, `result.policies`, `result.households`, `result.simulations`, `result.reports` |
| `GET` | `/v2/me/export?country_id=us` | 200 | `user_profile` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.user`, `result.policies`, `result.households`, `result.simulations`, `result.reports` |
| `GET` | `/v2/me/export?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.user`, `result.policies`, `result.dynamics`, `result.households`, `result.simulations`, `result.reports` |
| `GET` | `/v2/me/export?country_id=us` | 200 | `user_profile` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.user`, `result.policies`, `result.dynamics`, `result.households`, `result.simulations`, `result.reports` |
| `POST` | `/v2/me/upgrade?country_id=us` | 200 | `user_profile` | `Authorization`, `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.user_type`, `result.item.primary_country`, `result.outcome` |
| `POST` | `/v2/me/invitations/accept?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.item.user_type`, `result.item.previous_user_type`, `result.item.type_changed` |
| `POST` | `/v2/me/type-changes/{type_change_id}/dismiss?country_id=us` | 204 | `user_profile` | `Authorization` | |
Expand Down
43 changes: 43 additions & 0 deletions docs/engineering/skills/alembic-migrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -457,6 +457,8 @@ it publishes that version, with nothing to restore it. Downgrading past the
revision is therefore safe only while no version is pruned (no
`tax_benefit_model_versions` row has `catalog_values_pruned_at` set).
From the head, such a downgrade first runs the later revisions' downgrades:
`d417fe8b1b17`'s drops `user_dynamics` with every saved dynamic (see "API v2
users' saved dynamics"),
`9d1d12a7ac58`'s needs `dynamics` empty (see "API v2 dynamics stored like
policies"),
`f519a77ba122`'s drops `user_invitations` and needs no recorded change with
Expand Down Expand Up @@ -1073,3 +1075,44 @@ row. `tests/integration/test_alembic_v2_dynamics.py` checks that nothing else
changes, the downgrade and upgrade, both refusals, and the keys and unique
rules.

### API v2 users' saved dynamics

Revision `d417fe8b1b17` (parent `9d1d12a7ac58`) was autogenerated, with no
post-generation corrections apart from `ruff format`, after the model gained
`UserDynamic`. Its ID was chosen with `--rev-id`, so the tests written before it
could name it. It creates `user_dynamics`, users' named saved dynamics, built
like `user_policies` without its v1 reference, `baseline` and `provenance`:

- `user_id`, a key to `users`, `CASCADE`, indexed: a user's saved dynamics
are deleted with the user, and the sign-in merge moves a browser's to the
account it signs in to.
- `country_id`, a key to `countries`, `RESTRICT`.
- `dynamic_id` (required): with `country_id`, a key to `dynamics (id,
country_id)` (`fk_user_dynamics_dynamic_country`, `RESTRICT`). A saved
dynamic names a dynamic of its own country, and a dynamic that users have
saved can't be deleted.
- `name` (255) and `description` (text), both nullable.
- `(id, country_id)` is unique (`uq_user_dynamics_id_country`), so other
tables can name a saved dynamic of one country. There is no unique rule on
the owner and dynamic: a user may save one dynamic more than once.
- Indexes on `(country_id, user_id, created_at, id)` for a user's listing,
and on `(country_id, dynamic_id)`, which also serves the key's check when a
dynamic is deleted.

`user_dynamics` has no v1 column, since v1 has no dynamics. API v1 no longer
writes v1 saved policies (their routes were removed on 2026-10-22), so no
copy creates saved dynamics. D4 · 1's migration gives each v1 saved policy that
holds assumption values a saved dynamic with its name, through
`services.v2.user_dynamics.services.create_user_dynamic_in_session`.

The runtime role reads and writes `user_dynamics`, as it does `user_policies`;
no other role has access. The previous API v1 revision doesn't map the table,
so it keeps working at this revision, and deleting a user through it still
deletes their saved dynamics, through the key's `CASCADE`. Its sign-in merge
doesn't move saved dynamics, though: while it serves after a rollback, a
browser that signs in to an existing account loses its saved dynamics with
its unauthenticated user. The downgrade drops the table with every saved
dynamic, and the dynamics they named stay.
`tests/integration/test_alembic_v2_user_dynamics.py` checks that nothing else
changes, the keys, deletion with the user and the downgrade.

3 changes: 3 additions & 0 deletions docs/engineering/skills/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -632,6 +632,8 @@ uv run --frozen pytest \
tests/unit/v2/test_user_household_routes.py \
tests/unit/v2/test_user_simulation_report_routes.py \
tests/unit/v2/test_user_policy_service.py \
tests/unit/v2/test_user_dynamic_routes.py \
tests/unit/v2/test_user_dynamic_service.py \
tests/unit/v2/test_user_household_service.py \
tests/unit/v2/test_user_account_service.py \
tests/unit/v2/test_unauthenticated_user_service.py \
Expand All @@ -658,6 +660,7 @@ V2_MIGRATION_DATABASE_URL="postgresql+psycopg://.../policyengine_v2_alembic_test
uv run --frozen pytest \
tests/integration/test_alembic_v2_lifecycle.py \
tests/integration/test_alembic_v2_catalog_tables.py \
tests/integration/test_alembic_v2_user_dynamics.py \
tests/integration/test_v2_user_identity_persistence.py \
tests/integration/test_v2_user_type_persistence.py -q
```
Expand Down
4 changes: 2 additions & 2 deletions docs/engineering/skills/typing-only-imports.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,8 @@ name in that annotation at module level. Query dependencies are module-level
aliases, such as `CountryQueryDependency`. The signed-in user routes also depend
on `require_user`, the authenticator `NativeRouteDependencies` injects into each
router, which exists only inside the router builder. Their modules
(`fastapi_routes/v2/me`, `user_households`, `user_policies`, `user_reports` and
`user_simulations`) don't use `from __future__ import annotations`, so
(`fastapi_routes/v2/me`, `user_dynamics`, `user_households`, `user_policies`,
`user_reports` and `user_simulations`) don't use `from __future__ import annotations`, so
`Annotated[AccountPrincipal, Depends(require_user)]` is evaluated where the
handler is defined, and the names their other annotations use are imported at
runtime. With the future import, FastAPI would silently treat `principal` as a
Expand Down
190 changes: 187 additions & 3 deletions docs/generated/migration_contracts.json
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
{
"metadata": {
"db_entity_count": 6,
"request_count": 103,
"request_count": 113,
"route_group_count": 9,
"sim_flow_count": 3,
"workflow_count": 19
"workflow_count": 20
},
"route_groups": [
{
Expand Down Expand Up @@ -53,7 +53,8 @@
"policies",
"dynamics",
"user-policy",
"user-policies"
"user-policies",
"user-dynamics"
],
"sim_flow": null
},
Expand Down Expand Up @@ -444,6 +445,187 @@
}
]
},
{
"current_contract": "typed_v2_resources",
"future_owner_pr": "Users' saved dynamics",
"name": "user_dynamic_associations_v2",
"requests": [
{
"expected_status": 201,
"headers": [
"Authorization"
],
"method": "POST",
"path": "/v2/user-dynamics?country_id=us",
"route_group": "policy",
"stable_response_fields": [
"status",
"message",
"result.item.id",
"result.item.country_id",
"result.item.user_id",
"result.item.dynamic_id",
"result.item.name",
"result.item.description",
"result.item.created_at",
"result.item.updated_at"
]
},
{
"expected_status": 200,
"headers": [
"Authorization"
],
"method": "GET",
"path": "/v2/user-dynamics/{association_id}?country_id=us",
"route_group": "policy",
"stable_response_fields": [
"status",
"message",
"result.item.id",
"result.item.country_id",
"result.item.user_id",
"result.item.dynamic_id",
"result.item.name",
"result.item.description",
"result.item.created_at",
"result.item.updated_at"
]
},
{
"expected_status": 200,
"headers": [
"Authorization"
],
"method": "GET",
"path": "/v2/user-dynamics?country_id=us",
"route_group": "policy",
"stable_response_fields": [
"status",
"message",
"result.items",
"result.offset",
"result.limit",
"result.has_more"
]
},
{
"expected_status": 200,
"headers": [
"Authorization"
],
"method": "PATCH",
"path": "/v2/user-dynamics/{association_id}?country_id=us",
"route_group": "policy",
"stable_response_fields": [
"status",
"message",
"result.item.id",
"result.item.dynamic_id",
"result.item.name",
"result.item.description",
"result.item.updated_at"
]
},
{
"expected_status": 204,
"headers": [
"Authorization"
],
"method": "DELETE",
"path": "/v2/user-dynamics/{association_id}?country_id=us",
"route_group": "policy",
"stable_response_fields": []
},
{
"expected_status": 201,
"headers": [
"PolicyEngine-Unauthenticated-User"
],
"method": "POST",
"path": "/v2/user-dynamics?country_id=us",
"route_group": "policy",
"stable_response_fields": [
"status",
"message",
"result.item.id",
"result.item.country_id",
"result.item.user_id",
"result.item.dynamic_id",
"result.item.name",
"result.item.description",
"result.item.created_at",
"result.item.updated_at"
]
},
{
"expected_status": 200,
"headers": [
"PolicyEngine-Unauthenticated-User"
],
"method": "GET",
"path": "/v2/user-dynamics/{association_id}?country_id=us",
"route_group": "policy",
"stable_response_fields": [
"status",
"message",
"result.item.id",
"result.item.country_id",
"result.item.user_id",
"result.item.dynamic_id",
"result.item.name",
"result.item.description",
"result.item.created_at",
"result.item.updated_at"
]
},
{
"expected_status": 200,
"headers": [
"PolicyEngine-Unauthenticated-User"
],
"method": "GET",
"path": "/v2/user-dynamics?country_id=us",
"route_group": "policy",
"stable_response_fields": [
"status",
"message",
"result.items",
"result.offset",
"result.limit",
"result.has_more"
]
},
{
"expected_status": 200,
"headers": [
"PolicyEngine-Unauthenticated-User"
],
"method": "PATCH",
"path": "/v2/user-dynamics/{association_id}?country_id=us",
"route_group": "policy",
"stable_response_fields": [
"status",
"message",
"result.item.id",
"result.item.dynamic_id",
"result.item.name",
"result.item.description",
"result.item.updated_at"
]
},
{
"expected_status": 204,
"headers": [
"PolicyEngine-Unauthenticated-User"
],
"method": "DELETE",
"path": "/v2/user-dynamics/{association_id}?country_id=us",
"route_group": "policy",
"stable_response_fields": []
}
]
},
{
"current_contract": "api_v1_compatible",
"future_owner_pr": "PR 11: Household Migration",
Expand Down Expand Up @@ -1284,6 +1466,7 @@
"message",
"result.user",
"result.policies",
"result.dynamics",
"result.households",
"result.simulations",
"result.reports"
Expand All @@ -1302,6 +1485,7 @@
"message",
"result.user",
"result.policies",
"result.dynamics",
"result.households",
"result.simulations",
"result.reports"
Expand Down
Loading
Loading