Skip to content

0017. Workflow run identity, re-entry policy, and stop

  • Status: Accepted
  • Date: 2026-11-08

The earlier proposal derived an event-triggered run’s ID from (project, definition version, event ID), so replaying an event after republishing a workflow could start a second run. The re-entry policy for a customer who triggers the same workflow again, and whether stopping a workflow cancels or drains waiting runs, were open.

Run identity:

  • An event-triggered run’s ID is hash(project, workflow_id, event_id). The run records the version it pinned; the version is not part of the ID.
  • Time-triggered run IDs follow ADR 0016.
  • A replay is a resubmission with the same client idempotency key, or an inbound webhook with the same source event ID. Both resolve to the original event ID. A resubmission without a key is a new event.

Re-entry, set per workflow:

Policy Behaviour
once A customer enters the workflow at most once
no-while-active (default) A new entry is skipped while the customer has an active run; allowed after it ends
restart The active run exits (exited:restarted) and a new run starts
always Every trigger starts a run, even while others are active
  • Invariant: under once, no-while-active, and restart, a customer has at most one active run per workflow; under once, a customer has at most one run per workflow ever.
  • The re-entry policy belongs to the workflow, not to a version, and can be changed only while the workflow is stopped, so active runs never mix policies. After a change to once, entry markers count from the change.
  • Enforcement, in the project store, in the same transaction that creates the run:
    • workflow_entries has one row per run with the run’s active flag and the workflow’s re-entry policy when the run started. A partial unique index on (workflow_id, customer_id) WHERE active AND policy <> 'always' rejects a second active run. The flag is cleared in the transaction that ends the run.
    • once additionally writes an entry marker, unique on (workflow_id, customer_id), that is never removed when the run ends.
    • restart ends the active run (exited:restarted) before inserting the new row in the same transaction.
    • A unique violation from either index is the skip: the run is not created and a step-log reason is written.

Stop:

  • Stopping a workflow cancels its waiting runs (exited:workflow_stopped), moves its queued and waiting:plan_limit messages to skipped:workflow_stopped, and removes pending trigger fires and slots, in bounded batches. A message in sending, unknown, or accepted is left to the send state machine.
  • Each workflow has an activation epoch, incremented on every activation. A run and its messages record the epoch they started under. claimSend and tick treat a run whose epoch is not the workflow’s current epoch as stopped (exited:workflow_stopped), so a stop followed by a quick reactivation cannot release runs that the stop’s batches have not reached yet.
  • claimSend checks that the workflow is active in the run’s activation epoch, so a queued message of a stopped workflow is skipped. A message already in sending follows the send state machine (ADR 0011).
  • Publishing a new version switches the active version atomically; started runs stay pinned.
  • Replaying an event (as defined above), before or after republishing, cannot start a second run or send twice. Clients that may retry must send an idempotency key; the API docs say so.
  • The first engine code includes a test per policy proving that concurrent triggers cannot violate the invariant, and a test that a stop followed by reactivation cannot resume a run of the earlier epoch.
  • Users who want a drain-style stop can remove the trigger in a new version instead of stopping.

Amendment (2026-11-18, pending ADR 0044, Proposed): next to stop, a workflow can be paused (its sends wait, nothing is cancelled) and rolled back. Rollback makes the previous live version of the current activation epoch live again without changing the epoch (through a send approval where the workspace requires approval), and stops only the runs of the version it withdraws (exited:version_withdrawn), which the workflow record lists in withdrawnVersions. Stop also skips waiting:paused messages.

Amendment (2026-11-19, pending ADR 0047, Proposed): a run of a workflow with a goal waits in waiting:conversion_window after its last send step, for the workflow’s conversionWindow, ending completed or exited:goal_met. Its workflow_entries row stops being active when that wait begins, so re-entry policies treat the run as ended (the maintainer’s decision of 2026-11-20); stop and rollback end it like any waiting run.