Skip to content
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
`/v2/reports` run items and budget-window run items no longer have a `trigger` field: a run is shared between requests, and each user's trigger is on their record of it. API v1 no longer selects or writes the per-user columns of reports, report runs and budget-window runs, which a later database revision drops.
7 changes: 3 additions & 4 deletions docs/engineering/skills/alembic-migrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -931,10 +931,9 @@ from there gives the same operations.
- The per-user columns of shared rows become nullable, with no default:
`reports.label`, `report_runs.trigger` and `budget_window_runs.trigger`
(`reports.description` and `user_id` already were). A shared row describes
no one caller, so the simulation service stops writing them, and a later
revision drops them; until then the report read and run lists answer a
missing label or trigger as null. A user's trigger is on their
`user_report_run_associations` row.
no one caller, so the simulation service stops writing them, API v1's models
leave them out, and a later revision drops them. A user's trigger is on
their `user_report_run_associations` row.
- `user_report_run_associations` records each user's request for a report
run: the user (`CASCADE`), the run (`RESTRICT`, so a run a user asked for
can't be deleted), `requested_at` (required, with no default: the writer
Expand Down
73 changes: 38 additions & 35 deletions policyengine_api/data/v2/models/reports.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,6 @@
)
from policyengine_api.data.v2.models.policies import Policy
from policyengine_api.data.v2.models.simulations import Simulation
from policyengine_api.data.v2.models.users import User

