ruby_reactor 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54ecb36ac72eedf48af0025dff29d83986449586683300ce3fe8fd874c1412d5
-  data.tar.gz: 5e3565e3e238bad746d93982ca7b01560893a68755be18fbfce95df6f54ce5b3
+  metadata.gz: 66c0a0c5591cd862dc61063d752f4d92111370808256bfdae749825fec68429b
+  data.tar.gz: 212ac4ce7ef87e5d28606cab0aff8358afde437389fbb5b2d717b1b5874daa77
 SHA512:
-  metadata.gz: 708acdb0c74582cea4c33210ea1bac055080c7dd19c69d166db4b2c22705de2935346d6b09d4fc6c9cbb1bda5ba235cade92a88f04fe791e364bb78bda256138
-  data.tar.gz: e3f03e46d71babe276224571eaad3e794c7d8c695e2865333f5021e680feb21a12cd3b33527035e1349dc600d01faec87b573b691d7e50521c4f0d81610c8b8f
+  metadata.gz: 75e3bd7ead2281ef7bd1a74fe42a1aaaa1ff5ac92db2b72172e779b0fa9591878268b9829c939def027a6d368ad0ad7b00eddaa05bbb5497f0678229b68b17c0
+  data.tar.gz: 46c44e73bef1e7f2a11d7a5de51de83a2a9a2505aa8c5b06cf64215bc97c4c272f67f23a220187431a188a6dcca216ee13741566fc61e1ead6a8d7dc7b392d74

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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
 
@@ -58,7 +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)
+  - [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)
@@ -92,20 +92,31 @@ Or install it yourself as:
 
 Configure RubyReactor with your Sidekiq and Redis settings:
 
+Every setting below is **optional** — RubyReactor ships with the defaults shown. Override only what you need.
+
 ```ruby
 RubyReactor.configure do |config|
-  # Redis configuration for state persistence
+  # 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")
+  # Extra options passed to Redis.new. Default: {}.
   config.storage.redis_options = { timeout: 1 }
 
-  # Sidekiq configuration for async execution
+  # 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
 
-  # 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.
+  # Lock/semaphore/rate-limit/ordered-lock contention snooze behavior for
+  # async reactors. 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. Defaults: 5 / 5 / 20. 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
@@ -114,11 +125,18 @@ RubyReactor.configure do |config|
   # `with_rate_limit(:stripe)`. See Locks, Semaphores, Rate Limits & Periods.
   config.rate_limits.register(:stripe, limits: { second: 3, minute: 100 })
 
-  # Logger configuration
+  # Logger. Default: Logger.new($stderr).
   config.logger = Logger.new($stdout)
+
+  # Async router. Default: RubyReactor::SidekiqAdapter. Swap for a custom
+  # adapter if you don't use Sidekiq — the adapter only needs to respond to
+  # `perform_async(serialized_context, reactor_class_name, **)`.
+  # config.async_router = MyCustomAdapter
 end
 ```
 
+You can also leave out the `configure` block entirely — defaults work for local development against a Redis on `localhost:6379`.
+
 
 ## Quick Start
 
