cmdx 1.19.0 → 1.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ead1d181ed1eac565ea3287eeaaca3216e5d24a40f4071000539584435fc1327
-  data.tar.gz: ba0273c00286e10621f06fc5b0ba7be760afa99dd8d3fbfc6fc7da1c3c11891f
+  metadata.gz: 34ebd45d6a27296d5960995fc1b313b808f1d3835df82ce688ae1a6dc4faa313
+  data.tar.gz: 01ccc099ffd40950e4085c850ba3959db59bddbb5df39e8b540a6310607f7a59
 SHA512:
-  metadata.gz: 30e8c09228e765f2ac8e9b4f8db854da21a13e3a2d7e67b9ad61ecad66d09dd7f8ca9327ac9a8ef8777e78d56d5844a06f52e55d282cc1d78d7ddb9141b9acc2
-  data.tar.gz: 922de5ad8342195dc94bf8137e7023612db4df09b3979581c0e77aecf599cae971004e64b9ab71261ea6795feb8ca8b7fe3fe4fc3f37a570ed50157c404aff33
+  metadata.gz: 9cadc2e6c98e819512a62eb484c7ffb5ed2ea29bf135851441cb78fa4bb64421b844337d489976c4148c0e471144159640257dc20d574a802e90619d833c2316
+  data.tar.gz: 3edd420426ccc2ed48b1bc3f972984111eb10ec1f41bd835de478318cb5dba169cb440c5ff24b202533a942040a62aaf9897d88f03229cc97285ea69af11a377

data/CHANGELOG.md

@@ -6,25 +6,76 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [UNRELEASED]
 
+## [1.20.0] - 2026-03-12
+
+### Added
+- Add `CallbackRegistry#empty?` for fast callback presence checking
+- Add `Parallelizer` class for bounded thread pool execution
+- Add `Configuration#default_locale` setting (defaults to `"en"`)
+- Add `Task.type` to return task mechanics
+- Add `Utils::Normalize` module for exception and status normalization
+- Add `Utils::Wrap` module for array value normalization
+- Add `Retry` class for retry logic, state tracking, and jitter computation
+- Add `Settings` object with method-based access
+- Add `freeze_results` configuration option to replace `SKIP_CMDX_FREEZING` env var
+- Add `any?`, `clear`, and `size` delegators to `Errors`
+- Add `Context#respond_to_missing?` for setter methods
+- Add `Attribute#clear_task_tree!` to prevent stale task instance retention
+- Add thread-safe `Chain#push` and `Chain#index` via `Mutex`
+- Add identity-aware `Executor#clear_chain!` for parallel execution safety
+- Add `Executor#verify_middleware_yield!` to detect non-yielding middlewares
+- Add copy-on-write semantics to `MiddlewareRegistry`, `CallbackRegistry`, `CoercionRegistry`, and `ValidatorRegistry`
+- Add `Attribute#allocation_name` for task-free reader name resolution
+- Add `AttributeRegistry#define_readers_on!` and `#undefine_readers_on!` for eager reader definition
+
 ### Changed
-- Add attribute `source` fallback to `:context` when no task is given
-- Improve falsy attribute derived Hash value lookup
+- Short-circuit `Executor#post_execution!` when callback registry is empty
+- Optimize `Context#method_missing` to avoid `String` allocation on getter path
+- Replace `parallel` gem with native `Parallelizer` thread pool
+- Rename `in_threads` option to `pool_size`
+- Move `TimeoutError` to `exception.rb` for Zeitwerk autoloading
+- Update Rails initializer install script
+- Dup attributes in `AttributeRegistry#define_and_verify` for thread-safe concurrent execution
+- Default `retry_on` to `[StandardError, CMDx::TimeoutError]`
+- Replace hash-based `settings[:]` with method-based `settings.` access
+- Lazy-load locale translations instead of eager-loading
+- Use compile-time method definition for `Identifier#generate` and `Chain`/`Correlate` `thread_or_fiber`
+- Use `define_method` on task class for attribute readers
+- Tighten `Deprecator` regex to exact word boundaries
+- Use `public_send` instead of `send` in `Result` for state/status checks
+
+### Fixed
+- Fix `Attribute#source` and `#method_name` memoization without a task
+- Fix `execute!` to call `executed!` before `post_execution!` on non-halt path
+- Clear `task.errors` before each retry attempt
+- Fix `Pipeline#execute_tasks_in_parallel` to snapshot context per thread
+- Reject `in_processes` and `in_reactors` options in parallel tasks
+
+### Removed
+- Remove `SKIP_CMDX_FREEZING` env var in favor of `CMDx.configuration.freeze_results`
+
+## [1.19.0] - 2026-03-09
+
+### Changed
+- Fall back attribute `source` to `:context` when no task is given
+- Improve falsy attribute derived hash value lookup
 - Freeze chain results
