temporalio__skill-temporal-developer/references/ruby/determinism-protection.md

Ruby Workflow Determinism Protection

Overview

The Ruby SDK uses two mechanisms to enforce workflow determinism:

1. Illegal Call Tracing -- TracePoint-based interception of forbidden method calls on the workflow fiber.
2. Durable Fiber Scheduler -- a custom Fiber::Scheduler that makes fiber operations deterministic.

This differs from Python's sandbox (SandboxedWorkflowRunner) and TypeScript's V8 isolate sandbox. Ruby's approach is runtime tracing, not code isolation.

How Illegal Call Tracing Works

A TracePoint is installed on the workflow fiber thread. On every :call and :c_call event, the SDK checks the receiver class and method name against a configurable set of illegal calls.

# Internally, the SDK does something like:
TracePoint.new(:call, :c_call) do |tp|
  if illegal?(tp.defined_class, tp.method_id)
    raise Temporalio::Workflow::NondeterminismError,
      "Illegal call: #{tp.defined_class}##{tp.method_id}"
  end
end

Key behaviors:

• Raises Temporalio::Workflow::NondeterminismError on violation.
• Detects transitive calls -- a gem calling IO.read deep in its internals will still be caught.
• Only active on the workflow fiber, not on activity threads or other fibers.

Forbidden Operations in Workflows

Default forbidden operations:

• Kernel.sleep -- use Temporalio::Workflow.sleep
• Time.now (no args) -- use Temporalio::Workflow.now
• Thread.new -- not allowed in workflows
• IO.* -- all IO class methods (IO.read, IO.write, IO.pipe, etc.)
• Socket.* -- all socket operations
• Net::HTTP.* -- all HTTP client calls
• Random.* -- use Temporalio::Workflow.random
• SecureRandom.* -- use Temporalio::Workflow.uuid for UUIDs
• Timeout.timeout -- use Temporalio::Workflow.sleep with cancellation
• Mutex / synchronize -- use an explicit Temporalio::Workflow::Mutex

Note: Time.new('2000-12-31') with arguments IS deterministic and allowed. Only Time.now (wall-clock) is forbidden.

Disabling Illegal Call Tracing

Use Temporalio::Workflow::Unsafe.illegal_call_tracing_disabled when third-party code is known safe:

class MyWorkflow < Temporalio::Workflow::Definition
  def execute
    # Third-party gem that does harmless Time.now internally
    result = Temporalio::Workflow::Unsafe.illegal_call_tracing_disabled do
      SomeGem.format_data(input)
    end
    result
  end
end

The block disables tracing only for its duration. Keep it as narrow as possible.

Customizing Illegal Calls

Pass illegal_workflow_calls: to Temporalio::Worker.new:

worker = Temporalio::Worker.new(
  client: client,
  task_queue: 'my-queue',
  workflows: [MyWorkflow],
  illegal_workflow_calls: Temporalio::Worker.default_illegal_workflow_calls.merge(
    'MyInternalClass' => :all,
    'AnotherClass' => { dangerous_method: true }
  )
)

Default set available via:

Temporalio::Worker.default_illegal_workflow_calls
# => { 'Kernel' => { sleep: true }, 'IO' => :all, ... }

Hash format:

• { 'ClassName' => :all } -- block all methods on the class.
• { 'ClassName' => { method_name: true } } -- block specific methods.

Common Issues

Third-party gems triggering NondeterminismError

Gems that call IO, Time.now, or Socket internally will trigger errors even if you don't call those methods directly. The correct fix is context-dependent and requires understanding and possibly debugging of the situation.

Fix 1: The call to a gem genuinely is doing IO, side effects, or other non-deterministic things. Then just like with other Temporal Workflow code, it should be moved into an activity.

Fix 2: Escape hatch: for code that needs IO to run within the workflow, use io_enabled. You should very seriously consider why IO is needed in the workflow and not in an activity. If you use this escape hatch to create non-determinism issues, you might later face non-determinism errors.

Temporalio::Workflow::Unsafe.io_enabled do
  config = YAML.load_file('config.yml')
end

Fix 3: Escape hatch: for code that triggers the illegal call tracing but doesn't cause actual non-determinism issues, you can disable illegal_call_tracing_disabled. Again, you must be sure that you are semantically correct that there is no non-determinism involved.

Temporalio::Workflow::Unsafe.illegal_call_tracing_disabled do
  ThirdPartyGem.safe_pure_computation(data)
end

Durable scheduler conflicts

If a gem requires its own fiber scheduler behavior, disable the durable scheduler for that block:

Temporalio::Workflow::Unsafe.durable_scheduler_disabled do
  some_fiber_aware_gem.call
end

Best Practices

• Use Temporalio::Workflow.sleep, .now, .random, .uuid, .logger for all workflow-level operations.
• Never perform IO, network calls, or file access in workflow code -- delegate to activities.
• Use illegal_call_tracing_disabled sparingly and only when you are certain the code is deterministic.
• Wrap side-effect-only code in unless Temporalio::Workflow::Unsafe.replaying? to avoid duplicate emissions during replay.
• Prefer activities over io_enabled blocks -- activities have proper retry, timeout, and heartbeat semantics.