ruby_reactor 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3ddfd9b6e65d03e5c00d7980563da39b4132fc1d5f0dbe14e5b782d039c7f68
-  data.tar.gz: 785cc8ac8d426433a00f378eafb8f312b343950ecf496e2af0a6fe9e48115c29
+  metadata.gz: 7769f6488ce48db7f07cd9a7bb9774f697cadc6433293ca926a9e1c27b28ce3e
+  data.tar.gz: 9dd0d5edd43c8b7629474ca2c12dd8f1c755d43f7fab3bc33aaefb86a183ba7c
 SHA512:
-  metadata.gz: 549a49deff5d63e129c0b4c043cbc3987dbbb09b054907a5acb8941af85fedb5f9706bad8d56948bbc7ea889eba19174254962ca987e7835b4cd0a7bf3f9e165
-  data.tar.gz: 319399c2854cccb505fc7e8f6c964eeeb527bad375ed513b1a2c2ea89b77445283f287bbff5a0892902a56a5a56b5a9aff105a0164006abf407473ad3780a58d
+  metadata.gz: afbabcc37d4dbba1a6fcb83fb15b88160979802b7cd5d69fd0aed47538080c4abd3196b40a7f7464047f94c2aafa6d5317e825446179e9129a960c0e5d119742
+  data.tar.gz: caef3d4d35e37a0c9bc35b273ad20f8a0dc31810e35cf2ea1b50df57d347762c85d2a42aa6b3125401e324725d0e8f17f9d1acfecb5f8f3bafeeaf9a7308a5d2

