Romulus documentation
Waits and events
Release the worker while preserving the exact condition that can resume its run.
{
"run_id": "run_7f21",
"state": "waiting",
"event_type": "report.completed",
"correlation_id": "job_b772",
"timeout_policy": "request_review"
}Define the wait
Persist the expected event type, correlation ID and optional deadline in the run record before releasing the worker. Use a scoped correlation ID that distinguishes this external job or approval from other runs in the same project.
Decide what happens if the deadline passes. A workflow might cancel the external job, continue with a fallback, or stop for operator review. Capture that decision in the workflow definition.
Record the event before matching
Validate the event’s origin and payload and store it durably. Consider stored events when a run enters a wait, so a fast callback cannot slip through before the waiting state exists.
Deduplicate deliveries using the sender’s event identifier in its appropriate scope. Compare the job ID and event type against the active wait and check that the producer has authority to resume this run.
Resolve the race
A valid event and a deadline can become eligible at the same time. Use a conditional update so one transition wins and the next position is committed once. Preserve a late or duplicate delivery in the trace if it is relevant to investigation.
Test events arriving early, twice, after the deadline and with an incorrect correlation ID. The trace should explain why the run stayed waiting, resumed, or timed out.