Implement canonical report runs and legacy ID map

Author: anth-volk

changelog.d/3500.changed.md

@@ -1 +1 @@
-Preserve explicit report definitions and execution metadata across later syncs, key new report creation and alias validation by canonical report identity, and resolve report reads through canonical parents plus display-run selection.
+Preserve explicit report definitions and execution metadata, key report creation by canonical report identity, resolve legacy report IDs through a permanent compatibility map, and add run-targeted report and simulation rerun updates.

policyengine_api/data/initialise.sql

@@ -141,6 +141,11 @@ CREATE TABLE IF NOT EXISTS report_outputs (
     latest_successful_run_id CHAR(36) DEFAULT NULL
 );
 
+CREATE INDEX report_outputs_identity_idx
+    ON report_outputs (
+        country_id, report_identity_hash, report_identity_schema_version
+    );
+
 CREATE TABLE IF NOT EXISTS report_output_runs (
     id CHAR(36) PRIMARY KEY,
     report_output_id INT NOT NULL,
@@ -189,7 +194,13 @@ CREATE TABLE IF NOT EXISTS simulation_runs (
     UNIQUE KEY simulation_run_sequence_idx (simulation_id, run_sequence)
 );
 
-CREATE TABLE IF NOT EXISTS legacy_report_output_aliases (
+CREATE INDEX simulation_runs_report_output_run_idx
+    ON simulation_runs (report_output_run_id);
+
+CREATE TABLE IF NOT EXISTS legacy_report_output_id_map (
     legacy_report_output_id INT PRIMARY KEY,
     canonical_report_output_id INT NOT NULL
 );
+
+CREATE INDEX legacy_report_output_id_map_canonical_idx
+    ON legacy_report_output_id_map (canonical_report_output_id);

policyengine_api/data/initialise_local.sql

@@ -8,7 +8,7 @@ DROP TABLE IF EXISTS user_policies;
 DROP TABLE IF EXISTS tracers;
 DROP TABLE IF EXISTS report_output_runs;
 DROP TABLE IF EXISTS simulation_runs;
-DROP TABLE IF EXISTS legacy_report_output_aliases;
+DROP TABLE IF EXISTS legacy_report_output_id_map;
 
 CREATE TABLE IF NOT EXISTS household (
     id INTEGER PRIMARY KEY,
@@ -153,6 +153,11 @@ CREATE TABLE IF NOT EXISTS report_outputs (
     latest_successful_run_id CHAR(36) DEFAULT NULL
 );
 
+CREATE INDEX report_outputs_identity_idx
+    ON report_outputs (
+        country_id, report_identity_hash, report_identity_schema_version
+    );
+
 CREATE TABLE IF NOT EXISTS report_output_runs (
     id CHAR(36) PRIMARY KEY,
     report_output_id INT NOT NULL,
@@ -201,7 +206,13 @@ CREATE TABLE IF NOT EXISTS simulation_runs (
     UNIQUE (simulation_id, run_sequence)
 );
 
-CREATE TABLE IF NOT EXISTS legacy_report_output_aliases (
+CREATE INDEX simulation_runs_report_output_run_idx
+    ON simulation_runs (report_output_run_id);
+
+CREATE TABLE IF NOT EXISTS legacy_report_output_id_map (
     legacy_report_output_id INT PRIMARY KEY,
     canonical_report_output_id INT NOT NULL
 );
+
+CREATE INDEX legacy_report_output_id_map_canonical_idx
+    ON legacy_report_output_id_map (canonical_report_output_id);

policyengine_api/routes/report_output_routes.py

@@ -195,6 +195,53 @@ def get_report_output(country_id: str, report_id: int) -> Response:
     )
 
 
+@report_output_bp.route("/<country_id>/report/<int:report_id>/rerun", methods=["POST"])
+@validate_country
+def create_report_rerun(country_id: str, report_id: int) -> Response:
+    """
+    Create a new pending run for an existing report.
+
+    The requested report ID may be a legacy ID; the run is always created under
+    the resolved canonical report output.
+    """
+    payload = request.json or {}
+    if not isinstance(payload, dict):
+        raise BadRequest("Payload must be an object")
+
+    version_manifest_overrides = _parse_report_run_metadata(payload)
+
+    try:
+        if not report_output_service.report_output_exists(country_id, report_id):
+            raise NotFound(f"Report #{report_id} not found.")
+
+        rerun = report_output_service.create_report_rerun(
+            country_id=country_id,
+            report_output_id=report_id,
+            version_manifest_overrides=version_manifest_overrides,
+        )
+    except HTTPException:
+        raise
+    except ValueError as e:
+        current_app.logger.warning(
+            "Bad request creating report rerun #%s for country %s: %s",
+            report_id,
+            country_id,
+            e,
+        )
+        raise BadRequest(f"Failed to create report rerun: {e}") from e
+
+    response_body = dict(
+        status="ok",
+        message="Report rerun created successfully",
+        result=rerun,
+    )
+    return Response(
+        json.dumps(response_body),
+        status=201,
+        mimetype="application/json",
+    )
+
+
 @report_output_bp.route("/<country_id>/report", methods=["PATCH"])
 @validate_country
 def update_report_output(country_id: str) -> Response:
@@ -206,6 +253,7 @@ def update_report_output(country_id: str) -> Response:
 
     Request body can contain:
         - id (int): The report output ID.
+        - report_output_run_id (str | None): Specific report run to update.
         - status (str): The new status ('pending', 'running', 'complete', or 'error')
         - output (dict): The result output (for complete status)
         - api_version (str): The API version of the report
@@ -221,6 +269,7 @@ def update_report_output(country_id: str) -> Response:
     report_id = payload.get("id")
     output = payload.get("output")
     error_message = payload.get("error_message")
+    report_output_run_id = payload.get("report_output_run_id")
     version_manifest_overrides = _parse_report_run_metadata(payload)
     print(f"Updating report #{report_id} for country {country_id}")
 
@@ -236,6 +285,8 @@ def update_report_output(country_id: str) -> Response:
     # Validate that complete status has output
     if status == "complete" and output is None:
         raise BadRequest("output is required when status is 'complete'")
+    if report_output_run_id is not None and not isinstance(report_output_run_id, str):
+        raise BadRequest("report_output_run_id must be a string")
 
     try:
         # First check if the report output exists without running pointer sync:
@@ -251,17 +302,14 @@ def update_report_output(country_id: str) -> Response:
             status=status,
             output=output,
             error_message=error_message,
+            report_output_run_id=report_output_run_id,
             version_manifest_overrides=version_manifest_overrides,
         )
 
         if not success:
             raise BadRequest("No fields to update")
 
-        # Get the updated stored record so stale-runtime jobs do not appear to
-        # complete the current runtime lineage in the PATCH response.
-        updated_report = report_output_service.get_stored_report_output(
-            country_id, report_id
-        )
+        updated_report = report_output_service.get_report_output(country_id, report_id)
 
         response_body = dict(
             status="ok",

policyengine_api/routes/simulation_routes.py

@@ -178,6 +178,7 @@ def update_simulation(country_id: str) -> Response:
 
     Request body can contain:
         - id (int): The simulation ID.
+        - simulation_run_id (str | None): Specific simulation run to update.
         - status (str): The new status ('complete' or 'error')
         - output (dict): The result output (for complete status)
         - api_version (str): The API version of the simulation
@@ -193,6 +194,7 @@ def update_simulation(country_id: str) -> Response:
     simulation_id = payload.get("id")
     output = payload.get("output")
     error_message = payload.get("error_message")
+    simulation_run_id = payload.get("simulation_run_id")
     version_manifest_overrides = _parse_simulation_run_metadata(payload)
     print(f"Updating simulation #{simulation_id} for country {country_id}")
 
@@ -203,6 +205,8 @@ def update_simulation(country_id: str) -> Response:
     # Validate that complete status has output
     if status == "complete" and output is None:
         raise BadRequest("output is required when status is 'complete'")
+    if simulation_run_id is not None and not isinstance(simulation_run_id, str):
+        raise BadRequest("simulation_run_id must be a string")
 
     try:
         # First check if the simulation exists
@@ -219,6 +223,7 @@ def update_simulation(country_id: str) -> Response:
             status=status,
             output=output,
             error_message=error_message,
+            simulation_run_id=simulation_run_id,
             version_manifest_overrides=version_manifest_overrides,
         )