-- Fix missing fault cause no method error issue
-- Add context respond_to? with setter methods
+- Use `to_date`, `to_time`, `to_datetime` for date/time coercion checks
+
+### Fixed
+- Fix missing fault cause `NoMethodError`
 - Fix validator `allow_nil` inverted logic
-- Array coercion JSON parse error no returns CoercionError
-- Boolean coercions now return `false` for `nil` and `""`
-- Coerce anaglous date, datetime, and time class checks to rely on `to_date`, `to_time`, `to_datetime` methods
+- Fix array coercion JSON parse error to return `CoercionError`
+- Fix boolean coercions to return `false` for `nil` and `""`
 
-## [1.18.0] - 2025-03-09
+## [1.18.0] - 2026-03-09
 
 ### Changed
 - Use `Fiber.storage` instead of `Thread.current` for `Chain` and `Correlate` storage, with fallback to `Thread.current` for Ruby < 3.2, making them thread and fiber safe
 - Clone shared logger in `Task#logger` when `log_level` or `log_formatter` is customized to prevent mutation of the shared instance
 - Derive attribute values from source objects that respond to the attribute name (via `send`) as fallback when the source is not callable
 
-## [1.17.0] - 2025-02-23
+## [1.17.0] - 2026-02-23
 
 ### Added
 - Add `returns` macro for context output validation after task execution
@@ -33,26 +84,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Add hash coercion for JSON `"null"` string as empty hash
 - Add attribute sourcing to support both string and symbol keys when sourcing/deriving from Hash
 
-## Changed
-- Do not fail coercion if nil on optional attributes
+### Changed
 - Include the source method in the required attribute error message
 
-## [1.16.0] - 2025-02-06
+### Fixed
+- Fix coercion to not fail on `nil` for optional attributes
+
+## [1.16.0] - 2026-02-06
 
 ### Added
 - Add `CMDx::Exception` alias for `CMDx::Error`
 
 ### Changed
-- Renamed `exceptions.rb` file to `exception.rb` (zeitwerk issue)
-- Renamed `faults.rb` file to `fault.rb` (zeitwerk issue)
+- Rename `exceptions.rb` file to `exception.rb` (zeitwerk compatibility)
+- Rename `faults.rb` file to `fault.rb` (zeitwerk compatibility)
 
-## [1.15.0] - 2025-01-21
+## [1.15.0] - 2026-01-21
 
 ### Added
 - Add attribute `Absence` validator
 - Add attribute `:description` option
 
-## [1.14.0] - 2025-01-09
+## [1.14.0] - 2026-01-09
 
 ### Added
 - Add Ruby 4.0 compatibility

data/README.md

