Add Ruby SDK support

SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: temporal-developer
-description: Develop, debug, and manage Temporal applications across Python, TypeScript, Go, Java and .NET. Use when the user is building workflows, activities, or workers with a Temporal SDK, debugging issues like non-determinism errors, stuck workflows, or activity retries, using Temporal CLI, Temporal Server, or Temporal Cloud, or working with durable execution concepts like signals, queries, heartbeats, versioning, continue-as-new, child workflows, or saga patterns.
+description: Develop, debug, and manage Temporal applications across Python, TypeScript, Go, Java, .NET and Ruby. Use when the user is building workflows, activities, or workers with a Temporal SDK, debugging issues like non-determinism errors, stuck workflows, or activity retries, using Temporal CLI, Temporal Server, or Temporal Cloud, or working with durable execution concepts like signals, queries, heartbeats, versioning, continue-as-new, child workflows, or saga patterns.
 version: 0.4.0
 ---
 
 # Skill: temporal-developer
 
 ## Overview
 
-Temporal is a durable execution platform that makes workflows survive failures automatically. This skill provides guidance for building Temporal applications in Python, TypeScript, Go, Java and .NET.
+Temporal is a durable execution platform that makes workflows survive failures automatically. This skill provides guidance for building Temporal applications in Python, TypeScript, Go, Java, .NET, and Ruby.
 
 ## Core Architecture
 
