Skip to content

determinism.md

Latest commit

 

History

History
117 lines (80 loc) · 5 KB

determinism.md

File metadata and controls

117 lines (80 loc) · 5 KB

Determinism in Temporal Workflows

This document provides a conceptual-level overview to determinism in Temporal. Additional language-specific determinism information is available at references/{your_language}/determinism.md.

Overview

Temporal workflows must be deterministic because of history replay - the mechanism that enables durable execution.

Why Determinism Matters

The Replay Mechanism

When a Worker needs to restore workflow state (after crash, cache eviction, or continuing after a long timer), it re-executes the workflow code from the beginning. But instead of re-running external actions, it uses results stored in the Event History.

Initial Execution:
  Code runs → Generates Commands → Server stores as Events

Replay (Recovery):
  Code runs again → Generates Commands → SDK compares to Events
  If match: Use stored results, continue
  If mismatch: NondeterminismError!

Commands and Events

Every workflow operation generates a Command that becomes an Event, here are some examples:

Workflow Code Command Generated Event Stored
Execute activity ScheduleActivityTask ActivityTaskScheduled
Sleep/timer StartTimer TimerStarted
Child workflow StartChildWorkflowExecution ChildWorkflowExecutionStarted
Complete workflow CompleteWorkflowExecution WorkflowExecutionCompleted

Non-Determinism Example

First Run (11:59 AM):
  if datetime.now().hour < 12:  → True
    execute_activity(morning_task)  → Command: ScheduleActivityTask("morning_task")

Replay (12:01 PM):
  if datetime.now().hour < 12:  → False
    execute_activity(afternoon_task)  → Command: ScheduleActivityTask("afternoon_task")

Result: Commands don't match history → NondeterminismError

Sources of Non-Determinism

Time-Based Operations

  • datetime.now(), time.time(), Date.now()
  • Different value on each execution

Random Values

  • random.random(), Math.random(), uuid.uuid4()
  • Different value on each execution

External State

  • Reading files, environment variables, databases, networking / HTTP calls
  • State may change between executions

Non-Deterministic Iteration

  • Map/dict iteration order (in some languages)
  • Set iteration order

Threading/Concurrency

  • Race conditions produce different outcomes
  • Non-deterministic ordering

Central Concept: Place Non-Determinism within Activities

In Temporal, activities are the primary mechanism for making non-deterministic code durable and persisted in workflow history. Generally speaking, you should place sources of non-determinism in activities, which provides durability and recording of results, as well as automated retries and more. See references/{your_language}/{your_language}.md for the language you are working in for how to do this in practice.

For a few simple cases, like timestamps, random values, UUIDs, etc. the Temporal SDK in your language may provide durable variants that are simple to use. See references/{your_language}/determinism.md for the language you are working in for more info.

SDK Protection Mechanisms

Each Temporal SDK language provides a protection mechanism to make it easier to catch non-determinism errors earlier in development:

  • Python: The Python SDK runs workflows in a sandbox that intercepts and aborts non-deterministic calls at runtime.
  • TypeScript: The TypeScript SDK runs workflows in an isolated V8 sandbox, intercepting many common sources of non-determinism and replacing them automatically with deterministic variants.
  • PHP: The PHP SDK performs runtime checks that detect adding, removing, or reordering of commands (activity calls, timers, child workflows, etc.). It does NOT have a sandbox — developers must be disciplined about avoiding non-deterministic operations in workflow code.

Detecting Non-Determinism

During Execution

  • NondeterminismError raised when Commands don't match Events
  • Workflow becomes blocked until code is fixed

Testing with Replay

Replay tests verify that workflows follow identical code paths when re-run, by attempting to replay recorded executions. See the replay testing section of references/{your_language}/testing.md for information on how to write these tests.

Recovery from Non-Determinism

Accidental Change

If you accidentally introduced non-determinism:

  1. Revert code to match what's in history
  2. Restart worker
  3. Workflow auto-recovers

Intentional Change

If you need to change workflow logic:

  1. Use the Patching API to support both old and new code paths
  2. Or terminate old workflows and start new ones with updated code

See versioning.md for patching details.

Best Practices

  1. Use SDK-provided alternatives for time, random, UUID
  2. Move I/O to activities - workflows should only orchestrate
  3. Test with replay before deploying workflow changes
  4. Use patching for intentional changes to running workflows
  5. Keep workflows focused - complex logic increases non-determinism risk