Describe the dispatch, the report function and other_call as they work

From the extra review of the reworked 1.06: run_dispatch still said a new
call's first check is due shortly (it is the safety check's, one interval
later) and that the recording loop collects a call whose record is
unknown; report_call_ended's docstring said the reported call has always
returned when sim asks Modal (usually it has; otherwise sim answers
still_running and the function reports again); and other_call is also the
answer for runs that finished without holding any call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: anth-volk

libs/policyengine-simulation-contract/src/policyengine_simulation_contract/call_reports.py

@@ -90,7 +90,8 @@ class CallReportStatus(StrEnum):
     NOT_CONFIGURED = "not_configured"
     # No run, or not every run, the report names exists.
     UNKNOWN_RUNS = "unknown_runs"
-    # The runs hold another Modal call.
+    # The runs hold another Modal call, or finished without holding one (for
+    # example failed as abandoned before the call's ID was stored).
     OTHER_CALL = "other_call"
 
 

projects/policyengine-simulation-entry/src/policyengine_simulation_entry/run_dispatch.py

@@ -5,11 +5,12 @@
 1. claim: move the runs from ``pending`` to ``dispatching``. Only the instance
    whose claim changes them goes on; every other caller stops here.
 2. spawn the Modal call and wait only for Modal's acknowledgement.
-3. record the call ID, moving the runs to ``running`` with their first check
-   due shortly; or, when Modal refused the call, fail them.
+3. record the call ID, moving the runs to ``running``, with the safety
+   check's first look due one interval later (the call itself reports when
+   it ends); or, when starting the call raised, fail them.
 
-If the instance stops between 1 and 3, the runs stay ``dispatching`` until a
-recording pass fails them as abandoned. No route starts calls yet.
+If the instance stops between 1 and 3, the runs stay ``dispatching`` until the
+safety check fails them as abandoned. No route starts calls yet.
 """
 
 from __future__ import annotations
@@ -59,8 +60,9 @@ class DispatchOutcome(StrEnum):
     # cancelled.
     NOT_RECORDED = "not_recorded"
     # Recording the call raised and the database could not say whether the
-    # record committed; the call is left running. If it did, the recording
-    # loop collects the call; if not, the runs are failed as abandoned.
+    # record committed; the call is left running. If it did, the call's report
+    # or the safety check records its outcome; if not, the safety check fails
+    # the runs as abandoned.
     RECORD_UNKNOWN = "record_unknown"
 
 

projects/policyengine-simulation-executor/src/modal/v2_app.py

@@ -520,8 +520,10 @@ def report_call_ended(report: dict) -> str:
     """Tell sim that the call in ``report`` ended; return how that went.
 
     The v2 functions start this as their last step
-    (``src.modal.call_reports.reporting_call_end``), so the reported call
-    has returned by the time sim asks Modal for its outcome.
+    (``src.modal.call_reports.reporting_call_end``) and then return, so the
+    reported call has usually returned by the time sim asks Modal for its
+    outcome; when it has not, sim answers still_running and this reports
+    again after a wait.
     """
     from src.modal.call_reports import (  # noqa: PLC0415  # Modal function body: loaded in the worker container, not at deploy time
         send_call_ended_report_from_container,