ruby_reactor 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3ddfd9b6e65d03e5c00d7980563da39b4132fc1d5f0dbe14e5b782d039c7f68
-  data.tar.gz: 785cc8ac8d426433a00f378eafb8f312b343950ecf496e2af0a6fe9e48115c29
+  metadata.gz: de5c91a5450cb522097965aa4348760438b60babd05da33f9f7ec1a07fe9bd07
+  data.tar.gz: d565e81c6ba6e057b56912311bf16dee95ce0c441eb76f2b893658b751568b2c
 SHA512:
-  metadata.gz: 549a49deff5d63e129c0b4c043cbc3987dbbb09b054907a5acb8941af85fedb5f9706bad8d56948bbc7ea889eba19174254962ca987e7835b4cd0a7bf3f9e165
-  data.tar.gz: 319399c2854cccb505fc7e8f6c964eeeb527bad375ed513b1a2c2ea89b77445283f287bbff5a0892902a56a5a56b5a9aff105a0164006abf407473ad3780a58d
+  metadata.gz: dde49e045303aeb4bcf414ea30b7d85d8fb8a782f873dd9ebb4a9d7d0524e74de37ba4e53ddc11ac6dea360bf1226f946d0c50e74e685da2ac70394065f436d6
+  data.tar.gz: 7b9b0b5bf75866876bdc1811dfc1118272963337431148f480d6570e19bfc2e9d93a6fdfd91a3629734501a590e23be579b98ff2e2f4f125831410351e0e6865

data/README.md

@@ -24,6 +24,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 - **Compensation**: Automatic rollback of completed steps when a failure occurs.
 - **Interrupts**: Pause and resume workflows to wait for external events (webhooks, user approvals).
 - **Input Validation**: Integrated with `dry-validation` for robust input checking.
+- **Distributed Locks, Semaphores, Rate Limits & Periods**: Coordinate across processes with Redis-backed primitives — exclusive locks for at-most-one-runner, semaphores for capacity caps, fixed-window rate limits for external APIs (single or multi-window like "3/sec AND 100/min"), and `with_period` to dedup reactors to once per calendar bucket (once per day/month/year/etc). Async jobs snooze on contention with smart `retry_after` instead of consuming retry budget.
 
 ## Comparison
 
@@ -32,6 +33,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 | DAG/Parallel execution   | Yes          | No              | Limited     | Manual              |
 | Auto compensation/undo   | Yes          | No              | Manual      | Manual              |
 | Interrupts (pause/resume)| Yes          | No              | No          | Manual              |
+| Locks / sem / rate / per | Yes          | No              | No          | Manual              |
 | Built-in web dashboard   | Yes          | No              | No          | No                  |
 | Async with Sidekiq       | Yes          | No              | Limited     | Yes                 |
 