@@ -58,6 +58,7 @@ Check if `temporal` CLI is installed. If not, follow the instructions at `refere
    - Go -> read `references/go/go.md`
    - Java -> read `references/java/java.md`
    - .NET (C#) -> read `references/dotnet/dotnet.md`
+   - Ruby -> read `references/ruby/ruby.md`
 2. Second, read appropriate `core` and language-specific references for the task at hand.
 
 ## Primary References

references/core/determinism.md

@@ -89,6 +89,7 @@ Each Temporal SDK language provides a different level of protection against non-
 - Java: The Java SDK has no sandbox. Determinism is enforced by developer conventions — the SDK provides `Workflow.*` APIs as safe alternatives (e.g., `Workflow.sleep()` instead of `Thread.sleep()`), and non-determinism is only detected at replay time via `NonDeterministicException`. A static analysis tool (`temporal-workflowcheck`, beta) can catch violations at build time. Cooperative threading under a global lock eliminates the need for synchronization.
 - Go: The Go SDK has no runtime sandbox. Therefore, non-determinism bugs will never be immediately appararent, and are usually only observable during replay. The optional `workflowcheck` static analysis tool can be used to check for many sources of non-determinism at compile time.
 - .NET: The .NET SDK has no sandbox. It uses a custom TaskScheduler and a runtime EventListener to detect invalid task scheduling. Developers must use `Workflow.*` safe alternatives (e.g., Workflow.DelayAsync instead of Task.Delay) and avoid non-deterministic .NET Task APIs.
+- Ruby: The Ruby SDK uses Illegal Call Tracing (via `TracePoint`) to detect forbidden method calls at runtime on the workflow fiber, combined with a Durable Fiber Scheduler that makes fiber operations deterministic.
 
 Regardless of which SDK you are using, it is your responsibility to ensure that workflow code does not contain sources of non-determinism. Use SDK-specific tools as well as replay tests for doing so.
 

references/ruby/advanced-features.md

@@ -0,0 +1,247 @@
+# Ruby SDK Advanced Features
+
+## Schedules
+
+Create recurring workflow executions with `Temporalio::Client::Schedule`.
+
+```ruby
+require 'temporalio/client'
+
+# Create a schedule
+schedule_id = 'daily-report'
+client.create_schedule(
+  schedule_id,
+  Temporalio::Client::Schedule.new(
+    action: Temporalio::Client::Schedule::Action::StartWorkflow.new(
+      DailyReportWorkflow,
+      id: 'daily-report',
+      task_queue: 'reports'
+    ),
+    spec: Temporalio::Client::Schedule::Spec.new(
+      intervals: [
+        Temporalio::Client::Schedule::Spec::Interval.new(every: 86_400) # 1 day in seconds
+      ]
+    )
+  )
+)
+
+# Manage schedules
+handle = client.schedule_handle(schedule_id)
+handle.pause(note: 'Maintenance window')
+handle.unpause
+handle.trigger
+handle.delete
+```
+
+## Async Activity Completion
+
+For activities that complete asynchronously (e.g., human tasks, external callbacks).
+
+**Note:** If the external system that completes the asynchronous action can reliably be trusted to do the task and Signal back with the result, and it doesn't need to Heartbeat or receive Cancellation, then consider using **signals** instead.
+
+```ruby
+class RequestApproval < Temporalio::Activity::Definition
+  def execute(request_id)
+    # Get task token for async completion
+    task_token = Temporalio::Activity::Context.current.info.task_token
+
+    # Store task token for later completion (e.g., in database)
+    store_task_token(request_id, task_token)
+
+    # Signal that this activity completes asynchronously
+    Temporalio::Activity::Context.current.raise_complete_async
+  end
+end
+
+# Later, complete the activity from another process
+client = Temporalio::Client.connect('localhost:7233')
+task_token = get_task_token(request_id)
+handle = client.async_activity_handle(task_token: task_token)
+
+if approved
+  handle.complete('approved')
+else
+  handle.fail(Temporalio::Error::ApplicationError.new('Rejected'))
+end
+```
+
+If you configure a `heartbeat_timeout:` on the activity, the external completer is responsible for sending heartbeats via the async handle. If you do NOT set a `heartbeat_timeout`, no heartbeats are required.
+
+## Worker Tuning
+
+Configure worker performance settings.
+
+```ruby
+worker = Temporalio::Worker.new(
+  client: client,
+  task_queue: 'my-queue',
+  workflows: [MyWorkflow],
+  activities: [MyActivity],
+  # Max concurrent execution slots (default 100 each): how many workflow tasks
+  # and activities run at once on this worker.
+  tuner: Temporalio::Worker::Tuner.create_fixed(
+    workflow_slots: 100,
+    activity_slots: 100
+  ),
+  # Grace period (seconds) after shutdown is requested before in-progress
+  # activities are canceled. Defaults to 0 (cancel immediately on shutdown).
+  graceful_shutdown_period: 30
+)
+worker.run
+```
+
+On shutdown the worker stops polling for new tasks and cancels the `worker_shutdown_cancellation` on each running activity's context. After `graceful_shutdown_period` seconds it then issues actual cancellation to any still-running activities. The worker will not finish shutting down until all in-progress activities complete, so activities that ignore cancellation can block shutdown indefinitely.
+
+## Workflow Init Decorator
+
+Always initialize workflow state before signals/updates arrive. Signal and Update handlers can run *before* the main `execute` method -- for example with Signal-with-Start, when the Task Queue is backlogged, or right after continue-as-new -- so a handler may otherwise read uninitialized instance variables.
+
+Normally `initialize` must accept no required arguments. If you place the `workflow_init` class method directly above `initialize`, the constructor receives the same workflow arguments that `execute` receives (the same input the Client sent). It is guaranteed to run before any handler.
+
+```ruby
+class GreetingWorkflow < Temporalio::Workflow::Definition
+  workflow_init
+  def initialize(input)
+    # Runs before any signal/update handler
+    @name_with_title = "Sir #{input['name']}"
+    @title_has_been_checked = false
+  end
+
+  def execute(input)
+    Temporalio::Workflow.wait_condition { @title_has_been_checked }
+    "Hello, #{@name_with_title}"
+  end
+
+  workflow_update
+  def check_title_validity
+    # Guaranteed to see workflow input, since initialize ran first
+    valid = Temporalio::Workflow.execute_activity(
+      CheckTitleValidityActivity,
+      @name_with_title,
+      start_to_close_timeout: 100
+    )
+    @title_has_been_checked = true
+    valid
+  end
+end
+```
+
+`initialize` (with `workflow_init`) and `execute` must have the same parameters with the same types. You cannot make blocking calls (activities, sleeps, etc.) from `initialize`.
+
+## Workflow Failure Exception Types
+
+Control which exceptions cause workflow failure vs workflow task failure (which Temporal retries automatically).
+
+### Per-Workflow Configuration
+
+```ruby
+class MyWorkflow < Temporalio::Workflow::Definition
+  # Class method approach
+  def self.workflow_failure_exception_type
+    MyCustomError
+  end
+
+  def execute
+    raise MyCustomError, 'This fails the workflow, not just the task'
+  end
+end
+```
+
+### Worker-Level Configuration
+
+```ruby
+Temporalio::Worker.new(
+  client: client,
+  task_queue: 'my-queue',
+  workflows: [MyWorkflow],
+  workflow_failure_exception_types: [MyCustomError]
+)
+```
+
+**Tips:**
+- Set to `[Exception]` in tests so any unhandled exception fails the workflow immediately rather than retrying the workflow task forever. Surfaces bugs faster.
+- Include `Temporalio::Workflow::NondeterminismError` to fail the workflow instead of leaving it in a retrying state on non-determinism errors.
+
+## Activity Concurrency and Executors
+
+Ruby uses `Temporalio::Worker::ActivityExecutor::ThreadPool` by default. Activities run in a thread pool.
+
+```ruby
+# Default: activities run in thread pool
+worker = Temporalio::Worker.new(
+  client: client,
+  task_queue: 'my-queue',
+  workflows: [MyWorkflow],
+  activities: [MyActivity],
+  activity_executors: {
+    default: Temporalio::Worker::ActivityExecutor::ThreadPool.new(max_threads: 20)
+  }
+)
+```
+
+Fiber-based execution is also possible for IO-bound activities using Ruby's fiber scheduler.
+
+## Rails Integration
+
+### ActiveRecord Considerations
+
+Never pass ActiveRecord models directly to Temporal workflows or activities. Serialize to plain data structures.
+
+```ruby
+# BAD - Passing AR model
+client.execute_workflow(
+  ProcessOrderWorkflow,
+  Order.find(42),  # Don't pass AR objects!
+  id: 'order-42',
+  task_queue: 'orders'
+)
+
+# GOOD - Pass serializable data
+client.execute_workflow(
+  ProcessOrderWorkflow,
+  { id: 42, total: order.total, status: order.status },
+  id: 'order-42',
+  task_queue: 'orders'
+)
+```
+
+### Zeitwerk and Autoloading
+
+Rails autoloading can result in unexpected I/O during replay. `config.eager_load` must be enabled or Workflows must explicitly require code dependencies before they are executed. Usually the easiest place to do that is when starting the worker, and requiring all activities and workflows that the worker needs *before* starting the worker. For example:
+
+```ruby
+require "temporal_client"
+require "temporalio/worker"
+require "workflows/shopping_cart_activities.rb"
+require "workflows/shopping_cart_workflow.rb"
+
+worker = Temporalio::Worker.new(
+  client: TemporalClient.instance,
+  task_queue: TemporalClient.task_queue,
+  activities: [
+    Workflows::ShoppingCartActivities::FetchProducts,
+    ...
+  ],
+  workflows: [ Workflows::ShoppingCartWorkflow ]
+)
+worker.run
+```
+
+### Forking Considerations
+
+If using a forking server (Puma, Unicorn), workers must be created **after** the fork. Connections established before fork are not safe to share across processes.
+
+```ruby
+# In Puma config (puma.rb)
+before_worker_boot do
+  # Create Temporal client and worker AFTER fork
+  client = Temporalio::Client.connect('localhost:7233')
+  worker = Temporalio::Worker.new(
+    client: client,
+    task_queue: 'my-queue',
+    workflows: [MyWorkflow],
+    activities: [MyActivity]
+  )
+  Thread.new { worker.run }
+end
+```