data/.release-please-config.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "ruby",
+      "package-name": "ruby_reactor",
+      "version-file": "lib/ruby_reactor/version.rb",
+      "changelog-path": "CHANGELOG.md",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "draft": false,
+      "prerelease": false
+    }
+  }
+}

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.0"
+}

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.8

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.4.0](https://github.com/arturictus/ruby_reactor/compare/ruby_reactor-v0.3.2...ruby_reactor/v0.4.0) (2026-05-17)
+
+
+### Features
+
+* `AsyncResult` returning intermediate_results ([#10](https://github.com/arturictus/ruby_reactor/issues/10)) ([0cb96d6](https://github.com/arturictus/ruby_reactor/commit/0cb96d66e88097665998601276e38e1c2249c581))
+* enhance deserialization error handling in Sidekiq worker ([#23](https://github.com/arturictus/ruby_reactor/issues/23)) ([60dde95](https://github.com/arturictus/ruby_reactor/commit/60dde95606d52cc6a9d352ad0117b4092a1ebb9d))
+* Enhance failure messages with step, reactor, redacted inputs, a… ([#11](https://github.com/arturictus/ruby_reactor/issues/11)) ([952feae](https://github.com/arturictus/ruby_reactor/commit/952feaeb6ebbe5fbe2daf470263d8e769ba64138))
+* Introduce reactor interrupt functionality, allowing pausing and… ([#13](https://github.com/arturictus/ruby_reactor/issues/13)) ([53d0861](https://github.com/arturictus/ruby_reactor/commit/53d0861f0238f0e2247e581b0a27cba2f42cfba6))
+* Rspec helpers ([#19](https://github.com/arturictus/ruby_reactor/issues/19)) ([cb71f80](https://github.com/arturictus/ruby_reactor/commit/cb71f80c0708dacf6c10c0beac88446b00f30f54))
+* Web Dashboard ([#14](https://github.com/arturictus/ruby_reactor/issues/14)) ([80255dd](https://github.com/arturictus/ruby_reactor/commit/80255dd40800af8f6ed804de9c6f151331742fd5))

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
@@ -122,22 +132,40 @@ puts result.value  # => "Hello from Ruby Reactor!"
 
 ## Web Dashboard
 
-RubyReactor comes with a built-in web dashboard to inspect reactor executions, view logs, and retry failed steps.
+RubyReactor ships with a built-in web dashboard to inspect reactor executions, view logs, and retry failed steps. The dashboard is a Rack app (a [Roda](https://roda.jeremyevans.net/) application) bundled inside the gem with its pre-compiled JS/CSS assets — no extra install or asset build step is required.
 
 ### Rails Installation
 
-Mount the dashboard engine in your `config/routes.rb`:
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "ruby_reactor"
+```
+
+Then mount the dashboard in your `config/routes.rb`:
 
 ```ruby
 Rails.application.routes.draw do
   # ... other routes
-  mount RubyReactor::Web::Application => '/ruby_reactor'
+  mount RubyReactor::Web::Application => "/ruby_reactor"
 end
 ```
 
+That's it — visit `/ruby_reactor` and the UI loads. `RubyReactor::Web::Application` is autoloaded by Zeitwerk on first reference, so no extra `require` is needed.
+
+### Rack / Sinatra / Standalone
+
+Because it's a plain Rack app, you can mount it anywhere `call(env)` is accepted:
+
+```ruby
+# config.ru
+require "ruby_reactor/web/application"
+run RubyReactor::Web::Application
+```
+
 ![RubyReactor Dashboard Screenshot](documentation/images/failed_order_processing.png)
 
-You can secure the dashboard using standard Rails authentication methods (e.g., `authenticate` block with Devise).
+You can secure the dashboard using standard Rails authentication methods (e.g., wrapping the `mount` line in an `authenticate` block with Devise, or in a `constraints` block).
 
 ## Usage
 
@@ -159,7 +187,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 +219,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 +229,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 +355,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 +855,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 +881,7 @@ Comprehensive guide to testing reactors with RubyReactor's testing utilities. Le
   - [X] Sidekiq
   - [ ] ActiveJob
 - [ ] OpenTelemetry support
+- [X] locks
 
 ## Development
 
@@ -762,6 +889,64 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+### Running Redis for the test suite
+
+The gem's RSpec suite expects Redis on port `6780` (see [spec/spec_helper.rb](spec/spec_helper.rb)). Start it via Docker Compose:
+
+```bash
+docker compose up -d redis-test
+```
+
+Then run the suite:
+
+```bash
+bundle exec rspec
+```
+
+Stop it when done:
+
+```bash
+docker compose stop redis-test
+```
+
+### Running the demo Rails app
+
+The demo Rails app under [demo_app/](demo_app/) has its own Redis (port `6380`) and bind-mounts the repo so edits to `lib/` are live. Two ways to run it:
+
+**Option A — fully containerized (Redis + Rails + Sidekiq):**
+
+```bash
+docker compose up demo-redis demo-app demo-sidekiq
+```
+
+App available at <http://localhost:3789>.
+
+**Option B — Redis in Docker, Rails on host:**
+
+```bash
+docker compose up -d demo-redis
+
+cd demo_app
+bin/rails db:prepare
+REDIS_URL=redis://localhost:6380/1 bin/rails server
+# in another shell, if you need Sidekiq:
+REDIS_URL=redis://localhost:6380/1 bundle exec sidekiq
+```
+
+To run the demo app specs:
+
+```bash
+cd demo_app
+bundle exec rspec
+```
+
+Tear everything down:
+
+```bash
+docker compose down          # stop containers
+docker compose down -v       # also remove demo_redis_data + bundle_cache volumes
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/arturictus/ruby_reactor. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/arturictus/ruby_reactor/blob/main/CODE_OF_CONDUCT.md).

data/lib/ruby_reactor/configuration.rb

@@ -7,7 +7,8 @@ module RubyReactor
   class Configuration
     include Singleton
 
-    attr_writer :sidekiq_queue, :sidekiq_retry_count, :logger, :async_router
+    attr_writer :sidekiq_queue, :sidekiq_retry_count, :logger, :async_router,
+                :lock_snooze_base_delay, :lock_snooze_jitter, :lock_snooze_max_attempts
 
     def sidekiq_queue
       @sidekiq_queue ||= :default
@@ -17,6 +18,22 @@ module RubyReactor
       @sidekiq_retry_count ||= 3
     end
 
+    # Base seconds the Sidekiq worker waits before re-checking a contended lock.
+    def lock_snooze_base_delay
+      @lock_snooze_base_delay ||= 5
+    end
+
+    # Extra random seconds added to the base delay to avoid thundering herd.
+    def lock_snooze_jitter
+      @lock_snooze_jitter ||= 5
+    end
+
+    # How many times a single job can snooze on lock contention before it is
+    # marked as failed. Set to :infinity to never escalate.
+    def lock_snooze_max_attempts
+      @lock_snooze_max_attempts ||= 20
+    end
+
     def logger
       @logger ||= Logger.new($stderr)
     end

data/lib/ruby_reactor/context_serializer.rb

@@ -145,7 +145,7 @@ module RubyReactor
             when "Regexp"
               Regexp.new(value["source"], value["options"])
             when "GlobalID"
-              GlobalID::Locator.locate(value["gid"])
+              locate_global_id(value["gid"])
             when "Template::Element"
               RubyReactor::Template::Element.new(value["map_name"], value["path"])
             when "Template::Input"
@@ -198,6 +198,15 @@ module RubyReactor
 
       private
 
+      def locate_global_id(gid)
+        unless defined?(GlobalID::Locator)
+          raise RubyReactor::Error::DeserializationError,
+                "globalid gem is required to deserialize GlobalID values (gid: #{gid})"
+        end
+
+        GlobalID::Locator.locate(gid)
+      end
+
       def validate_size(data)
         size = data.bytesize
         return if size <= MAX_CONTEXT_SIZE

data/lib/ruby_reactor/dsl/lockable.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Dsl
+    module Lockable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        attr_reader :lock_config, :semaphore_config, :period_config, :rate_limit_config
+
+        # Propagate lock/semaphore/period/rate-limit config to subclasses;
+        # without this a subclass of a configured reactor would silently lose
+        # those settings.
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@lock_config, @lock_config) if @lock_config
+          subclass.instance_variable_set(:@semaphore_config, @semaphore_config) if @semaphore_config
+          subclass.instance_variable_set(:@period_config, @period_config) if @period_config
+          subclass.instance_variable_set(:@rate_limit_config, @rate_limit_config) if @rate_limit_config
+        end
+
+        # Configure locking for this reactor
+        # @param ttl [Integer] Time to live in seconds (default: 60)
+        # @param wait [Integer] Time to wait for lock in seconds (default: 0)
+        # @param auto_extend [Boolean] When true (default), a background thread
+        #   refreshes the lock TTL every ttl/3 seconds while the reactor runs,
+        #   protecting steps that may legitimately outlast `ttl`. Pass `false`
+        #   to disable and rely solely on `ttl` for expiry.
+        # @yield [inputs] Block that returns the lock key string
+        def with_lock(ttl: 60, wait: 0, auto_extend: true, &block)
+          @lock_config = {
+            ttl: ttl,
+            wait: wait,
+            auto_extend: auto_extend,
+            key_proc: block
+          }
+        end
+
+        # Configure semaphore for this reactor
+        # @param limit [Integer] Maximum concurrent executions
+        # @param wait [Integer] Time to wait for a token in seconds (default: 0)
+        # @yield [inputs] Block that returns the semaphore key string
+        def with_semaphore(limit:, wait: 0, &block)
+          @semaphore_config = {
+            limit: limit,
+            wait: wait,
+            key_proc: block
+          }
+        end
+
+        # Configure a calendar-aligned dedup window for this reactor. The
+        # reactor will run at most once per bucket per key; subsequent calls
+        # in the same bucket return `RubyReactor::Skipped` without executing
+        # any steps.
+        #
+        # Note: `with_period` is *dedup*, not *concurrency*. Two concurrent
+        # racers can both see no marker and both run. Pair with `with_lock`
+        # for true at-most-one semantics within the bucket.
+        #
+        # @param every [Symbol, Integer] :minute / :hour / :day / :week /
+        #   :month / :year, or an integer number of seconds for a sliding
+        #   bucket (index = `time.to_i / every`).
+        # @yield [inputs] Block that returns the period key base. The final
+        #   Redis marker key is `period:<base>:<bucket_id>`.
+        def with_period(every:, &block)
+          # Validate eagerly so misconfiguration surfaces at class load time.
+          RubyReactor::Period.period_seconds(every)
+
+          @period_config = {
+            every: every,
+            key_proc: block
+          }
+        end
+
+        # Configure rate limiting for this reactor (fixed-window counter).
+        # Pass either a single window via `limit:` + `period:`, or a hash of
+        # windows via `limits:` for layered API quotas.
+        #
+        # @example Single window
+        #   with_rate_limit(limit: 3, period: :second) { |i| "stripe:#{i[:account_id]}" }
+        #
+        # @example Multi-window (3/sec AND 100/min AND 5000/hr)
+        #   with_rate_limit(
+        #     limits: { second: 3, minute: 100, hour: 5000 }
+        #   ) { |i| "stripe:#{i[:account_id]}" }
+        #
+        # @param limit [Integer] requests per period (single-window form)
+        # @param period [Symbol, Integer] :second / :minute / :hour / :day /
+        #   :week / :month / :year, or integer seconds (single-window form)
+        # @param limits [Hash{Symbol,Integer => Integer}] mapping of period
+        #   unit to limit (multi-window form)
+        # @yield [inputs] Block returning the rate-limit key base.
+        def with_rate_limit(limit: nil, period: nil, limits: nil, &block)
+          normalized = normalize_rate_limit_args(limit, period, limits)
+
+          @rate_limit_config = {
+            limits: normalized,
+            key_proc: block
+          }
+        end
+
+        private
+
+        def normalize_rate_limit_args(limit, period, limits)
+          if limits
+            raise ArgumentError, "with_rate_limit: use either :limits, or :limit + :period, not both" if limit || period
+
+            limits.map do |period_key, limit_val|
+              {
+                period_seconds: RubyReactor::Period.period_seconds(period_key),
+                limit: Integer(limit_val),
+                name: period_key.to_s
+              }
+            end
+          elsif limit && period
+            [{
+              period_seconds: RubyReactor::Period.period_seconds(period),
+              limit: Integer(limit),
+              name: period.to_s
+            }]
+          else
+            raise ArgumentError, "with_rate_limit requires :limit + :period, or :limits"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/executor/result_handler.rb

@@ -14,6 +14,9 @@ module RubyReactor
 
       def handle_step_result(step_config, result, resolved_arguments)
         case result
+        when RubyReactor::Skipped
+          # Important: must come before the Success branch — Skipped < Success.
+          handle_skipped(step_config, result)
         when RubyReactor::Success
           handle_success(step_config, result, resolved_arguments)
         when RubyReactor::MaxRetriesExhaustedFailure
@@ -53,6 +56,22 @@ module RubyReactor
 
       private
 
+      # A step returned `RubyReactor.Skipped(...)`. Halt cleanly: record the
+      # event in the trace, do NOT push to the undo stack (so existing
+      # completed steps stay as-is — no compensation), and stamp the step
+      # name on the result so the caller can see who halted.
+      def handle_skipped(step_config, result)
+        @step_results[step_config.name] = result
+        result.instance_variable_set(:@step_name, step_config.name) if result.step_name.nil?
+        @context.execution_trace << {
+          type: :skipped,
+          step: step_config.name,
+          timestamp: Time.now,
+          reason: result.reason
+        }
+        result
+      end
+
       def handle_success(step_config, result, resolved_arguments)
         validate_step_output(step_config, result.value, resolved_arguments)
         @step_results[step_config.name] = result

data/lib/ruby_reactor/executor/step_executor.rb

@@ -33,6 +33,11 @@ module RubyReactor
             # If a step returns RetryQueuedResult, we need to stop and return it
             return result if result.is_a?(RetryQueuedResult)
 
+            # If a step returns Skipped, halt the reactor cleanly (no
+            # compensation). Must be checked BEFORE Failure / Success because
+            # Skipped is a Success subclass.
+            return result if result.is_a?(RubyReactor::Skipped)
+
             # If a step returns Failure, we need to stop execution and return it
             return result if result.is_a?(RubyReactor::Failure)