Workflow versioning
Because Catalyst Workflows persist execution history and replay it to reconstruct state, changes to workflow code must preserve determinism for in-flight executions.
Replay safety rules
When a workflow resumes after a crash or restart, the runtime replays all past events through the workflow code to reconstruct current state. If the code has changed in a way that produces different decisions on replay, the execution becomes inconsistent. Safe changes include:
- Adding new code paths that are not reached by in-flight instances.
- Adding new activities that only execute after the current checkpoint.
Unsafe changes include:
- Reordering existing activities.
- Removing activities that in-flight instances have already scheduled.
- Changing timer durations that existing instances have already set.
Versioning strategies
Version gates — use a version flag (passed as workflow input or read from a side-effect-free config) to branch the workflow code so old instances follow the old path and new instances follow the new path.
Drain and redeploy — wait until all in-flight instances of the old version complete (or terminate them explicitly), then deploy the new version. Use the Workflows console to monitor completion.
New workflow name — deploy the updated logic as a new workflow name and route new invocations there. Old instances continue running on the old name.
Stub — populate with concrete code examples and the full determinism rule set from the Dapr documentation.