@@ -56,6 +58,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
     - [Full Reactor Async](#full-reactor-async)
     - [Step-Level Async](#step-level-async)
   - [Interrupts (Pause & Resume)](#interrupts-pause--resume)
+  - [Locks & Semaphores](#locks--semaphores)
   - [Map & Parallel Execution](#map--parallel-execution)
     - [Map with Dynamic Source (ActiveRecord)](#map-with-dynamic-source-activerecord)
   - [Input Validation](#input-validation)
@@ -99,7 +102,14 @@ RubyReactor.configure do |config|
   # Sidekiq configuration for async execution
   config.sidekiq_queue = :default
   config.sidekiq_retry_count = 3
-  
+
+  # Lock contention snooze behavior for async reactors. When a Sidekiq worker
+  # cannot acquire a lock or semaphore, it re-enqueues itself with this delay
+  # (plus jitter) up to `lock_snooze_max_attempts` times before giving up.
+  config.lock_snooze_base_delay = 5
+  config.lock_snooze_jitter = 5
+  config.lock_snooze_max_attempts = 20
+
   # Logger configuration
   config.logger = Logger.new($stdout)
 end
@@ -159,7 +169,7 @@ class UserRegistrationReactor < RubyReactor::Reactor
 
     run do |args, context|
       if args[:email] && args[:email].include?('@')
-        Success(args[:email].trim)
+        Success(args[:email].strip)
       else
         Failure("Email must contain @")
       end
@@ -191,8 +201,9 @@ class UserRegistrationReactor < RubyReactor::Reactor
       Success(user)
     end
 
-    conpensate do |error, args, context|
+    compensate do |error, args, context|
       Notify.to(args[:email])
+      Success()
     end
   end
 
@@ -200,8 +211,8 @@ class UserRegistrationReactor < RubyReactor::Reactor
     argument :email, result(:validate_email)
     wait_for :create_user
 
-    run do |args, _context| 
-      Email.sent!(args[:email], "verify your email")
+    run do |args, _context|
+      Email.send!(args[:email], "verify your email")
       Success()
     end
 
@@ -326,6 +337,99 @@ ApprovalReactor.continue_by_correlation_id(
 )
 ```
 
+### Locks & Semaphores
+
+Coordinate across processes with Redis-backed primitives:
+
+- **`with_lock`** — at-most-one runner per key at a time (concurrency control).
+- **`with_semaphore`** — cap total concurrent runners per key (capacity control).
+- **`with_rate_limit`** — fixed-window rate limit, single or multi-window ("3/sec AND 100/min").
+- **`with_period`** — run at most once per calendar bucket (dedup / once-per-day, once-per-month, etc).
+
+```ruby
+class RefundOrderReactor < RubyReactor::Reactor
+  input :order_id
+
+  # Only one refund per order at a time. Auto-extend keeps the TTL fresh while
+  # the reactor runs, so long steps cannot let the lock expire mid-flight.
+  with_lock(ttl: 60) { |inputs| "order:#{inputs[:order_id]}" }
+
+  step :refund do
+    argument :order_id, input(:order_id)
+    run { |args| PaymentGateway.refund(args[:order_id]) }
+  end
+end
+
+class GeocodeReactor < RubyReactor::Reactor
+  input :address
+
+  # At most 5 geocode calls in flight across the fleet.
+  with_semaphore(limit: 5) { |inputs| "geocode_api" }
+
+  step :geocode do
+    argument :address, input(:address)
+    run { |args| Geocoder.lookup(args[:address]) }
+  end
+end
+
+class MonthlyBillingReactor < RubyReactor::Reactor
+  input :org_id
+
+  # Run at most once per UTC month per org. Subsequent calls in the same month
+  # return RubyReactor::Skipped without executing any step. Pair with
+  # with_lock for strict at-most-one even under concurrent racers.
+  with_period(every: :month) { |inputs| "monthly_billing:#{inputs[:org_id]}" }
+
+  step :build do
+    argument :org_id, input(:org_id)
+    run { |args| Billing.generate(args[:org_id]) }
+  end
+end
+
+class ChargeReactor < RubyReactor::Reactor
+  input :account_id
+
+  # Respect upstream Stripe rate limits: 3/sec and 100/min.
+  # Async workers snooze for exactly retry_after seconds instead of
+  # consuming Sidekiq retry budget.
+  with_rate_limit(
+    limits: { second: 3, minute: 100 }
+  ) { |inputs| "stripe:#{inputs[:account_id]}" }
+
+  step :charge do
+    argument :account_id, input(:account_id)
+    run { |args| Stripe.charge(args[:account_id]) }
+  end
+end
+```
+
+On contention:
+
+- **Inline** (`Reactor.run`) raises `RubyReactor::Lock::AcquisitionError` / `RubyReactor::Semaphore::AcquisitionError` / `RubyReactor::RateLimit::ExceededError`.
+- **Async** (Sidekiq) snoozes the job via `perform_in(delay, ...)`. For rate limits the delay is the error's `retry_after_seconds` (precise wakeup); for locks/semaphores it's `lock_snooze_base_delay + jitter`. Snoozes do not count against the Sidekiq retry budget. After `lock_snooze_max_attempts` snoozes the context is marked failed.
+
+On dedup hits (period gate already marked), the reactor returns a `RubyReactor::Skipped` result instead — no steps run, no exception:
+
+```ruby
+result = MonthlyBillingReactor.run(org_id: 42)
+result.success?  # true (Skipped is a Success subclass)
+result.skipped?  # true on dedup hit, false otherwise
+```
+
+A step's `run` block can also return `RubyReactor.Skipped(reason: "...")` to halt the reactor cleanly — remaining steps don't execute, **and already-completed steps are NOT compensated**. Use it when the rest of the workflow is unnecessary and partial progress should be kept (`Failure` is for "stop and roll back").
+
+```ruby
+step :ensure_active do
+  argument :user, result(:fetch_user)
+  run do |args|
+    next RubyReactor.Skipped(reason: "user_opted_out") if args[:user].opted_out?
+    RubyReactor.Success(args[:user])
+  end
+end
+```
+
+See [Locks, Semaphores, Rate Limits & Periods](documentation/locks_and_semaphores.md) for re-entrancy, auto-extend, multi-window quotas, bucket semantics, owner identity, snooze tuning, and operational notes.
+
 ### Map & Parallel Execution
 
 Process collections in parallel using the `map` step:
@@ -733,6 +837,10 @@ Learn how to pause and resume reactors to handle long-running processes, manual
 ### [Testing with RSpec](documentation/testing.md)
 Comprehensive guide to testing reactors with RubyReactor's testing utilities. Learn about the `TestSubject` class for reactor execution and introspection, step mocking for isolating dependencies, testing nested and composed reactors, and custom RSpec matchers like `be_success`, `have_run_step`, and `have_retried_step`.
 
+### [Locks, Semaphores, Rate Limits & Periods](documentation/locks_and_semaphores.md)
+
+Coordinate access to shared resources across processes with Redis-backed primitives: exclusive locks (`with_lock`), concurrency-limiting semaphores (`with_semaphore`), fixed-window rate limits with multi-window quotas (`with_rate_limit`), and calendar-bucketed dedup (`with_period`, returning `Skipped` results). Covers re-entrancy across composed reactors, TTL auto-extend, inline-vs-async contention behavior, smart `retry_after` snoozes for rate limits, snooze tuning, the token-based semaphore safety model, and once-per-day/month/year scheduling patterns.
+
 ### Examples
 - [Order Processing](documentation/examples/order_processing.md) - Complete order processing workflow example
 - [Payment Processing](documentation/examples/payment_processing.md) - Payment handling with compensation
@@ -755,6 +863,7 @@ Comprehensive guide to testing reactors with RubyReactor's testing utilities. Le
   - [X] Sidekiq
   - [ ] ActiveJob
 - [ ] OpenTelemetry support
+- [X] locks
 
 ## Development
 

data/documentation/README.md

@@ -8,13 +8,15 @@ RubyReactor is a powerful Ruby framework for building reliable, sequential busin
 - [Core Concepts](core_concepts.md)
 - [DAG Execution and Saga Patterns](DAG.md)
 - [Async Reactors](async_reactors.md)
+- [Composition](composition.md)
+- [Data Pipelines](data_pipelines.md)
 - [Retry Configuration](retry_configuration.md)
-- [Migration Guide](migration_guide.md)
+- [Interrupts](interrupts.md)
+- [Testing with RSpec](testing.md)
 - [Examples](examples/)
   - [Order Processing](examples/order_processing.md)
   - [Payment Processing](examples/payment_processing.md)
   - [Inventory Management](examples/inventory_management.md)
-- [API Reference](api_reference.md)
 
 ## Quick Start
 
@@ -22,21 +24,30 @@ RubyReactor is a powerful Ruby framework for building reliable, sequential busin
 require 'ruby_reactor'
 
 class OrderProcessingReactor < RubyReactor::Reactor
+  input :order_id
+
   step :validate_order do
-    run { validate_order_logic }
+    argument :order_id, input(:order_id)
+    run { |args, _ctx| Success(Order.find(args[:order_id])) }
   end
 
   step :process_payment do
-    run { process_payment_logic }
+    argument :order, result(:validate_order)
+    run { |args, _ctx| Success(PaymentService.charge(args[:order])) }
   end
 
   step :send_confirmation do
-    run { send_email_confirmation }
+    argument :order, result(:validate_order)
+    run { |args, _ctx| Success(EmailService.send(args[:order])) }
   end
+
+  returns :process_payment
 end
 
 # Execute synchronously
 result = OrderProcessingReactor.run(order_id: 123)
+result.success? # => true
+result.value    # => payment result
 ```
 
 ## Key Features
@@ -106,9 +117,10 @@ RubyReactor provides comprehensive error handling:
 
 ## Requirements
 
-- Ruby 2.7+
-- Redis (for async execution)
+- Ruby 3.0+
+- Redis (for async execution and state persistence)
 - Sidekiq (for background processing)
+- dry-validation (optional, for input/payload validation)
 
 ## Installation
 
@@ -120,4 +132,4 @@ gem 'ruby_reactor'
 
 ## Contributing
 
-See [CONTRIBUTING.md](../CONTRIBUTING.md) for development setup and contribution guidelines.
+Bug reports and pull requests are welcome at <https://github.com/arturictus/ruby_reactor>. See the root [README](../README.md#contributing) for development setup.

data/documentation/async_reactors.md

@@ -41,20 +41,21 @@ end
 # Synchronous call returns immediately
 async_result = OrderProcessingReactor.run(order_id: 123)
 
-# Check status later
-case async_result.status
-when :pending
-  puts "Execution is queued"
-when :running
-  puts "Execution is in progress"
-when :success
-  puts "Execution completed successfully"
-  result = async_result.result
-when :failed
-  puts "Execution failed: #{async_result.error}"
+async_result.execution_id       # UUID for reloading state
+async_result.intermediate_results # Whatever was computed before handoff
+
+# Inspect status later by reloading from storage
+reactor = OrderProcessingReactor.find(async_result.execution_id)
+case reactor.context.status.to_s
+when "running"   then puts "Execution is in progress"
+when "completed" then puts "Done: #{reactor.result.value}"
+when "failed"    then puts "Failed: #{reactor.result.error}"
+when "paused"    then puts "Waiting on interrupt"
 end
 ```
 
+> **Note:** `AsyncResult` itself does not poll. It only carries the job handle and any results computed before handoff (`job_id`, `execution_id`, `intermediate_results`). To check progress, reload via `Reactor.find(execution_id)` and inspect `context.status`, or use the web dashboard.
+
 ### Architecture
 
 ```mermaid
@@ -85,26 +86,28 @@ Individual steps can be marked as `async: true`. Execution runs synchronously un
 class OrderProcessingReactor < RubyReactor::Reactor
   step :validate_order do
     # Runs synchronously
-    run { validate_order_logic }
+    run { |args, _ctx| validate_order_logic(args) }
   end
 
-  step :process_payment, async: true do
-    # First async step - triggers handoff to worker
-    run { process_payment_logic }
+  step :process_payment do
+    async true # First async step — triggers handoff to worker
+    run { |args, _ctx| process_payment_logic(args) }
   end
 
   step :update_inventory do
     # Runs in worker after handoff
-    run { update_inventory_logic }
+    run { |args, _ctx| update_inventory_logic(args) }
   end
 
   step :send_confirmation do
     # Runs in same worker
-    run { send_confirmation_logic }
+    run { |args, _ctx| send_confirmation_logic(args) }
   end
 end
 ```
 
+> **DSL note:** `async` is declared inside the step block (`async true`), not as a keyword on `step :name, async: true`. The `step` method only accepts a step name and an optional implementation class as positional arguments.
+
 ### Execution Flow
 
 ```ruby
@@ -244,17 +247,18 @@ class PaymentProcessingReactor < RubyReactor::Reactor
 
   step :validate_payment do
     retries max_attempts: 3, backoff: :exponential, base_delay: 1.second
-    run { validate_payment_logic }
+    run { |args, _ctx| validate_payment_logic(args) }
   end
 
-  step :charge_card, async: true do
+  step :charge_card do
+    async true
     retries max_attempts: 5, backoff: :linear, base_delay: 5.seconds
-    run { charge_card_logic }
+    run { |args, _ctx| charge_card_logic(args) }
   end
 
   step :update_records do
     # No retry - critical step
-    run { update_records_logic }
+    run { |args, _ctx| update_records_logic(args) }
   end
 end
 ```
@@ -298,25 +302,30 @@ class OrderProcessingReactor < RubyReactor::Reactor
   async true
 
   step :process_payment do
-    run { process_payment_logic }
+    argument :order, result(:validate_order)
+    run { |args, _ctx| process_payment_logic(args[:order]) }
 
-    undo do |payment_id:, **|
-      # Runs in worker if execution fails later
-      PaymentService.refund(payment_id)
+    undo do |result, _args, _ctx|
+      # Runs in worker when a LATER step fails
+      PaymentService.refund(result[:payment_id])
+      Success()
     end
 
-    compensate do |payment_id:, **|
-      # Runs in worker if execution fails later
-      PaymentService.refund(payment_id)
+    compensate do |error, args, _ctx|
+      # Runs in worker if THIS step fails
+      AuditService.log_payment_failure(args[:order].id, error.message)
+      Success()
     end
   end
 
   step :update_inventory do
-    run { update_inventory_logic }
+    argument :order, result(:validate_order)
+    run { |args, _ctx| update_inventory_logic(args[:order]) }
 
-    compensate do |order:, **|
+    compensate do |_error, args, _ctx|
       # Runs in worker on failure
-      InventoryService.restore(order)
+      InventoryService.restore(args[:order])
+      Success()
     end
   end
 end
@@ -337,16 +346,19 @@ Retries are visible in Sidekiq web UI with:
 ### Sidekiq Worker Setup
 
 ```ruby
-# config/sidekiq.rb
-require 'ruby_reactor/worker'
-
+# config/initializers/ruby_reactor.rb (Rails) or load before booting Sidekiq
 RubyReactor.configure do |config|
+  config.storage.adapter = :redis
+  config.storage.redis_url = ENV.fetch("REDIS_URL", "redis://localhost:6379/0")
+
   config.sidekiq_queue = :default
   config.sidekiq_retry_count = 3
   config.logger = Logger.new('log/ruby_reactor.log')
 end
 ```
 
+Sidekiq workers are loaded automatically via Zeitwerk when `ruby_reactor` is required — no extra `require` is needed.
+
 ## Performance Considerations
 
 ### Worker Pool Sizing

data/documentation/core_concepts.md

@@ -24,12 +24,15 @@ Steps are the individual units of work within a reactor. Each step has a name an
 
 ### Inline Step Definition
 
+`run` blocks always receive two positional arguments: the resolved arguments hash and the execution context. Declare inputs with `argument :name, source`:
+
 ```ruby
 step :validate_order do
-  run do |order_id|
-    # Step implementation
-    order = Order.find(order_id)
-    raise "Order not found" unless order
+  argument :order_id, input(:order_id)
+
+  run do |args, _context|
+    order = Order.find(args[:order_id])
+    return Failure("Order not found") unless order
     Success({ order: order })
   end
 end
@@ -144,29 +147,22 @@ end
 
 ## Results
 
-Every reactor execution returns a comprehensive result object.
-<!-- 
-# TODO
-
-This is not true, update to use instance and what is stored
-```ruby
-result = OrderProcessingReactor.run(order_id: 123)
-
-# Overall status
-result.success?        # => true/false
-result.failure?        # => true/false
+`Reactor.run` returns one of four result types:
 
-# Step outputs
-result.step_results    # => { validate_order: {...}, process_payment: {...} }
-result.intermediate_results  # => Hash of all step outputs
+- **`RubyReactor::Success`** — `success?` is `true`. `value` holds the output of the step named in `returns`, or the full `intermediate_results` hash if no `returns` is declared.
+- **`RubyReactor::Failure`** — `failure?` is `true`. Readers include `error`, `step_name`, `reactor_name`, `step_arguments`, `inputs`, `exception_class`, `file_path`, `line_number`, `backtrace`, `validation_errors`, and `retryable?`.
+- **`RubyReactor::AsyncResult`** — returned by an async reactor or when a step hands off to a worker. Readers: `job_id`, `execution_id`, `intermediate_results`.
+- **`RubyReactor::InterruptResult`** — returned when an `interrupt` step pauses execution. Readers: `execution_id`, `correlation_id`, `status` (`:paused`), `timeout_at`, `intermediate_results`.
 
-# Execution tracking
-result.completed_steps # => #<Set: {:validate_order, :process_payment}>
-result.inputs          # => { order_id: 123 }
+Step-by-step state lives on the context, not the result object. Reload via `Reactor.find(execution_id)` to inspect:
 
-# Error information
-result.error           # => Exception object if failed
-``` -->
+```ruby
+reactor = OrderProcessingReactor.find(execution_id)
+reactor.context.intermediate_results # => { validate_order: {...}, ... }
+reactor.context.status               # => "completed" | "failed" | "paused" | "running"
+reactor.execution_trace              # ordered list of run/undo/compensate entries
+reactor.result                       # reconstructed Success/Failure/InterruptResult
+```
 
 ## Error Handling
 
@@ -178,14 +174,18 @@ When a step fails, execution stops and compensation begins:
 
 ```ruby
 step :process_payment do
-  run do
+  argument :amount, input(:amount)
+  argument :token, input(:card_token)
+
+  run do |args, _ctx|
     # This might fail
-    PaymentService.charge(amount, token)
+    PaymentService.charge(args[:amount], args[:token])
   end
 
-  compensate do |payment_id: nil, **|
-    # Undo the payment if it was created
-    PaymentService.refund(payment_id) if payment_id
+  compensate do |error, args, _ctx|
+    # Compensation receives (error, arguments, context)
+    # Best-effort cleanup specific to this step's failure
+    AuditService.log_payment_failure(args[:token], error.message)
   end
 end
 ```
@@ -349,22 +349,23 @@ result = Reactor.run(inputs)
 
 ### Asynchronous Execution
 
-<!-- TODO: review this part -->
-
 ```ruby
 async_result = Reactor.run(inputs)
 # Returns immediately
-# Check status later
-
-case async_result.status
-when :success
-  result = async_result.result
-when :failed
-  error = async_result.error
+async_result.execution_id # UUID to look up state later
+
+# Reload to inspect status / final result
+reactor = Reactor.find(async_result.execution_id)
+case reactor.context.status.to_s
+when "completed" then reactor.result.value
+when "failed"    then reactor.result.error
+when "paused"    then reactor.result.correlation_id
+when "running"   then :still_running
 end
 ```
 
 **Characteristics:**
+
 - Non-blocking execution
 - Background processing with Sidekiq
 - Retry capabilities
@@ -372,33 +373,38 @@ end
 
 ## Step Arguments
 
-Steps receive arguments through keyword arguments, with automatic dependency injection.
+`run` blocks always receive two positional arguments: the resolved arguments hash and the context. Declare each argument explicitly with `argument :name, source` — there is no implicit keyword injection.
+
+Sources you can use:
+
+- `input(:name)` — value from the reactor's inputs (the hash passed to `Reactor.run`).
+- `input(:name, :path)` — nested path access into a hash input.
+- `result(:step_name)` — full output of a previous step.
+- `result(:step_name, :path)` — nested path into a previous step's output.
+- `value(literal)` — a constant value.
 
 ```ruby
 step :validate_order do
-  run do |order_id:, customer_id:|
-    # Direct access to reactor inputs
-    order = Order.find_by(id: order_id, customer_id: customer_id)
+  argument :order_id, input(:order_id)
+  argument :customer_id, input(:customer_id)
+
+  run do |args, _context|
+    order = Order.find_by(id: args[:order_id], customer_id: args[:customer_id])
     Success({ order: order })
   end
 end
 
 step :process_payment do
-  argument :order_data, result(:validate_order)
+  argument :order, result(:validate_order, :order)
 
   run do |args, _context|
-    # Access results from previous steps
-    order = args[:order_data][:order]
-    payment = PaymentService.charge(order.total, order.card_token)
+    payment = PaymentService.charge(args[:order].total, args[:order].card_token)
     Success({ payment_id: payment.id })
   end
 end
 ```
 
-**Argument Resolution:**
-1. **Step Results**: Outputs from completed dependent steps
-2. **Reactor Inputs**: Original inputs passed to `run()`
-3. **Intermediate Results**: Accumulated outputs from all steps
+If a step declares no `argument`s, the reactor's raw inputs hash is passed as `args`.
 
 ## Undo
 
@@ -415,15 +421,16 @@ Unlike compensation which only runs for the failing step, undo is triggered duri
 
 ```ruby
 step :reserve_inventory do
-  run do |items:|
-    reservation_id = InventoryService.reserve(items)
+  argument :items, input(:items)
+
+  run do |args, _ctx|
+    reservation_id = InventoryService.reserve(args[:items])
     Success({ reservation_id: reservation_id })
   end
 
-  undo do |reservation_result, arguments, context|
+  undo do |result, arguments, context|
     # Undo receives the step's result, arguments, and full context
-    reservation_id = reservation_result[:reservation_id]
-    InventoryService.release(reservation_id)
+    InventoryService.release(result[:reservation_id])
     Success("Inventory reservation released")
   end
 end
@@ -438,9 +445,11 @@ Undo blocks receive three parameters:
 
 ```ruby
 step :complex_operation do
-  run do |input:|
+  argument :input, input(:payload)
+
+  run do |args, _ctx|
     # Complex operation that modifies external state
-    record = create_record(input)
+    record = create_record(args[:input])
     notification = send_notification(record)
     Success({ record_id: record.id, notification_id: notification.id })
   end
@@ -477,8 +486,10 @@ Compensation runs immediately when a step fails, before the broader rollback pro
 
 ```ruby
 step :reserve_inventory do
-  run do |items:|
-    reservation_id = InventoryService.reserve(items)
+  argument :items, input(:items)
+
+  run do |args, _ctx|
+    reservation_id = InventoryService.reserve(args[:items])
     Success({ reservation_id: reservation_id })
   end
 
@@ -501,9 +512,12 @@ Compensation blocks receive three parameters:
 
 ```ruby
 step :process_payment do
-  run do |order:, payment_method:|
+  argument :order, result(:validate_order)
+  argument :payment_method, input(:payment_method)
+
+  run do |args, _ctx|
     # Payment processing logic that might fail
-    PaymentService.charge(order.total, payment_method)
+    PaymentService.charge(args[:order].total, args[:payment_method])
   end
 
   compensate do |error, arguments, context|