ruby_reactor 0.5.1 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54ecb36ac72eedf48af0025dff29d83986449586683300ce3fe8fd874c1412d5
-  data.tar.gz: 5e3565e3e238bad746d93982ca7b01560893a68755be18fbfce95df6f54ce5b3
+  metadata.gz: 778bc5305c6d1f20833819afd9ccd46f5a5b4c2c135d8e63344d6530f9a733f1
+  data.tar.gz: 32e769816eba846f419e3f31e8290b94e8ff04fe6ea71fef125bb128b3085b82
 SHA512:
-  metadata.gz: 708acdb0c74582cea4c33210ea1bac055080c7dd19c69d166db4b2c22705de2935346d6b09d4fc6c9cbb1bda5ba235cade92a88f04fe791e364bb78bda256138
-  data.tar.gz: e3f03e46d71babe276224571eaad3e794c7d8c695e2865333f5021e680feb21a12cd3b33527035e1349dc600d01faec87b573b691d7e50521c4f0d81610c8b8f
+  metadata.gz: 592db1d0ef94153a4ea028aa3cdeb59f7e4c73929ebec5afd5a9795a93d27a0cfb0c4bd3e135ccf1b14c0329123be6cf0905ad4a141018993832d21212754db3
+  data.tar.gz: 2fd90e47af8e26cf2d58468a1f0629fd1dc04890df0a6e1704e8d6cba5c65b1e050f10f56628c27c7c90b0545d081e33169e3bfd62f416affd761b62edeb24a0

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.5.1"
+  ".": "0.5.3"
 }

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.5.3](https://github.com/arturictus/ruby_reactor/compare/v0.5.2...v0.5.3) (2026-06-17)
+
+
+### Features
+
+* Durability & Recovery ([#39](https://github.com/arturictus/ruby_reactor/issues/39)) ([103e583](https://github.com/arturictus/ruby_reactor/commit/103e5835b413eec2302fa63f3e998d487cfd9eaf))
+
+## [0.5.2](https://github.com/arturictus/ruby_reactor/compare/v0.5.1...v0.5.2) (2026-06-14)
+
+
+### Features
+
+* Nonce lock ([#26](https://github.com/arturictus/ruby_reactor/issues/26)) ([5925cac](https://github.com/arturictus/ruby_reactor/commit/5925cac7af93f59be6c0a8a98ab020f96080f60b))
+
 ## [0.5.1](https://github.com/arturictus/ruby_reactor/compare/v0.5.0...v0.5.1) (2026-06-14)
 
 

data/README.md

@@ -24,7 +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.
+- **Distributed Locks, Semaphores, Rate Limits, Periods & Ordered Locks**: 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"), `with_period` to dedup reactors to once per calendar bucket, and `with_ordered_lock` for strict transaction ordering via a monotonically increasing nonce assigned at enqueue. Async jobs snooze on contention with smart `retry_after` instead of consuming retry budget.
 
 ## Comparison
 
@@ -36,6 +36,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 | Locks / sem / rate / per | Yes          | No              | No          | Manual              |
 | Built-in web dashboard   | Yes          | No              | No          | No                  |
 | Async with Sidekiq       | Yes          | No              | Limited     | Yes                 |
+| Durable crash recovery   | Yes          | No              | No          | Manual              |
 
 ## Real-World Use Cases
 
@@ -44,6 +45,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 - **Subscription Billing**: Coordinate Stripe charges, invoice email generation, and internal entitlement updates. Use interrupts to pause the workflow when 3rd-party APIs are required to continue the workflow or when specific customer approval is needed.
 
 ## Table of Contents
+
 - [Features](#features)
 - [Comparison](#comparison)
 - [Real-World Use Cases](#real-world-use-cases)
@@ -57,8 +59,9 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
   - [Async Execution](#async-execution)
     - [Full Reactor Async](#full-reactor-async)
     - [Step-Level Async](#step-level-async)
+  - [Durability & Recovery](#durability--recovery)
   - [Interrupts (Pause & Resume)](#interrupts-pause--resume)
-  - [Locks & Semaphores](#locks--semaphores)
+  - [Locks, Semaphores & Ordered Locks](#locks-semaphores--ordered-locks)
   - [Map & Parallel Execution](#map--parallel-execution)
     - [Map with Dynamic Source (ActiveRecord)](#map-with-dynamic-source-activerecord)
   - [Input Validation](#input-validation)
@@ -90,35 +93,96 @@ Or install it yourself as:
 
 ## Configuration
 
-Configure RubyReactor with your Sidekiq and Redis settings:
+Every setting is **optional** — RubyReactor ships with the defaults shown. Drop
+this into an initializer (e.g. `config/initializers/ruby_reactor.rb`); pasted as-is
+it changes nothing, so it doubles as a reference of every knob.
+
+> **Reading the block:** lines starting with `##` are documentation. Lines starting
+> with a single `#` (a `config.…` call) are real settings commented at their
+> default — uncomment one to enable it.
 
 ```ruby
 RubyReactor.configure do |config|
-  # Redis configuration for state persistence
-  config.storage.adapter = :redis
+  ## === Storage (Redis) ===
+
+  ## Storage adapter. Default: :redis (the only adapter shipped today).
+  # config.storage.adapter = :redis
+
+  ## Redis URL. Default: "redis://localhost:6379/0".
   config.storage.redis_url = ENV.fetch("REDIS_URL", "redis://localhost:6379/0")
-  config.storage.redis_options = { timeout: 1 }
 
-  # Sidekiq configuration for async execution
-  config.sidekiq_queue = :default
-  config.sidekiq_retry_count = 3
+  ## Extra options passed to Redis.new. Default: {}.
+  # config.storage.redis_options = { timeout: 1 }
 
-  # 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
+  ## === Sidekiq ===
 
-  # Named rate limits shared across reactors. Reference them with
-  # `with_rate_limit(:stripe)`. See Locks, Semaphores, Rate Limits & Periods.
-  config.rate_limits.register(:stripe, limits: { second: 3, minute: 100 })
+  ## Sidekiq queue used by RubyReactor's async worker. Default: :default.
+  # config.sidekiq_queue = :default
+
+  ## Sidekiq retry count for infrastructure failures only (deserialization,
+  ## Redis, network). Step retries are managed separately. Default: 3.
+  # config.sidekiq_retry_count = 3
+
+  ## === Contention snooze (locks / semaphores / rate limits / ordered locks) ===
+
+  ## When a Sidekiq worker cannot acquire a primitive it re-enqueues itself with
+  ## `lock_snooze_base_delay + rand(0..lock_snooze_jitter)` seconds (rate-limit
+  ## uses a precise `retry_after_seconds` hint from the error; ordered-lock waits
+  ## re-poll at the base delay so a successor catches its blocker finishing fast),
+  ## up to `lock_snooze_max_attempts` times before marking the context :failed.
+  ## Set max_attempts to :infinity to never give up.
+  # config.lock_snooze_base_delay = 5
+  # config.lock_snooze_jitter = 5
+  # config.lock_snooze_max_attempts = 20
+
+  ## === Durability & crash recovery (see "Durability & Recovery" below) ===
+
+  ## Retention TTL (seconds) for stored reactor/map state. Must exceed your
+  ## worst-case snooze/retry window; re-stamped on every write. Default: 86_400.
+  # config.context_ttl = 86_400
+
+  ## TTL (seconds) for the per-context liveness lock. A live worker auto-extends
+  ## it; its absence is the sweeper's "worker died" signal. Must exceed the
+  ## longest a single step can run without yielding the GIL. Default: 60.
+  # config.context_lock_ttl = 60
+
+  ## Minimum seconds between per-step checkpoints within one run. 0 = checkpoint
+  ## after every step (strongest guarantee). Raise to coalesce mid-run writes for
+  ## long reactors — only safe when steps are idempotent. Default: 0.
+  # config.checkpoint_min_interval = 0
+
+  ## Recovery sweeper (the chain is kicked once by `RubyReactor.start_sweeper!`).
+  # config.sweeper_enabled = true    # run recovery by default
+  # config.sweeper_interval = 30     # seconds between sweeps = recovery-latency bound
+  # config.sweeper_limit = 1000      # max contexts/maps inspected per sweep
 
-  # Logger configuration
-  config.logger = Logger.new($stdout)
+  ## === Misc ===
+
+  ## Logger. Default: Logger.new($stdout).
+  # config.logger = Logger.new($stdout)
+
+  ## Async router. Default: RubyReactor::SidekiqAdapter. Swap for a custom adapter
+  ## if you don't use Sidekiq — it only needs to respond to
+  ## `perform_async(context_id, reactor_class_name, **)`.
+  # config.async_router = MyCustomAdapter
+
+  ## === Examples (no default — set these to use the feature) ===
+
+  ## Named rate limits shared across reactors. Reference with `with_rate_limit(:stripe)`.
+  # config.rate_limits.register(:stripe, limits: { second: 3, minute: 100 })
+
+  ## OpenTelemetry / custom middlewares. Default: [].
+  # config.middlewares = [RubyReactor::OpenTelemetry]
 end
 ```
 
+You can also leave out the `configure` block entirely — defaults work for local development against a Redis on `localhost:6379`.
+
+> **Crash recovery needs a kick.** The `sweeper_*` settings above only configure
+> the recovery sweeper — they do not start it. Call `RubyReactor.start_sweeper!`
+> once at boot (ideally from a Sidekiq `on(:startup)` hook) or no crashed reactor
+> will ever resume. See [Durability & Recovery](#durability--recovery).
+
 
 ## Quick Start
 
@@ -323,6 +387,73 @@ def create(params)
 end
 ```
 
+### Durability & Recovery
+
+Async reactors are durable: state lives in Redis, not in the job payload. Before
+any background job is enqueued the root context is persisted, and after every
+completed step a checkpoint advances the stored blob — so a crash re-runs at most
+one step, never the whole reactor. Each running reactor also holds a short
+**liveness lock** that a live worker auto-extends; its absence is how a dead
+worker is detected.
+
+**Recovery is not automatic until you start the sweeper.** A crashed worker's
+reactor only resumes when the recovery sweeper notices the lapsed liveness lock
+and re-enqueues it. The sweeper is a self-rescheduling chain — **kick it once per
+process boot:**
+
+The recommended spot is a Sidekiq server startup hook, so only the worker
+process runs recovery (not your web/console/client processes):
+
+```ruby
+# config/initializers/sidekiq.rb
+Sidekiq.configure_server do |config|
+  config.on(:startup) { RubyReactor.start_sweeper! }
+end
+```
+
+Anywhere that runs once at boot works too — e.g. a Rails initializer:
+
+```ruby
+# config/initializers/ruby_reactor.rb
+RubyReactor.start_sweeper!
+```
+
+That's all that's required: `start_sweeper!` is idempotent (safe to call on every
+boot — duplicate kicks collapse to one chain), runs both the top-level reactor
+sweeper and the map sweeper every `config.sweeper_interval` seconds, and stops if
+you set `config.sweeper_enabled = false`. The interval is your recovery-latency
+bound.
+
+> **Sidekiq Enterprise `super_fetch` compatibility:** the chain is safe under
+> reliable fetch. `super_fetch` re-runs a job whose worker died mid-execution, so
+> a tick that crashes *after* enqueuing its successor but *before* acking would,
+> with naive single-flight, be recovered alongside that successor and fork the
+> chain (doubling every interval). RubyReactor avoids this: it never relies on
+> "one job in the chain" — each next tick is claimed by a per-time-window lock, so
+> a `super_fetch`-recovered tick computes the same window, loses the claim, and
+> collapses back to a single successor. The startup hook above is likewise
+> idempotent across multiple `super_fetch` server processes.
+
+**Prefer your own scheduler?** Set `config.sweeper_enabled = false` (which makes
+`start_sweeper!` a no-op) and drive recovery from cron, a Kubernetes `CronJob`,
+`sidekiq-cron`, `sidekiq-scheduler`, or Rails recurring tasks. Each tick is one
+call:
+
+```ruby
+RubyReactor.sweep_once # => { reactors: <n re-enqueued>, maps: <n recovered> }
+```
+
+For example, a rake task a system cron / CronJob can invoke:
+
+```ruby
+# lib/tasks/ruby_reactor.rake
+namespace :ruby_reactor do
+  task sweep: :environment do
+    RubyReactor.sweep_once
+  end
+end
+```
+
 ### Interrupts (Pause & Resume)
 
 Pause execution to wait for external events like webhooks or user approvals.
@@ -359,7 +490,7 @@ ApprovalReactor.continue_by_correlation_id(
 )
 ```
 
-### Locks & Semaphores
+### Locks, Semaphores & Ordered Locks
 
 Coordinate across processes with Redis-backed primitives:
 
@@ -367,6 +498,7 @@ Coordinate across processes with Redis-backed primitives:
 - **`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"). Inline per-reactor, or reference a named limit registered once in `RubyReactor.configure` and shared across reactors.
 - **`with_period`** — run at most once per calendar bucket (dedup / once-per-day, once-per-month, etc).
+- **`with_ordered_lock`** — strict transaction ordering via a monotonically increasing nonce assigned at enqueue. Workers can only proceed when their nonce equals `last_completed + 1`.
 
 ```ruby
 class RefundOrderReactor < RubyReactor::Reactor
@@ -423,6 +555,27 @@ class ChargeReactor < RubyReactor::Reactor
     run { |args| Stripe.charge(args[:account_id]) }
   end
 end
+
+class OrderedTransactionReactor < RubyReactor::Reactor
+  async
+  input :account_id
+  input :transaction
+
+  # Strict order: a monotonically increasing nonce is assigned at enqueue
+  # time (inside `Reactor.run`). Workers only execute when their nonce
+  # equals last_completed + 1; otherwise they snooze. After the sequence
+  # fully drains the counter resets to 0.
+  with_ordered_lock(poison_pill_timeout: 300) { |inputs| "txs:#{inputs[:account_id]}" }
+
+  step :apply do
+    argument :transaction, input(:transaction)
+    run { |args| Ledger.apply(args[:transaction]) }
+  end
+end
+
+# Caller-side order is preserved; the worker pool may pick jobs in any order
+# but the gate enforces sequential execution per key.
+[tx1, tx2, tx3].each { |tx| OrderedTransactionReactor.run(account_id: 42, transaction: tx) }
 ```
 
 **Named global limits.** When several reactors hit the same external service, register the limit once and reference it by name. The name is the shared key base, so every reactor throttles against one bucket:
@@ -449,8 +602,8 @@ Referencing an unregistered name raises `RubyReactor::RateLimitRegistry::Unknown
 
 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.
+- **Inline** (`Reactor.run`) raises `RubyReactor::Lock::AcquisitionError` / `RubyReactor::Semaphore::AcquisitionError` / `RubyReactor::RateLimit::ExceededError` / `RubyReactor::OrderedLock::WaitError`.
+- **Async** (Sidekiq) snoozes the job via `perform_in(delay, ...)`. For rate limits the delay uses the error's `retry_after_seconds` hint (precise wakeup — the bucket roll time is known exactly); for locks, semaphores, and ordered-lock waits it's `lock_snooze_base_delay + jitter` (a short re-poll, since a held lock or a live blocker nonce typically clears in milliseconds). Snoozes do not count against the Sidekiq retry budget. After `lock_snooze_max_attempts` snoozes the context is marked failed (ordered-lock waits bypass the cap — see the ordered-lock docs).
 
 On dedup hits (period gate already marked), the reactor returns a `RubyReactor::Skipped` result instead — no steps run, no exception:
 
@@ -472,7 +625,7 @@ step :ensure_active do
 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.
+See [Locks, Semaphores, Rate Limits, Periods & Ordered Locks](documentation/locks_and_semaphores.md) for re-entrancy, auto-extend, multi-window quotas, bucket semantics, owner identity, snooze tuning, ordered-lock assignment + poison-pill semantics, and operational notes.
 
 ### Map & Parallel Execution
 
@@ -986,9 +1139,9 @@ 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)
+### [Locks, Semaphores, Rate Limits, Periods & Ordered Locks](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.
+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`), calendar-bucketed dedup (`with_period`, returning `Skipped` results), and strict sequential ordering via a monotonically increasing nonce assigned at enqueue (`with_ordered_lock`). 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, once-per-day/month/year scheduling patterns, ordered-lock counter reset on drain, poison-pill timeouts, and deadlock-safe composition rules.
 
 ### [Middlewares & OpenTelemetry](documentation/middlewares.md)
 

data/lib/ruby_reactor/configuration.rb

@@ -9,12 +9,76 @@ module RubyReactor
 
     attr_writer :sidekiq_queue, :sidekiq_retry_count, :logger, :async_router,
                 :lock_snooze_base_delay, :lock_snooze_jitter, :lock_snooze_max_attempts,
-                :middlewares
+                :middlewares, :context_ttl, :context_lock_ttl, :checkpoint_min_interval,
+                :sweeper_enabled, :sweeper_interval, :sweeper_limit
 
     def sidekiq_queue
       @sidekiq_queue ||= :default
     end
 
+    # Retention TTL (seconds) for a stored reactor context. Storage is
+    # load-bearing for resume, so this must comfortably exceed the worst-case
+    # snooze/retry window. Refreshed on every checkpoint write.
+    def context_ttl
+      @context_ttl ||= 86_400
+    end
+
+    # Minimum wall-clock seconds between two PER-STEP durable checkpoints within a
+    # single worker run. The save-per-step checkpoint (`on_step_complete`) bounds
+    # crash re-execution to one step, but re-serializes and re-writes the WHOLE
+    # root blob after every Success — O(steps × context_size) writes for a long,
+    # large reactor. This throttle coalesces the mid-run intermediate checkpoints:
+    # a checkpoint is written only if at least this many seconds have elapsed since
+    # the last one. The final terminal/handoff state is ALWAYS persisted (by the
+    # run's ensure-save and the pre-enqueue checkpoint), so throttling only affects
+    # mid-run granularity. Tradeoff: with interval > 0, a crash may re-run every
+    # step completed inside the last interval — safe only when those steps are
+    # idempotent or side-effect-free.
+    #
+    # Default 0 -> checkpoint after EVERY step (strongest guarantee, no coalescing).
+    def checkpoint_min_interval
+      @checkpoint_min_interval ||= 0
+    end
+
+    # Whether the recovery sweepers run. The host kicks the self-rescheduling
+    # chain once (`RubyReactor.start_sweeper!`, e.g. from an initializer); each
+    # tick re-checks this flag, so flipping it to false stops the chain at the
+    # next tick. Default on: durability is inert without a running sweeper, so
+    # recovery must work out of the box.
+    def sweeper_enabled
+      @sweeper_enabled = true if @sweeper_enabled.nil?
+      @sweeper_enabled
+    end
+
+    # Seconds between sweeps. This is the upper bound on recovery latency for a
+    # dead worker — lower it for faster recovery, raise it to cut scan load.
+    def sweeper_interval
+      @sweeper_interval ||= 30
+    end
+
+    # Max contexts/maps inspected per sweep (passed to each sweeper's run_once).
+    def sweeper_limit
+      @sweeper_limit ||= 1000
+    end
+
+    # TTL (seconds) for the per-context liveness lock (`async:<id>`). Short by
+    # design — it is a liveness signal, not retention. A live worker auto-extends
+    # it (every ttl/3 s, from a background thread); its absence is the sweeper's
+    # "worker died" signal.
+    #
+    # SAFETY CONSTRAINT: this MUST exceed the longest a single step can run
+    # WITHOUT letting the auto-extend thread make progress. Under MRI the
+    # extender shares the GIL, so a step that holds the GIL continuously for
+    # longer than this TTL (a long CPU-bound pure-Ruby loop, a C extension that
+    # never releases the GIL, or a stop-the-world GC pause) lets the lock lapse.
+    # A lapsed lock looks "dead" to the sweeper, which may re-enqueue a duplicate
+    # that runs CONCURRENTLY with the still-live original — a double-run. I/O-bound
+    # steps release the GIL and keep the lock fresh, so the default 60s suits
+    # typical workloads; raise it if you run long synchronous CPU-bound steps.
+    def context_lock_ttl
+      @context_lock_ttl ||= 60
+    end
+
     def sidekiq_retry_count
       @sidekiq_retry_count ||= 3
     end
@@ -36,7 +100,7 @@ module RubyReactor
     end
 
     def logger
-      @logger ||= Logger.new($stderr)
+      @logger ||= Logger.new($stdout)
     end
 
     def async_router

data/lib/ruby_reactor/context_serializer.rb

@@ -19,13 +19,18 @@ module RubyReactor
 
       def deserialize(serialized_data)
         decompressed = decompress_if_needed(serialized_data)
-        data = JSON.parse(decompressed, symbolize_names: false)
+        deserialize_hash(JSON.parse(decompressed, symbolize_names: false))
+      rescue JSON::ParserError => e
+        raise RubyReactor::Error::DeserializationError, "Failed to parse serialized context: #{e.message}"
+      end
 
+      # Deserialize from an already-parsed Hash (e.g. what the storage adapter's
+      # `retrieve_context` returns). Lets the rehydrate-by-id worker path avoid a
+      # second JSON parse while still schema-validating. Schema validation lives
+      # here so both the string and Hash entry points enforce it.
+      def deserialize_hash(data)
         validate_schema_version(data)
-
         Context.deserialize_from_retry(data)
-      rescue JSON::ParserError => e
-        raise RubyReactor::Error::DeserializationError, "Failed to parse serialized context: #{e.message}"
       end
 
       # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength

data/lib/ruby_reactor/dsl/compose_builder.rb

@@ -41,6 +41,7 @@ module RubyReactor
       end
 
       def build
+        warn_if_child_has_ordered_lock!
         dependencies = extract_dependencies_from_mappings
 
         step_config = {
@@ -78,6 +79,25 @@ module RubyReactor
 
       private
 
+      # Composed children bypass `Reactor#run`, so `assign_ordered_lock_nonce!`
+      # never fires for them — their `with_ordered_lock` declaration is silently
+      # ignored. Surface this at class load so users don't expect ordering
+      # enforcement that isn't happening. Nested ordered-lock sequences must be
+      # invoked as top-level `Reactor.run` to participate.
+      def warn_if_child_has_ordered_lock!
+        return unless @composed_reactor_class
+        return unless @composed_reactor_class.respond_to?(:ordered_lock_config)
+        return unless @composed_reactor_class.ordered_lock_config
+
+        parent_name = @reactor&.name || "<anonymous>"
+        child_name = @composed_reactor_class.name || "<anonymous>"
+        RubyReactor.configuration.logger.warn(
+          "RubyReactor: `with_ordered_lock` on #{child_name} is ignored when " \
+          "composed by #{parent_name}##{@name}. Nested ordered-lock sequences " \
+          "are independent and must run via top-level `Reactor.run` to be enforced."
+        )
+      end
+
       def ensure_composed_reactor_class!
         raise ArgumentError, "No block provided for inline compose" unless @composed_reactor_class
       end

data/lib/ruby_reactor/dsl/lockable.rb

@@ -8,7 +8,7 @@ module RubyReactor
       end
 
       module ClassMethods
-        attr_reader :lock_config, :semaphore_config, :period_config, :rate_limit_config
+        attr_reader :lock_config, :semaphore_config, :period_config, :rate_limit_config, :ordered_lock_config
 
         # Propagate lock/semaphore/period/rate-limit config to subclasses;
         # without this a subclass of a configured reactor would silently lose
@@ -19,6 +19,7 @@ module RubyReactor
           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
+          subclass.instance_variable_set(:@ordered_lock_config, @ordered_lock_config) if @ordered_lock_config
         end
 
         # Configure locking for this reactor
@@ -74,6 +75,45 @@ module RubyReactor
           }
         end
 
+        # Configure strict-ordering nonce gating for this reactor. A
+        # monotonically increasing nonce is assigned at enqueue time; the
+        # worker can only proceed when its nonce equals `last_completed + 1`.
+        # Otherwise the worker raises {OrderedLock::WaitError} and the Sidekiq
+        # worker snoozes via `perform_in`.
+        #
+        # Counters reset to 0 once the sequence fully drains (last_completed
+        # catches up to next). Re-entrancy is NOT supported — a nested reactor
+        # with its own `with_ordered_lock` is an independent sequence.
+        #
+        # @param poison_pill_timeout [Integer] seconds since the blocker nonce
+        #   was assigned before the gate auto-advances past it. Protects
+        #   against permanent head-of-line blocking from a caller that INCRed
+        #   the counter but crashed before enqueueing.
+        # @param ttl [Integer] TTL on the counter keys, refreshed on every
+        #   assign. Only fully-drained sequences GC themselves.
+        # @param strict [Boolean] When true (default), if any nonce in the
+        #   sequence terminates with a `Failure`, all subsequent nonces are
+        #   short-circuited with `Skipped(reason: :ordered_lock_chain_failed)`
+        #   instead of executing. This models "stop the line on the first
+        #   problem" pipelines (e.g. ledger transactions). When false, the
+        #   sequence keeps executing every nonce in order regardless of prior
+        #   failures. The poison state is per-key and clears on full drain. The
+        #   check only applies to a fresh `execute`; an already-started run
+        #   that paused (InterruptResult/AsyncResult) completes on resume even
+        #   if the chain failed in the meantime.
+        # @yield [inputs] Block that returns the ordered-lock key string.
+        def with_ordered_lock(poison_pill_timeout: OrderedLock::DEFAULT_POISON_PILL_TIMEOUT,
+                              ttl: OrderedLock::DEFAULT_TTL,
+                              strict: true,
+                              &block)
+          @ordered_lock_config = {
+            poison_pill_timeout: poison_pill_timeout,
+            ttl: ttl,
+            strict: strict,
+            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.