Guides

Determinism Rules


Workflow code must be deterministic — meaning it must produce the same sequence of context calls every time it executes with the same inputs. This is a fundamental requirement, not a suggestion.

The reason is replay. When a workflow resumes after a crash, the runtime re-executes your workflow function from the beginning. It matches each context call to a journal entry by sequence number: the first execute_task in your code corresponds to journal entry #1, the second to #2, and so on. If replay encounters a different sequence of calls than the original execution, the journal entries won't match and the workflow will fail with a non-determinism error.

What is Safe

Any operation that produces the same result every time is safe to use directly in workflow code:

  • Pure computation — math, string manipulation, data transformation
  • Context methods — execute_task, execute, sleep, wait_for_event, execute_child_workflow (these are journaled)
  • Branching on task results — if/else based on journaled values is safe because the same journaled values will be replayed
1
use orcher::prelude::*;
2
use anyhow::Result;
3
use std::time::Duration;
4
5
#[workflow(name = "safe_workflow", version = "1.0.0")]
6
pub async fn safe_workflow(
7
ctx: WorkflowContext,
8
input: MyInput,
9
) -> Result<String> {
10
// Safe: Pure computation (same input always gives same output)
11
let computed = input.amount * 2;
12
13
// Safe: Using task execution (result is journaled)
14
let result: String = ctx
15
.execute_task(get_data, ())
16
.await?;
17
18
// Safe: Using workflow context (sleep is journaled)
19
ctx.sleep(Duration::from_secs(60)).await?;
20
21
Ok(result)
22
}

What is NOT Safe

Operations that can return different values on each execution will break replay. These must always be wrapped in tasks:

  • Current time — DateTime::now(), new Date(), datetime.now() return different values on replay. If you need the current time, get it inside a task and return it as a result.
  • Random values — rand::random(), Math.random(), random.randint() produce different values on each call. Wrap randomness in a task.
  • UUIDs — UUID generation is random. Generate UUIDs inside tasks.
  • Direct I/O — Network calls, file reads, database queries outside of tasks are not journaled. If the result differs on replay, your workflow will diverge.
1
use orcher::prelude::*;
2
use anyhow::Result;
3
use std::time::SystemTime;
4
use rand::Rng;
5
6
#[workflow(name = "unsafe_workflow", version = "1.0.0")]
7
pub async fn unsafe_workflow(
8
ctx: WorkflowContext,
9
_input: MyInput,
10
) -> Result<String> {
11
// UNSAFE: Current time changes on replay
12
let now = SystemTime::now();
13
14
// UNSAFE: Random values differ on replay
15
let random = rand::thread_rng().gen::<u32>();
16
17
// UNSAFE: Direct network call (not journaled)
18
let response = reqwest::get("https://api.example.com").await?;
19
20
// CORRECT: Use execute() or execute_task() for all external interactions
21
let result: String = ctx
22
.execute("fetch_data", || async {
23
let resp = reqwest::get("https://api.example.com").await?;
24
Ok(resp.text().await?)
25
})
26
.await?;
27
28
Ok(result)
29
}

Next Steps