How does a definition-based workflow state machine differ from code-first durable execution, and why must durable workflow code be deterministic?
answer
- where the control flow lives
- interpreter versus replayed code
- a history of recorded step results
- same decisions on every replay
- clock, randomness, I/O through the engine
basics
~20 sA definition-based engine interprets a declared state machine and saves state at each transition. Code-first durable execution runs ordinary workflow code and rebuilds its state by replaying recorded step results, so that code must make identical decisions on every replay.
solid answer
~50 sIn a **definition-based** engine the workflow is data: a state machine in JSON or YAML that the engine interprets, saving the execution's state after each transition. Control flow is limited to what the definition language offers (choices, waits, parallel branches, iteration). In **code-first durable execution** the workflow is a function in a general-purpose language; the engine records each step's result in an **execution history** and, after a pause or crash, rebuilds the code's local state by **replaying** it from the top against that history, handing back recorded results instead of running the steps again. Replay works only if the code is **deterministic**: given the same history it must request the same steps in the same order. So the current time, random values, new IDs, network calls and configuration reads go through the engine's APIs or into steps, whose results are recorded.
code
pseudocode · 14 linesworkflow publishDocument(documentId):
text = step("extractText", documentId) # result recorded in history
# WRONG: a direct clock read returns a new value on every replay
# if systemClock.now() > deadline: ...
receivedAt = engine.currentTime() # recorded once, identical on replay
reviewId = step("newReviewId") # random ID made inside a step
decision = waitForCallback("review", reviewId)
if decision.approved:
step("publish", documentId, text, receivedAt)
else:
step("notifyRejected", documentId, decision.reason)go deeper
Recall the two shapes: a declared state machine the engine interprets, and workflow code the engine replays against a recorded history.
Explain replay step by step and list what breaks determinism: direct clock reads, randomness, I/O and configuration reads outside steps.
Show how you keep a team deterministic in practice: review rules, replay tests against recorded histories, and diagnosing a non-determinism error from the history.
Weigh the definition language's limits and lock-in against putting determinism discipline on every developer who edits workflow code.
## Two ways to describe the same pipeline A hosted workflow engine coordinates steps that run as functions: extract the text of an uploaded document, wait for a reviewer, publish. Engines describe that coordination in one of two ways. | | Definition-based state machine | Code-first durable execution | |---|---|---| | What you write | A declarative definition (JSON or YAML) of states and transitions | A workflow function in a general-purpose language | | Who runs the control flow | The engine interprets the definition | Your code, re-run by a host process the engine drives | | How state survives a pause | The engine saves the execution's data after each transition | The engine keeps an event history and replays the code against it | | Flexibility of logic | Whatever the definition language offers | Loops, branches and helpers of a real language | | Main discipline | Fitting logic into the language's states | Keeping workflow code deterministic | | Testing | Engine tooling, often a local emulator | Ordinary unit tests plus replay tests | Both persist progress, both retry steps, and both can wait for days. The difference is **where the control flow lives** and **how the engine recovers it**. ## How replay works In code-first durable execution the engine does not snapshot memory. It records **events**: "step `extractText` was scheduled", "it returned this result", "a timer was started", "a callback arrived". When the workflow must continue (after a wait, after a crash, or when the hosting process moved), the engine rebuilds its state like this: 1. It starts the workflow function again from its first line with the original input. 2. Each time the code asks for a step, the engine checks the history. If that step already completed, it returns the **recorded result** immediately instead of running the step again. 3. The code reaches the point where the history ends, with every local variable exactly as before. 4. From there the code runs live: new step requests are executed and appended to the history. Steps therefore do not run twice because of replay. What runs again on every replay is the **workflow code between steps**, and that is why the code is constrained. ## The determinism rules Replay assumes that the same history produces the same sequence of step requests. The engine compares what the code asks for with what the history says it asked for last time; when they disagree, it raises a **non-determinism error** and the execution stops making progress. Anything that can return a different value on a second run breaks that assumption: - **Reading the clock directly.** `now()` differs on replay; use the engine's time API, whose value is recorded. - **Randomness and new IDs.** A random number or a freshly generated UUID differs each run; generate it in a step or through an engine API. - **Network and disk I/O.** A database read can return new data on replay; do I/O inside steps so the result is recorded once. - **Configuration and environment reads.** A flag flipped between runs sends the code down another branch; read it in a step. - **Iteration order** over unordered collections, and the language's own threads or sleeps, which the engine cannot record. - **Mutable global state** shared across executions in the hosting process. Definition-based engines do not replay your code, so these rules do not apply in that form; their equivalent discipline is that a state's input and output paths must match what the next state expects. ## When each fits - Choose a **definition-based** engine when flows are mostly wiring between functions and managed services, when operators want a visual graph of every execution, and when the definition language covers the branching you need. - Choose **code-first durable execution** when the logic is genuinely algorithmic (loops with conditions, dynamic fan-out, compensation chosen at runtime), when developers want ordinary tests and refactoring tools, and when the team will hold the determinism line in review. - Expect each to cost something: definition languages get awkward for complex logic and are specific to their engine, while code-first engines put correctness on every developer who touches workflow code. ## A note on history size Because every step, timer and callback appends events, histories grow. Many engines cap how many events one execution may hold, and replay time grows with history length. A long-running loop should periodically finish and start a fresh execution that carries its current state forward rather than accumulate history forever.
- Does replaying durable workflow code send a notification email a second time?Not if the email is sent inside a step. During replay the engine returns each completed step's recorded result without running the step again, so the email goes out once. If the code sends it directly between steps, it runs on every replay and the email repeats. That is the practical reason side effects belong in steps, never in workflow code.
- Why does a code-first workflow that loops for weeks eventually need to restart itself?Each iteration adds events to the execution history, many engines cap the number of events per execution, and replay gets slower as history grows. The usual fix is to end the execution after a batch of iterations and immediately start a fresh one with the current state as its input, so each history stays short.
- Durable workflow code can call any API directly because the engine retries it anyway.
- Replay re-executes every completed step, so steps always run twice after a crash.
- Reading the system clock in workflow code is harmless because it is only a read.
- Code-first and definition-based engines differ only in syntax, not in how state survives.
- The engine restores a memory snapshot, so any code is safe inside a durable workflow.