@@ -359,7 +377,7 @@ ApprovalReactor.continue_by_correlation_id(
 )
 ```
 
-### Locks & Semaphores
+### Locks, Semaphores & Ordered Locks
 
 Coordinate across processes with Redis-backed primitives:
 
@@ -367,6 +385,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 +442,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 +489,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 +512,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 +1026,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/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.

data/lib/ruby_reactor/executor/ordered_lock_support.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  class Executor
+    # Gate check and terminal-advance logic for `with_ordered_lock`. Mixed
+    # into Executor to keep that class under the length limit. All methods
+    # read from `@context.private_data[:ordered_lock]`, which Reactor#run
+    # populates at enqueue time.
+    module OrderedLockSupport
+      # Thread-local stack of ordered-lock keys whose steps are currently
+      # running in this thread. Used to detect a synchronous `Reactor.run`
+      # nested under another ordered-lock reactor on the same key — which
+      # would deadlock since the outer holds the slot and the inner can never
+      # advance.
+      THREAD_LOCAL_ACTIVE_KEYS = :ruby_reactor_active_ordered_locks
+
+      # Minimum interval between liveness heartbeats; protects very small
+      # poison_pill_timeouts (mirrors Lock::MIN_EXTEND_INTERVAL).
+      HEARTBEAT_MIN_INTERVAL = 1.0
+
+      def self.active_keys
+        Thread.current[THREAD_LOCAL_ACTIVE_KEYS] ||= []
+      end
+
+      # Parse the ordered-lock stash from a context's private_data, surviving
+      # the JSON round-trip (symbol or string keys). Module-level so the
+      # Sidekiq worker can advance the nonce on escalation paths that never
+      # construct an Executor.
+      def self.info_from(context)
+        data = context.private_data[:ordered_lock] || context.private_data["ordered_lock"]
+        return nil unless data
+
+        strict_raw = data[:strict]
+        strict_raw = data["strict"] if strict_raw.nil?
+        strict_raw = true if strict_raw.nil?
+
+        {
+          key: data[:key] || data["key"],
+          nonce: (data[:nonce] || data["nonce"]).to_i,
+          epoch: (data[:epoch] || data["epoch"]).to_i,
+          poison_pill_timeout: (data[:poison_pill_timeout] || data["poison_pill_timeout"] ||
+                                OrderedLock::DEFAULT_POISON_PILL_TIMEOUT).to_i,
+          ttl: (data[:ttl] || data["ttl"] || OrderedLock::DEFAULT_TTL).to_i,
+          strict: [true, "true"].include?(strict_raw)
+        }
+      end
+
+      # Strict-ordering gate. Runs BEFORE rate-limit / lock / semaphore so a
+      # waiting nonce never holds any other primitive — preventing
+      # hold-and-wait deadlocks when `with_lock` and `with_ordered_lock`
+      # share inputs. Raises {OrderedLock::WaitError}; the Sidekiq worker
+      # rescues and snoozes.
+      def check_ordered_lock_gate
+        info = ordered_lock_info
+        return :go unless info
+
+        OrderedLock.new(
+          info.fetch(:key),
+          nonce: info.fetch(:nonce),
+          epoch: info.fetch(:epoch),
+          poison_pill_timeout: info.fetch(:poison_pill_timeout),
+          strict: info.fetch(:strict)
+        ).check!
+      end
+
+      # Combined gate-check + thread-local push. Call at the top of
+      # `execute` / `resume_execution`. Pair with `leave_ordered_lock_scope`
+      # in `ensure`.
+      #
+      # The strict-mode chain-skip only fires on a *fresh* start (no step
+      # has run yet on this context). This lets an in-flight run that paused
+      # (Interrupt / AsyncResult) complete on resume regardless of chain
+      # failures that landed while it was parked, while still applying
+      # strict to a fresh Sidekiq job (which enters via `resume_execution`
+      # but has no prior step state).
+      def enter_ordered_lock_scope
+        gate = check_ordered_lock_gate
+        # A stale-batch run never participates regardless of fresh/resume state —
+        # its numbering belongs to a drained generation. Chain-skip stays gated
+        # on a fresh start so an in-flight paused run still completes on resume.
+        @ordered_lock_stale_batch = gate == :stale_batch
+        @ordered_lock_chain_skip = fresh_ordered_lock_start? && gate == :skip_chain_failed
+
+        # Drained-batch gate: the batch GC'd while this caller slept. A genuine
+        # late straggler runs (poison semantics); a Sidekiq redelivery of an
+        # ALREADY-terminal context must not re-execute its steps. Only the
+        # latter — confirmed by a terminal stored status — is short-circuited.
+        @ordered_lock_drained_replay = gate == :drained_go && stored_status_terminal?
+
+        info = ordered_lock_info
+        return unless info
+
+        OrderedLockSupport.active_keys << info[:key]
+
+        # Only a run that will actually execute steps needs a heartbeat. A
+        # short-circuiting run (stale batch / strict chain skip / drained
+        # redelivery) does no work and terminally advances immediately, so
+        # starting a thread for it is pointless churn.
+        return if @ordered_lock_stale_batch || @ordered_lock_chain_skip || @ordered_lock_drained_replay
+
+        start_ordered_lock_heartbeat(info)
+      end
+
+      def fresh_ordered_lock_start?
+        @context.intermediate_results.empty? && @context.current_step.nil?
+      end
+
+      def ordered_lock_chain_skip?
+        @ordered_lock_chain_skip == true
+      end
+
+      def ordered_lock_stale_batch?
+        @ordered_lock_stale_batch == true
+      end
+
+      def ordered_lock_drained_replay?
+        @ordered_lock_drained_replay == true
+      end
+
+      # Terminal Skipped result when the ordered-lock gate short-circuits this
+      # run (stale batch, strict chain failure, or a drained-batch redelivery of
+      # an already-terminal context), or nil to continue. Shared by `execute`
+      # and `resume_execution`.
+      def ordered_lock_short_circuit
+        return RubyReactor::Skipped.new(reason: :ordered_lock_stale_batch) if ordered_lock_stale_batch?
+        return RubyReactor::Skipped.new(reason: :ordered_lock_drained_replay) if ordered_lock_drained_replay?
+        return RubyReactor::Skipped.new(reason: :ordered_lock_chain_failed) if ordered_lock_chain_skip?
+
+        nil
+      end
+
+      # Pre-step short-circuit: ordered-lock gate skip or already-marked
+      # period bucket. Returns a terminal result or nil.
+      def short_circuit_result
+        ordered_lock_short_circuit || check_period_gate
+      end
+
+      def short_circuit!(result)
+        @result = result
+
+        # A stale-batch or drained-batch-redelivery skip means this run's epoch
+        # belongs to a drained generation — typically a slow straggler or a
+        # Sidekiq at-least-once redelivery. If the redelivery is of a job that
+        # ALREADY reached a terminal status, its stored context is the source of
+        # truth; writing :skipped over a :completed/:failed record would silently
+        # corrupt the outcome. Return the skip to the worker (so it stops)
+        # without saving. The `@skip_context_persist` flag also suppresses the
+        # ensure-block save in execute / resume_execution, which would otherwise
+        # clobber the stored terminal record with this run's stale in-memory
+        # status.
+        if redelivery_of_terminal?(result)
+          @skip_context_persist = true
+          return @result
+        end
+
+        update_context_status(@result)
+        save_context
+        @result
+      end
+
+      def skip_context_persist?
+        @skip_context_persist == true
+      end
+
+      # True when the skip is one of the drained-generation reasons (stale batch
+      # or drained-batch replay) AND the stored context already reached a
+      # terminal status — i.e. this is a redelivery of an already-finished run
+      # whose record must not be overwritten. The drained-replay flag is only
+      # set when the status was terminal, but re-checking keeps both paths
+      # uniform and self-guarding.
+      def redelivery_of_terminal?(result)
+        return false unless result.is_a?(RubyReactor::Skipped)
+        return false unless %i[ordered_lock_stale_batch ordered_lock_drained_replay].include?(result.reason)
+
+        stored_status_terminal?
+      end
+
+      def stored_status_terminal?
+        %w[completed failed skipped].include?(stored_context_status)
+      end
+
+      def stored_context_status
+        reactor_class_name = @reactor_class.name || "AnonymousReactor-#{@reactor_class.object_id}"
+        data = RubyReactor.configuration.storage_adapter.retrieve_context(@context.context_id, reactor_class_name)
+        return nil unless data
+
+        (data["status"] || data[:status]).to_s
+      rescue StandardError
+        nil
+      end
+
+      # Combined terminal-advance + thread-local pop. Idempotent: safe to call
+      # in `ensure` even if `enter_ordered_lock_scope` never pushed (gate
+      # raised, or no ordered_lock configured).
+      def leave_ordered_lock_scope
+        # Stop (and join) the heartbeat BEFORE advancing: the advance HDELs this
+        # nonce's assigned_at, and a heartbeat racing that HDEL could restamp it.
+        # The HEARTBEAT_SCRIPT's hexists guard makes a late restamp a harmless
+        # no-op, but joining first keeps the ordering deterministic.
+        stop_ordered_lock_heartbeat
+        advance_ordered_lock_if_terminal
+        info = ordered_lock_info
+        return unless info
+
+        stack = OrderedLockSupport.active_keys
+        idx = stack.rindex(info[:key])
+        stack.delete_at(idx) if idx
+      end
+
+      # Background thread that restamps this nonce's assigned_at every pp/3
+      # seconds (floored at HEARTBEAT_MIN_INTERVAL) while its steps run, so a
+      # legitimately slow blocker is not poison-passed by a successor. Mirrors
+      # the Lock auto-extend thread. The thread sleeps FIRST, so a job that
+      # finishes faster than one interval never touches Redis.
+      def start_ordered_lock_heartbeat(info)
+        return if @ordered_lock_heartbeat_running
+
+        pp = info[:poison_pill_timeout].to_f
+        interval = [pp / 3.0, HEARTBEAT_MIN_INTERVAL].max
+        @ordered_lock_heartbeat_running = true
+        lock = OrderedLock.new(
+          info.fetch(:key), nonce: info.fetch(:nonce), epoch: info.fetch(:epoch)
+        )
+
+        @ordered_lock_heartbeat = Thread.new do
+          while @ordered_lock_heartbeat_running
+            sleep interval
+            break unless @ordered_lock_heartbeat_running
+
+            begin
+              lock.heartbeat!
+            rescue StandardError => e
+              RubyReactor.configuration.logger.warn(
+                "RubyReactor ordered_lock heartbeat failed for '#{info[:key]}' " \
+                "nonce #{info[:nonce]}: #{e.message}"
+              )
+              break
+            end
+          end
+        end
+      end
+
+      def stop_ordered_lock_heartbeat
+        return unless @ordered_lock_heartbeat_running
+
+        @ordered_lock_heartbeat_running = false
+        thread = @ordered_lock_heartbeat
+        @ordered_lock_heartbeat = nil
+        return unless thread
+
+        thread.wakeup if thread.alive?
+        thread.join(0.1)
+      rescue StandardError
+        # Best-effort shutdown; never let heartbeat teardown break the ensure chain.
+      end
+
+      # Advance the cursor when this run reached a *terminal* status.
+      # Retry-queued, interrupted, or async-handed-off results keep the same
+      # nonce owning the slot — a Sidekiq retry must not double-advance. A
+      # terminal `Failure` is also recorded as the chain's poison marker
+      # (only the FIRST such failure sticks).
+      def advance_ordered_lock_if_terminal
+        info = ordered_lock_info
+        return unless info
+        return unless terminal_for_ordered_lock?(@result)
+
+        OrderedLockSupport.advance_with_retry(info, failed: @result.is_a?(RubyReactor::Failure))
+      end
+
+      # A missed advance on a terminal result stalls every successor for up to
+      # poison_pill_timeout with only a warn line as evidence, so one transient
+      # Redis blip is worth absorbing here before giving up.
+      def self.advance_with_retry(info, failed:)
+        attempts = 0
+        begin
+          attempts += 1
+          OrderedLock.new(
+            info.fetch(:key), nonce: info.fetch(:nonce), epoch: info.fetch(:epoch), ttl: info.fetch(:ttl)
+          ).advance!(failed: failed)
+        rescue StandardError => e
+          retry if attempts < 2
+
+          RubyReactor.configuration.logger.warn(
+            "RubyReactor failed to advance ordered_lock '#{info[:key]}' nonce #{info[:nonce]} " \
+            "after #{attempts} attempts: #{e.message} — successors will stall until " \
+            "poison_pill_timeout (#{info[:poison_pill_timeout]}s) expires"
+          )
+        end
+      end
+
+      private
+
+      def ordered_lock_info
+        OrderedLockSupport.info_from(@context)
+      end
+
+      def terminal_for_ordered_lock?(result)
+        case result
+        when RubyReactor::AsyncResult, RubyReactor::InterruptResult, RetryQueuedResult
+          false
+        when RubyReactor::Success, RubyReactor::Failure
+          true
+        end
+      end
+    end
+  end
+end