@@ -12,9 +12,9 @@
   [Changelog](./CHANGELOG.md) ·
   [Report Bug](https://github.com/drexed/cmdx/issues) ·
   [Request Feature](https://github.com/drexed/cmdx/issues) ·
+  [AI Skills](https://github.com/drexed/cmdx/blob/main/skills) ·
   [llms.txt](https://drexed.github.io/cmdx/llms.txt) ·
   [llms-full.txt](https://drexed.github.io/cmdx/llms-full.txt) ·
-  [SKILL.md](https://github.com/drexed/cmdx/blob/main/docs/SKILL.md)
 
   <img alt="Version" src="https://img.shields.io/gem/v/cmdx">
   <img alt="Build" src="https://github.com/drexed/cmdx/actions/workflows/ci.yml/badge.svg">

data/lib/cmdx/attribute.rb

@@ -108,7 +108,7 @@ module CMDx
     def initialize(name, options = {}, &)
       @parent = options.delete(:parent)
       @required = options.delete(:required) || false
-      @types = Array(options.delete(:types) || options.delete(:type))
+      @types = Utils::Wrap.array(options.delete(:types) || options.delete(:type))
       @description = options.delete(:description) || options.delete(:desc)
 
       @name = name.to_sym
@@ -118,6 +118,21 @@ module CMDx
       instance_eval(&) if block_given?
     end
 
+    # Deep-copies children and clears task-dependent memoization so that
+    # duped attributes can be safely bound to a task without mutating the
+    # class-level originals. This makes concurrent execution thread-safe.
+    #
+    # @param source [Attribute] The attribute being duplicated
+    #
+    # @rbs (Attribute source) -> void
+    def initialize_dup(source)
+      super
+      @children = source.children.map(&:dup)
+      remove_instance_variable(:@source) if defined?(@source)
+      remove_instance_variable(:@method_name) if defined?(@method_name)
+      @task = nil
+    end
+
     class << self
 
       # Builds multiple attributes with the same configuration.
@@ -220,15 +235,45 @@ module CMDx
     def source
       return @source if defined?(@source)
 
-      @source = parent&.method_name || begin
+      parent&.method_name || begin
         value = options[:source]
 
         if value.is_a?(Proc)
-          task ? task.instance_eval(&value) : :context
+          task ? @source = task.instance_eval(&value) : :context
         elsif value.respond_to?(:call)
-          task ? value.call(task) : :context
+          task ? @source = value.call(task) : :context
         else
-          value || :context
+          @source = value || :context
+        end
+      end
+    end
+
+    # Returns the method name for this attribute when it can be resolved
+    # statically (without a task instance). Returns nil for Proc/callable
+    # sources whose method name depends on runtime evaluation.
+    #
+    # @return [Symbol, nil] The static method name, or nil if dynamic
+    #
+    # @example
+    #   attribute.allocation_name # => :user_name
+    #
+    # @rbs () -> Symbol?
+    def allocation_name
+      return @allocation_name if defined?(@allocation_name)
+
+      @allocation_name = options[:as] || begin
+        src = options[:source]
+        source_name =
+          if parent
+            parent.allocation_name
+          elsif !src.is_a?(Proc) && !src.respond_to?(:call)
+            src || :context
+          end
+
+        if source_name.is_a?(Symbol)
+          prefix = AFFIX.call(options[:prefix]) { "#{source_name}_" }
+          suffix = AFFIX.call(options[:suffix]) { "_#{source_name}" }
+          :"#{prefix}#{name}#{suffix}"
         end
       end
     end
@@ -244,12 +289,17 @@ module CMDx
     def method_name
       return @method_name if defined?(@method_name)
 
-      @method_name = options[:as] || begin
+      result = options[:as] || begin
         prefix = AFFIX.call(options[:prefix]) { "#{source}_" }
         suffix = AFFIX.call(options[:suffix]) { "_#{source}" }
-
         :"#{prefix}#{name}#{suffix}"
       end
+
+      # Only memoize if @source is defined to avoid memoizing method
+      # name when no task is present.
+      return result unless defined?(@source)
+
+      @method_name = result
     end
 
     # Defines and verifies the entire attribute tree including nested children.
@@ -264,6 +314,15 @@ module CMDx
       end
     end
 
+    # Recursively clears the task reference from this attribute and all children.
+    # Prevents the class-level attribute from retaining the last-executed task instance.
+    #
+    # @rbs () -> void
+    def clear_task_tree!
+      @task = nil
+      children.each(&:clear_task_tree!)
+    end
+
     # @return [Hash] A hash representation of the attribute
     #
     # @example
@@ -348,29 +407,33 @@ module CMDx
       attributes(*names, **options.merge(required: true), &)
     end
 
-    # Defines the attribute method on the task and validates the configuration.
+    # Defines the attribute reader on the task class (once) and
+    # generates/validates the per-instance value (every execution).
     #
     # @raise [RuntimeError] When the method name is already defined on the task
     #
     # @rbs () -> void
     def define_and_verify
-      if task.respond_to?(method_name, true)
-        raise <<~MESSAGE
-          The method #{method_name.inspect} is already defined on the #{task.class.name} task.
-          This may be due conflicts with one of the task's user defined or internal methods/attributes.
+      name_of_method = method_name
+
+      unless task.class.method_defined?(name_of_method)
+        if task.respond_to?(name_of_method, true)
+          raise <<~MESSAGE
+            The method #{name_of_method.inspect} is already defined on the #{task.class.name} task.
+            This may be due conflicts with one of the task's user defined or internal methods/attributes.
 
-          Use :as, :prefix, and/or :suffix attribute options to avoid conflicts with existing methods.
-        MESSAGE
+            Use :as, :prefix, and/or :suffix attribute options to avoid conflicts with existing methods.
+          MESSAGE
+        end
+
+        task.class.define_method(name_of_method) do
+          attributes[name_of_method]
+        end
       end
 
       attribute_value = AttributeValue.new(self)
       attribute_value.generate
       attribute_value.validate
-
-      name_of_method = method_name
-      task.define_singleton_method(name_of_method) do
-        attributes[name_of_method]
-      end
     end
 
   end

data/lib/cmdx/attribute_registry.rb

@@ -56,7 +56,7 @@ module CMDx
     #
     # @rbs (Attribute | Array[Attribute] attributes) -> self
     def register(attributes)
-      @registry.concat(Array(attributes))
+      @registry.concat(Utils::Wrap.array(attributes))
       self
     end
 
@@ -73,29 +73,100 @@ module CMDx
     #
     # @rbs ((Symbol | String | Array[Symbol | String]) names) -> self
     def deregister(names)
-      Array(names).each do |name|
+      Utils::Wrap.array(names).each do |name|
         @registry.reject! { |attribute| matches_attribute_tree?(attribute, name.to_sym) }
       end
 
       self
     end
 
-    # Associates all registered attributes with a task and verifies their definitions.
-    # This method is called during task setup to establish attribute-task relationships
-    # and validate the attribute hierarchy.
+    # Eagerly defines attribute reader methods on the task class for all
+    # attributes whose method names can be statically resolved. Called at
+    # class definition time so readers are defined once, not per-execution.
     #
-    # @param task [Task] The task to associate with all attributes
+    # @param task_class [Class] The task class to define readers on
+    # @param attrs [Array<Attribute>] Attributes to process (defaults to all)
+    #
+    # @rbs (Class task_class, ?Array[Attribute] attrs) -> void
+    def define_readers_on!(task_class, attrs = registry)
+      attrs.each { |attr| define_reader_tree!(task_class, attr) }
+    end
+
+    # Removes eagerly defined reader methods from the task class for
+    # attributes about to be deregistered. Must be called before {#deregister}.
+    #
+    # @param task_class [Class] The task class to undefine readers on
+    # @param names [Array<Symbol, String>] Attribute method names being removed
+    #
+    # @rbs (Class task_class, (Symbol | String | Array[Symbol | String]) names) -> void
+    def undefine_readers_on!(task_class, names)
+      Utils::Wrap.array(names).each do |name|
+        sym = name.to_sym
+
+        registry.each do |attribute|
+          next unless matches_attribute_tree?(attribute, sym)
+
+          undefine_reader_tree!(task_class, attribute)
+        end
+      end
+    end
+
+    # Verifies attribute definitions against a task instance.
+    # Each attribute is duped before binding so the class-level originals
+    # are never mutated — this eliminates the concurrency hazard of
+    # shared mutable @task, @source, and @method_name state.
+    #
+    # @param task [Task] The task to verify attributes against
     #
     # @rbs (Task task) -> void
     def define_and_verify(task)
       registry.each do |attribute|
-        attribute.task = task
-        attribute.define_and_verify_tree
+        duplicate = attribute.dup
+        duplicate.task = task
+        duplicate.define_and_verify_tree
       end
     end
 
     private
 
+    # Recursively defines reader methods for an attribute and its children
+    # when the method name is statically resolvable.
+    #
+    # @param task_class [Class] The task class to define readers on
+    # @param attribute [Attribute] The attribute to define a reader for
+    #
+    # @rbs (Class task_class, Attribute attribute) -> void
+    def define_reader_tree!(task_class, attribute)
+      name = attribute.allocation_name
+
+      if name && !task_class.method_defined?(name)
+        if task_class.private_method_defined?(name)
+          raise <<~MESSAGE
+            The method #{name.inspect} is already defined on the #{task_class.name} task.
+            This may be due conflicts with one of the task's user defined or internal methods/attributes.
+
+            Use :as, :prefix, and/or :suffix attribute options to avoid conflicts with existing methods.
+          MESSAGE
+        end
+
+        task_class.define_method(name) { attributes[name] }
+      end
+
+      attribute.children.each { |child| define_reader_tree!(task_class, child) }
+    end
+
+    # Recursively removes reader methods for an attribute and its children.
+    #
+    # @param task_class [Class] The task class to undefine readers on
+    # @param attribute [Attribute] The attribute whose readers to remove
+    #
+    # @rbs (Class task_class, Attribute attribute) -> void
+    def undefine_reader_tree!(task_class, attribute)
+      name = attribute.allocation_name
+      task_class.remove_method(name) if name && task_class.method_defined?(name, false)
+      attribute.children.each { |child| undefine_reader_tree!(task_class, child) }
+    end
+
     # Recursively checks if an attribute or any of its children match the given name.
     #
     # @param attribute [Attribute] The attribute to check

data/lib/cmdx/attribute_value.rb

@@ -81,7 +81,7 @@ module CMDx
     #
     # @rbs () -> void
     def validate
-      registry = task.class.settings[:validators]
+      registry = task.class.settings.validators
 
       options.slice(*registry.keys).each do |type, opts|
         registry.validate(type, task, value, opts)
@@ -226,7 +226,7 @@ module CMDx
     def coerce_value(transformed_value)
       return transformed_value if types.empty?
 
-      registry = task.class.settings[:coercions]
+      registry = task.class.settings.coercions
       last_idx = types.size - 1
 
       types.find.with_index do |type, i|

data/lib/cmdx/callback_registry.rb

@@ -5,8 +5,13 @@ module CMDx
   #
   # Callbacks are organized by type and can be registered with optional conditions and options.
   # Each callback type represents a specific execution phase or outcome.
+  #
+  # Supports copy-on-write semantics: a duped registry shares the parent's
+  # data until a write operation triggers materialization.
   class CallbackRegistry
 
+    extend Forwardable
+
     # @rbs TYPES: Array[Symbol]
     TYPES = %i[
       before_validation
@@ -21,32 +26,43 @@ module CMDx
       on_bad
     ].freeze
 
-    # Returns the internal registry of callbacks organized by type.
-    #
-    # @return [Hash{Symbol => Set<Array>}] Hash mapping callback types to their registered callables
-    #
-    # @example
-    #   registry.registry # => { before_execution: #<Set: [[[:validate], {}]]> }
+    # @rbs TYPES_SET: Set[Symbol]
+    TYPES_SET = TYPES.to_set.freeze
+    private_constant :TYPES_SET
+
+    def_delegators :registry, :empty?
+
+    # @param registry [Hash, nil] Initial registry hash, defaults to empty
     #
-    # @rbs @registry: Hash[Symbol, Set[Array[untyped]]]
-    attr_reader :registry
-    alias to_h registry
+    # @rbs (?Hash[Symbol, Set[Array[untyped]]]? registry) -> void
+    def initialize(registry = nil)
+      @registry = registry || {}
+    end
 
-    # @param registry [Hash] Initial registry hash, defaults to empty
+    # Sets up copy-on-write state when duplicated via dup.
+    #
+    # @param source [CallbackRegistry] The registry being duplicated
     #
-    # @rbs (?Hash[Symbol, Set[Array[untyped]]] registry) -> void
-    def initialize(registry = {})
-      @registry = registry
+    # @rbs (CallbackRegistry source) -> void
+    def initialize_dup(source)
+      @parent = source
+      @registry = nil
+      super
     end
 
-    # Creates a deep copy of the registry with duplicated callable sets
+    # Returns the internal registry of callbacks organized by type.
+    # Delegates to the parent registry when not yet materialized.
     #
-    # @return [CallbackRegistry] A new instance with duplicated registry contents
+    # @return [Hash{Symbol => Set<Array>}] Hash mapping callback types to their registered callables
     #
-    # @rbs () -> CallbackRegistry
-    def dup
-      self.class.new(registry.transform_values(&:dup))
+    # @example
+    #   registry.registry # => { before_execution: #<Set: [[[:validate], {}]]> }
+    #
+    # @rbs () -> Hash[Symbol, Set[Array[untyped]]]
+    def registry
+      @registry || @parent.registry
     end
+    alias to_h registry
 
     # Registers one or more callables for a specific callback type
     #
@@ -70,10 +86,12 @@ module CMDx
     #
     # @rbs (Symbol type, *untyped callables, **untyped options) ?{ (Task) -> void } -> self
     def register(type, *callables, **options, &block)
+      materialize!
+
       callables << block if block_given?
 
-      registry[type] ||= Set.new
-      registry[type] << [callables, options]
+      @registry[type] ||= Set.new
+      @registry[type] << [callables, options]
       self
     end
 
@@ -92,11 +110,13 @@ module CMDx
     #
     # @rbs (Symbol type, *untyped callables, **untyped options) ?{ (Task) -> void } -> self
     def deregister(type, *callables, **options, &block)
+      materialize!
+
       callables << block if block_given?
-      return self unless registry[type]
+      return self unless @registry[type]
 
-      registry[type].delete([callables, options])
-      registry.delete(type) if registry[type].empty?
+      @registry[type].delete([callables, options])
+      @registry.delete(type) if @registry[type].empty?
       self
     end
 
@@ -112,12 +132,13 @@ module CMDx
     #
     # @rbs (Symbol type, Task task) -> void
     def invoke(type, task)
-      raise TypeError, "unknown callback type #{type.inspect}" unless TYPES.include?(type)
+      raise TypeError, "unknown callback type #{type.inspect}" unless TYPES_SET.include?(type)
+      return unless registry[type]
 
-      Array(registry[type]).each do |callables, options|
+      registry[type].each do |callables, options|
         next unless Utils::Condition.evaluate(task, options)
 
-        Array(callables).each do |callable|
+        Utils::Wrap.array(callables).each do |callable|
           if callable.is_a?(Symbol)
             task.send(callable)
           elsif callable.is_a?(Proc)
@@ -131,5 +152,18 @@ module CMDx
       end
     end
 
+    private
+
+    # Copies the parent's registry data into this instance,
+    # severing the copy-on-write link.
+    #
+    # @rbs () -> void
+    def materialize!
+      return if @registry
+
+      @registry = @parent.registry.transform_values(&:dup)
+      @parent = nil
+    end
+
   end
 end

data/lib/cmdx/chain.rb

@@ -31,7 +31,7 @@ module CMDx
     # @rbs @results: Array[Result]
     attr_reader :results
 
-    def_delegators :results, :index, :first, :last, :size
+    def_delegators :results, :first, :last, :size
     def_delegators :first, :state, :status, :outcome, :runtime
 
     # Creates a new chain with a unique identifier and empty results collection.
@@ -40,6 +40,7 @@ module CMDx
     #
     # @rbs () -> void
     def initialize(dry_run: false)
+      @mutex = Mutex.new
       @id = Identifier.generate
       @results = []
       @dry_run = !!dry_run
@@ -107,7 +108,7 @@ module CMDx
         raise TypeError, "must be a CMDx::Result" unless result.is_a?(Result)
 
         self.current ||= new(dry_run:)
-        current.results << result
+        current.push(result)
         current
       end
 
@@ -118,12 +119,40 @@ module CMDx
       # @return [Hash] The thread or fiber storage
       #
       # @rbs () -> Hash
-      def thread_or_fiber
-        Fiber.respond_to?(:storage) ? Fiber.storage : Thread.current
+      if Fiber.respond_to?(:storage)
+        def thread_or_fiber = Fiber.storage
+      else
+        def thread_or_fiber = Thread.current
       end
 
     end
 
+    # Thread-safe append of a result to the chain.
+    # Caches the result's index to avoid repeated O(n) lookups.
+    #
+    # @param result [Result] The result to append
+    #
+    # @return [Array<Result>] The updated results array
+    #
+    # @rbs (Result result) -> Array[Result]
+    def push(result)
+      @mutex.synchronize do
+        result.instance_variable_set(:@chain_index, @results.size)
+        @results << result
+      end
+    end
+
+    # Thread-safe lookup of a result's position in the chain.
+    #
+    # @param result [Result] The result to find
+    #
+    # @return [Integer, nil] The zero-based index or nil if not found
+    #
+    # @rbs (Result result) -> Integer?
+    def index(result)
+      @mutex.synchronize { @results.index(result) }
+    end
+
     # Returns whether the chain is running in dry-run mode.
     #
     # @return [Boolean] Whether the chain is running in dry-run mode