if TYPE_CHECKING:
from policyengine_api.data.v2.models.run_results import (
Expand Down Expand Up @@ -61,7 +60,10 @@ class ReportRunStatus(StrEnum):


class ReportRunTrigger(StrEnum):
"""Why a report run started: the report's first run, a manual or a system rerun."""
"""Why a user asked for a report run: the report's creation or a re-run.

``system`` remains in the database type; no user's record may hold it.
"""

INITIAL = "initial"
MANUAL = "manual"
Expand All @@ -71,13 +73,18 @@ class ReportRunTrigger(StrEnum):
class Report(TimestampedModel, table=True):
"""Stable report definition; execution state belongs to ReportRun.

The simulation service writes reports, and the Public API the user, model,
policy, household, dataset and region a report names; each service writes
only its own tables, and the foreign keys between them stay. Deleting the
user, policy, dataset or region clears the reference, which for the user
is found through ``user_id``'s index; the model and household can't be
The simulation service writes reports, and API v1 the model, policy,
household, dataset and region a report names; each service writes only its
own tables, and the foreign keys between them stay. Deleting the policy,
dataset or region clears the reference; the model and household can't be
deleted while a report names them.

A report is shared by everyone who asks for it, so it describes no one
caller: a report's name and description are on each user's saved report.
The table's ``label``, ``description`` and ``user_id`` are left out of this
model, so API v1 neither loads nor writes them and a release keeps working
while a later revision drops them.

The simulation service finds a report by ``definition_key``, the SHA-256
of what it compares (its country, type, each side's policy and dynamic,
the dataset name, region code, year and SPM selection both sides share,
Expand All @@ -89,7 +96,19 @@ class Report(TimestampedModel, table=True):
"""

__tablename__ = "reports"
__mapper_args__: ClassVar[dict[str, Any]] = {
"exclude_properties": ("label", "description", "user_id")
}
__table_args__ = (
# Kept in the table, unmapped, until a revision drops them.
sa.Column("label", sa.String(255)),
sa.Column("description", sa.String),
sa.Column(
"user_id",
sa.Uuid,
sa.ForeignKey("users.id", ondelete="SET NULL"),
index=True,
),
sa.CheckConstraint(
"year IS NULL OR year BETWEEN 1900 AND 2200",
name="ck_reports_year",
Expand Down Expand Up @@ -117,18 +136,8 @@ class Report(TimestampedModel, table=True):
sa.Index("ix_reports_dataset_independent_key", "dataset_independent_key"),
)

# Per-user: nullable until a later revision drops it, since a shared report
# describes no one caller.
label: str | None = Field(default=None, max_length=255)
description: str | None = None
country: str = Field(max_length=16)
type: str | None = Field(default=None, max_length=128)
user_id: UUID | None = Field(
default=None,
foreign_key="users.id",
ondelete="SET NULL",
index=True,
)
tax_benefit_model_id: UUID = Field(
foreign_key="tax_benefit_models.id",
ondelete="RESTRICT",
Expand Down Expand Up @@ -171,7 +180,6 @@ class Report(TimestampedModel, table=True):
definition_key: str | None = Field(default=None, max_length=64)
dataset_independent_key: str | None = Field(default=None, max_length=64)

user: User | None = Relationship(back_populates="reports")
tax_benefit_model: TaxBenefitModel = Relationship(back_populates="reports")
policy: Policy | None = Relationship(back_populates="reports")
baseline_simulation: Simulation | None = Relationship(
Expand Down Expand Up @@ -217,7 +225,12 @@ class BudgetWindowRun(TimestampedModel, table=True):
"""

__tablename__ = "budget_window_runs"
__mapper_args__: ClassVar[dict[str, Any]] = {"exclude_properties": ("trigger",)}
__table_args__ = (
# Kept in the table, unmapped, until a revision drops it: a shared run
# answers more than one request, and each user's trigger is on their
# record of it.
sa.Column("trigger", enum_type(ReportRunTrigger, "v2_report_run_trigger")),
sa.UniqueConstraint("id", "report_id", name="uq_budget_window_runs_id_report"),
sa.CheckConstraint(
"status NOT IN ('succeeded', 'failed') OR completed_at IS NOT NULL",
Expand Down Expand Up @@ -247,12 +260,6 @@ class BudgetWindowRun(TimestampedModel, table=True):
index=True,
)
policyengine_version: str | None = Field(default=None, max_length=128)
# Per-user: nullable until a later revision drops it, since a shared run
# answers more than one request; each user's trigger is on their record.
trigger: ReportRunTrigger | None = Field(
default=None,
sa_type=enum_type(ReportRunTrigger, "v2_report_run_trigger"),
)
recalculate: bool = False
status: ReportRunStatus = Field(
default=ReportRunStatus.PENDING,
Expand Down Expand Up @@ -280,11 +287,11 @@ class ReportRun(TimestampedModel, table=True):
and ``year``, at most one report run per year of a window run.
``spm_provenance`` is the SPM receipt and ``data_version`` the data release
it used. Its labour supply response has its own two tables. Its cliff impact
is its two simulation runs' (``CliffImpact``). The table's four older cliff
columns are declared in ``__table_args__`` and left out of the mapper, so API
v1 neither loads nor writes them. This covers only those four: ``trigger`` is
still mapped, so it must stop being mapped in an earlier release before a
revision drops it.
is its two simulation runs' (``CliffImpact``), and each user's trigger is on
their record of the run. The table's four older cliff columns and
``trigger`` are declared in ``__table_args__`` and left out of the mapper, so
API v1 neither loads nor writes them and a release keeps working while a
later revision drops them.

Outside budget windows, a report has at most one run that hasn't failed
for each pair of package versions, which identical requests join; a
Expand All @@ -295,6 +302,7 @@ class ReportRun(TimestampedModel, table=True):
__tablename__ = "report_runs"
__mapper_args__: ClassVar[dict[str, Any]] = {
"exclude_properties": (
"trigger",
"baseline_cliff_gap",
"baseline_cliff_share",
"reform_cliff_gap",
Expand All @@ -303,6 +311,7 @@ class ReportRun(TimestampedModel, table=True):
}
__table_args__ = (
# Kept in the table, unmapped, until a revision drops them.
sa.Column("trigger", enum_type(ReportRunTrigger, "v2_report_run_trigger")),
sa.Column("baseline_cliff_gap", sa.Float),
sa.Column("baseline_cliff_share", sa.Float),
sa.Column("reform_cliff_gap", sa.Float),
Expand Down Expand Up @@ -391,12 +400,6 @@ class ReportRun(TimestampedModel, table=True):
default=ReportRunStatus.PENDING,
sa_type=enum_type(ReportRunStatus, "v2_report_run_status"),
)
# Per-user: nullable until a later revision drops it, since a shared run
# answers more than one request; each user's trigger is on their record.
trigger: ReportRunTrigger | None = Field(
default=None,
sa_type=enum_type(ReportRunTrigger, "v2_report_run_trigger"),
)
idempotency_key: UUID | None = Field(default=None)
modal_call_id: str | None = Field(default=None, max_length=255)
started_at: datetime | None = Field(
Expand Down
6 changes: 2 additions & 4 deletions policyengine_api/data/v2/models/users.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,6 @@
UserReportRunAssociation,
UserSimulationAssociation,
)
from policyengine_api.data.v2.models.reports import Report


class UserType(StrEnum):
Expand Down Expand Up @@ -79,8 +78,8 @@ class User(IdentifiedModel, table=True):

A signed-in user, of any type but ``unauthenticated``, always has a
primary country. Deleting a user deletes their sign-in identities, saved
associations and records of the report runs they asked for; reports they
own are kept without an owner.
associations and records of the report runs they asked for; the reports
and runs themselves are shared and stay.
"""

__tablename__ = "users"
Expand Down Expand Up @@ -115,7 +114,6 @@ class User(IdentifiedModel, table=True):
sa_column_kwargs={"server_default": UserType.STANDARD.value},
)

reports: list["Report"] = Relationship(back_populates="user")
identities: list["UserIdentity"] = Relationship(
back_populates="user",
cascade_delete=True,
Expand Down
6 changes: 0 additions & 6 deletions policyengine_api/data/v2/report_runs.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,6 @@
Report,
ReportRun,
ReportRunStatus,
ReportRunTrigger,
)
from policyengine_api.data.v2.models.base import utc_now

Expand Down Expand Up @@ -113,7 +112,6 @@ def create_report_run(
*,
report_id: UUID,
inputs: ReportRunInputs,
trigger: ReportRunTrigger,
idempotency_key: UUID | None = None,
) -> ReportRun:
"""Create one run, or return the run for a retried idempotent request.
Expand All @@ -122,9 +120,6 @@ def create_report_run(
simulation runs that attempt named.
"""
_locked_report(session, report_id)
if trigger is ReportRunTrigger.MANUAL and idempotency_key is None:
msg = "manual report reruns require an idempotency key"
raise ValueError(msg)
versions = inputs.versions
if not versions.country_package_version or not versions.policyengine_version:
msg = "report run package versions must be non-empty"
Expand All @@ -136,7 +131,6 @@ def create_report_run(
reform_simulation_run_id=inputs.simulation_runs.reform_simulation_run_id,
country_package_version=versions.country_package_version,
policyengine_version=versions.policyengine_version,
trigger=trigger,
idempotency_key=idempotency_key,
)
if idempotency_key is None:
Expand Down
11 changes: 2 additions & 9 deletions policyengine_api/fastapi_routes/v2/reports/response_models.py
Original file line number Diff line number Diff line change
Expand Up @@ -56,15 +56,11 @@ class ReportRunItem(StrictReportAPIModel):
"""One calculation of a report, on one country package and .py version.

``status`` is ``pending``, ``running``, ``succeeded`` or ``failed``, and
``error_message`` says why a failed run failed. ``trigger`` is
``initial`` for the run the report's creation started, and null for a run
the simulation service shares between requests, which records no one
request's trigger.
``error_message`` says why a failed run failed.
"""

id: UUID
status: Literal["pending", "running", "succeeded", "failed"]
trigger: Literal["initial", "manual", "system"] | None
country_package_version: str
policyengine_version: str
baseline_simulation_run_id: UUID
Expand Down Expand Up @@ -299,9 +295,7 @@ class BudgetWindowRunItem(StrictReportAPIModel):

``status`` is ``pending`` until a year starts running, ``running`` while
its years run, ``failed`` once a year has failed, with ``error_message``
saying which, and ``succeeded`` once every year has. ``trigger`` is
``initial`` for the run the report's creation started (null for a shared
run, which records no one request's trigger), and ``recalculate`` says
saying which, and ``succeeded`` once every year has. ``recalculate`` says
whether its years calculate their simulations again rather than reusing
successful runs.
``country_package_version`` and ``policyengine_version`` are the versions
Expand All @@ -310,7 +304,6 @@ class BudgetWindowRunItem(StrictReportAPIModel):

id: UUID
status: Literal["pending", "running", "succeeded", "failed"]
trigger: Literal["initial", "manual", "system"] | None
recalculate: bool
country_package_version: str | None
policyengine_version: str | None
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -68,11 +68,10 @@ def report_kind(report: Report) -> ReportKind:


def report_run_read(run: ReportRun) -> ReportRunRead:
"""Return the run's status, trigger, versions and times."""
"""Return the run's status, versions and times."""
return ReportRunRead(
id=run.id,
status=run.status.value,
trigger=None if run.trigger is None else run.trigger.value,
country_package_version=run.country_package_version,
policyengine_version=run.policyengine_version,
baseline_simulation_run_id=run.baseline_simulation_run_id,
Expand Down Expand Up @@ -236,7 +235,7 @@ def household_report_read(
def budget_window_run_read(
window_run: BudgetWindowRun, years: Sequence[ReportRun]
) -> BudgetWindowRunRead:
"""Return the window run's status, trigger and times, with its years.
"""Return the window run's status and times, with its years.

Its versions are its first year's, since the simulation service creates
every year on one version; a run with no year has none.
Expand All @@ -250,7 +249,6 @@ def budget_window_run_read(
return BudgetWindowRunRead(
id=window_run.id,
status=window_run.status.value,
trigger=None if window_run.trigger is None else window_run.trigger.value,
recalculate=window_run.recalculate,
country_package_version=(
None if first_year is None else first_year.country_package_version
Expand Down
9 changes: 2 additions & 7 deletions policyengine_api/services/v2/stored_reports/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,6 @@
# The kinds whose runs are their report runs; a budget window's are its
# budget-window runs.
ReportRunsKind = Literal["economy", "household"]
ReportRunTriggerName = Literal["initial", "manual", "system"]
# How far a side's cliff calculation has got: not_calculated while its
# simulation run has none, else its calculation's status (failed once its
# newest calculation failed and none is pending, running or succeeded).
Expand All @@ -65,15 +64,12 @@
class ReportRunRead:
"""One calculation of a report, and the package versions it ran on.

``trigger`` is ``initial`` for the run the report's creation started, and
null for a run the simulation service shares between requests. A user's
trigger is on their record of the run. ``error_message`` says why a failed
run failed.
``error_message`` says why a failed run failed. A run is shared between
requests, so each user's trigger is on their record of the run.
"""

id: UUID
status: Literal["pending", "running", "succeeded", "failed"]
trigger: ReportRunTriggerName | None
country_package_version: str
policyengine_version: str
baseline_simulation_run_id: UUID
Expand Down Expand Up @@ -237,7 +233,6 @@ class BudgetWindowRunRead:

id: UUID
status: Literal["pending", "running", "succeeded", "failed"]
trigger: ReportRunTriggerName | None
recalculate: bool
country_package_version: str | None
policyengine_version: str | None
Expand Down
13 changes: 5 additions & 8 deletions tests/integration/stored_report_rows.py
Original file line number Diff line number Diff line change
Expand Up @@ -299,21 +299,19 @@ def store_report( # noqa: PLR0913 # the connection and catalog, then each colu
)
connection.execute(
text(
"INSERT INTO reports (id, label, description, country, type, "
"INSERT INTO reports (id, country, type, "
"tax_benefit_model_id, policy_id, baseline_simulation_id, "
"reform_simulation_id, household_id, dataset_id, region_id, year, "
"budget_window_size, inputs, key_version, definition_key, "
"dataset_independent_key, created_at) VALUES (:id, :label, "
":description, :country, :type, :model_id, :policy_id, :baseline, "
"dataset_independent_key, created_at) VALUES (:id, "
":country, :type, :model_id, :policy_id, :baseline, "
":reform, :household_id, :dataset_id, :region_id, :year, "
":budget_window_size, CAST(:inputs AS JSON), :key_version, "
":definition_key, :dataset_independent_key, "
"COALESCE(CAST(:created_at AS timestamptz), now()))"
),
{
"id": report.report_id,
"label": f"{catalog.country} reform",
"description": "A stored report",
"country": catalog.country,
"type": "economy",
"model_id": catalog.model_id,
Expand Down Expand Up @@ -387,13 +385,13 @@ def store_report_run(
"INSERT INTO report_runs (id, created_at, report_id, "
"baseline_simulation_run_id, reform_simulation_run_id, "
"budget_window_run_id, year, "
"country_package_version, policyengine_version, status, trigger, "
"country_package_version, policyengine_version, status, "
"started_at, completed_at, error_message, spm_provenance, forced"
+ "".join(f", {column}" for column in result_columns)
+ ") VALUES (:id, :created_at, :report_id, :baseline_run, "
":reform_run, :budget_window_run_id, :year, "
":country_package_version, :policyengine_version, "
":status, 'initial', :started_at, :completed_at, :error_message, "
":status, :started_at, :completed_at, :error_message, "
":spm_provenance, :forced"
+ "".join(f", :{column}" for column in result_columns)
+ ")"
Expand Down Expand Up @@ -485,7 +483,6 @@ def store_budget_window_run(
created_at=created_at,
report_id=report.report_id,
tax_benefit_model_version_id=catalog.version_id,
trigger="initial",
recalculate=False,
status=settings.status,
error_message=settings.error_message,
Expand Down
2 changes: 1 addition & 1 deletion tests/integration/test_v2_budget_window_report_creation.py
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,7 @@ def test_a_created_budget_window_is_answered_as_the_tables_hold_it(
assert (item["id"], item["kind"]) == (str(catalog.report_ids[0]), "budget_window")
assert (item["year"], item["budget_window_size"]) == (2026, 3)
assert item["status"] == "pending"
assert item["run"]["trigger"] == "initial"
assert "trigger" not in item["run"]
assert item["run"]["policyengine_version"] == "4.2.0"
assert [(year["year"], year["status"]) for year in item["run"]["years"]] == [
(2026, "pending"),
Expand Down
Loading
Loading