cmdx 2.0.1 → 2.1.0

data/lib/cmdx/retry.rb

@@ -20,6 +20,7 @@ module CMDx
     #   `:decorrelated_jitter`) or custom
     # @yieldparam attempt [Integer]
     # @yieldparam delay [Float]
+    # @yieldparam prev_delay [Float, nil]
     def initialize(exceptions, options = EMPTY_HASH, &block)
       @exceptions = exceptions.flatten
       @options    = options.freeze
@@ -28,15 +29,17 @@ module CMDx
 
     # Returns a new Retry layering `new_exceptions` and `new_options` onto the
     # current one. Used for inheritance so subclasses extend rather than
-    # replace.
+    # replace. Returns `self` only when *every* override (exceptions, options,
+    # and block) is empty so option-only updates such as `retry_on(limit: 5)`
+    # still take effect.
     #
     # @param new_exceptions [Array<Class>]
     # @param new_options [Hash{Symbol => Object}]
     # @param block [#call, nil] replacement jitter callable (falls back to the prior block)
-    # @yield [attempt, delay] optional replacement jitter block
+    # @yield [attempt, delay, prev_delay] optional replacement jitter block
     # @return [Retry]
     def build(new_exceptions, new_options, &block)
-      return self if new_exceptions.empty?
+      return self if new_exceptions.empty? && new_options.empty? && block.nil?
 
       merged_exceptions = exceptions | new_exceptions.flatten
       merged_options    = @options.merge(new_options)
@@ -66,6 +69,16 @@ module CMDx
 
     # Sleeps `attempt`'s jittered/bounded delay. No-op when the base delay is zero.
     #
+    # Custom jitter callables (registry, task Symbol method, `Proc` / block via
+    # `instance_exec` on the task, and other `#call`-ables) always receive
+    # `(attempt, delay, prev_delay)` so strategies share one shape; ignore
+    # `prev_delay` when you do not need decorrelated threading.
+    #
+    # Non-numeric or non-finite jitter results are sanitized to the base `delay`
+    # and the final sleep is always clamped to `[0, max_delay]` when `max_delay`
+    # is set, preventing self-DoS from a buggy jitter returning `Float::INFINITY`
+    # or a non-Numeric value.
+    #
     # @param attempt [Integer] zero-based retry attempt number
     # @param task [Task, nil] used as receiver for Symbol/Proc jitter strategies
     # @param prev_delay [Float, nil] previous computed delay; only consumed by
@@ -85,18 +98,19 @@ module CMDx
           if registry.key?(jitter)
             registry.lookup(jitter).call(attempt, delay, prev_delay)
           else
-            task.send(jitter, attempt, delay)
+            task.send(jitter, attempt, delay, prev_delay)
           end
         when Proc
-          task.instance_exec(attempt, delay, &jitter)
+          task.instance_exec(attempt, delay, prev_delay, &jitter)
         else
           if jitter.respond_to?(:call)
-            jitter.call(attempt, delay)
+            jitter.call(attempt, delay, prev_delay)
           else
             delay
           end
         end
 
+      d = delay unless d.is_a?(Numeric) && d.finite?
       d = d.clamp(0, max_delay) if max_delay
       Kernel.sleep(d) if d.positive?
       d
@@ -126,13 +140,6 @@ module CMDx
 
     private
 
-    # Resolves the retriers registry to consult for built-in jitter strategies.
-    # Prefers the task class's registry (so per-task `register(:retrier, ...)`
-    # overrides take effect) and falls back to the global configuration when
-    # no task is supplied.
-    #
-    # @param task [Task, nil]
-    # @return [Retriers]
     def retriers_registry(task)
       if task && task.class.respond_to?(:retriers)
         task.class.retriers

data/lib/cmdx/runtime.rb

@@ -6,13 +6,14 @@ module CMDx
   # retry), output verification, rollback on failure, result finalization,
   # and teardown (freeze + chain clear).
   #
-  # Signal propagation: Runtime wraps `work` in `catch(Signal::TAG)` so
-  # `success!` / `skip!` / `fail!` / `throw!` break out cleanly. Raised
-  # Faults are converted to echoed signals (carrying the upstream failed
-  # result as `:origin`); other `StandardError`s become failed signals with
-  # the exception as `:cause`. `execute!` (strict mode) re-raises on failure
-  # after the result is finalized, raising a {Fault} built from the deepest
-  # originating result so `fault.task` points at the leaf that failed.
+  # Signal propagation: `work` and the surrounding middleware/callback chain
+  # both run inside `catch(Signal::TAG)`, so `success!` / `skip!` / `fail!` /
+  # `throw!` halt cleanly from anywhere. Raised Faults become echoed signals
+  # (with the upstream result as `:origin`); other `StandardError`s become
+  # failed signals (with the exception as `:cause`). In strict mode,
+  # `execute!` re-raises from `ensure` using a {Fault} built from the
+  # deepest originating result, so `fault.task` points at the leaf that
+  # failed.
   #
   # @note Always used via the class method; never new Runtime manually.
   # @see Task.execute
@@ -51,13 +52,12 @@ module CMDx
         emit_telemetry(:task_started)
         run_deprecation
         run_lifecycle
-        finalize_result
-        raise_signal! if @strict
       end
 
-      @result
+      finalize_result
     ensure
       run_teardown
+      raise_signal!
     end
 
     private
@@ -71,10 +71,11 @@ module CMDx
     end
 
     def run_middlewares(&)
-      middlewares = @task.class.middlewares
-      return yield if middlewares.empty?
-
-      middlewares.process(@task, &)
+      @signal = catch(Signal::TAG) do
+        middlewares = @task.class.middlewares
+        middlewares.empty? ? yield : middlewares.process(@task, &)
+        @signal # Return non-middleware signal
+      end
     end
 
     def run_deprecation
@@ -104,9 +105,9 @@ module CMDx
     end
 
     def raise_signal!
-      return unless @result.failed?
+      return unless @strict && @result&.failed?
 
-      cause = @signal.cause
+      cause = @result.cause
       raise cause if cause && !cause.is_a?(Fault)
 
       raise Fault, @result.caused_failure, cause:
@@ -176,7 +177,7 @@ module CMDx
       rescue Error => e
         raise(e)
       rescue StandardError => e
-        Signal.failed("[#{e.class}] #{e.message}", cause: e, metadata: @task.metadata)
+        Signal.failed(Util.to_error_s(e), cause: e, metadata: @task.metadata)
       end
     end
 

data/lib/cmdx/settings.rb

@@ -50,7 +50,10 @@ module CMDx
       end
     end
 
-    # @return [Array<Symbol>] keys to exclude from logging
+    # @return [Array<Symbol>] keys to exclude from `Runtime` log output.
+    #   Matched against {Result#to_h} keys. Common values for redaction:
+    #   `:context` (may contain secrets / PII), `:cause` (raw exception),
+    #   `:reason` (may embed exception messages from unhandled errors).
     def log_exclusions
       @options.fetch(:log_exclusions) do
         CMDx.configuration.log_exclusions
@@ -64,14 +67,9 @@ module CMDx
       end
     end
 
-    # Returns a fresh array each call so callers can mutate the result
-    # without affecting other tasks (or hitting `FrozenError` on the
-    # shared sentinel).
-    #
-    # @return [Array<Symbol, String>] task tags, surfaced on result hashes
+    # @return [Array<Symbol, String>] task tags
     def tags
-      tags = @options[:tags]
-      tags ? tags.dup : []
+      @options[:tags] || EMPTY_ARRAY
     end
 
     # @return [Boolean] whether this task's {Context} should raise on
@@ -83,7 +81,9 @@ module CMDx
       end
     end
 
-    # @return [String, nil] correlation id or the global configuration's correlation id
+    # @return [#call, nil] callable that produces a correlation id when invoked
+    #   by Runtime at root-chain construction. Resolution order:
+    #   task-level setting → {Configuration#correlation_id} → nil.
     def correlation_id
       @options.fetch(:correlation_id) do
         CMDx.configuration.correlation_id

data/lib/cmdx/signal.rb

@@ -76,7 +76,7 @@ module CMDx
       # @return [Signal] new instance mirroring `other`
       # @raise [ArgumentError] when `other` is neither a Signal nor a Result
       def echoed(other, **options)
-        raise ArgumentError, "must be a Result or Signal" unless other.is_a?(Result) || other.is_a?(Signal)
+        raise ArgumentError, "Signal.echoed expected a Result or Signal (got #{other.class})" unless other.is_a?(Result) || other.is_a?(Signal)
 
         options[:origin] = other if other.is_a?(Result) && !options.key?(:origin)
         new(other.state, other.status, **options, reason: other.reason)

data/lib/cmdx/task.rb

@@ -53,6 +53,9 @@ module CMDx
       # @option options [Array<Symbol>] :log_exclusions (see {Settings#initialize})
       # @option options [Array<Symbol, String>] :tags (see {Settings#initialize})
       # @option options [Boolean] :strict_context (see {Settings#initialize})
+      # @option options [#call] :correlation_id callable returning a String id
+      #   resolved once by {Runtime} when the root chain is acquired; surfaces
+      #   as `result.xid` (see {Settings#correlation_id})
       # @return [Settings]
       def settings(options = EMPTY_HASH)
         @settings ||=
@@ -190,7 +193,12 @@ module CMDx
           inputs.register(self, ...)
         when :output
           outputs.register(...)
-        else raise ArgumentError, "unknown registry type: #{type.inspect}"
+        else
+          raise ArgumentError, <<~MSG.chomp
+            unknown registry type #{type.inspect};
+            expected one of [:middleware, :callback, :coercion, :validator, :executor, :merger, :retrier, :deprecator, :input, :output].
+            See https://drexed.github.io/cmdx/configuration/#registrations-register-deregister
+          MSG
         end
       end
 
@@ -221,7 +229,12 @@ module CMDx
           inputs.deregister(self, ...)
         when :output
           outputs.deregister(...)
-        else raise ArgumentError, "unknown registry type: #{type.inspect}"
+        else
+          raise ArgumentError, <<~MSG.chomp
+            unknown registry type #{type.inspect};
+            expected one of [:middleware, :callback, :coercion, :validator, :executor, :merger, :retrier, :deprecator, :input, :output].
+            See https://drexed.github.io/cmdx/configuration/#registrations-register-deregister
+          MSG
         end
       end
 
@@ -280,6 +293,8 @@ module CMDx
       alias input inputs
 
       # Declares optional inputs (shorthand for `inputs ..., required: false`).
+      # An explicit `required:` in `options` is ignored — use {.inputs} when
+      # you need to set the flag dynamically.
       #
       # @param names [Array<Symbol>]
       # @param options [Hash{Symbol => Object}] see {Input#initialize}
@@ -296,10 +311,12 @@ module CMDx
       # @option options [Object] :validate (see {Validators#extract})
       # @yield nested-input DSL block (see {Inputs::ChildBuilder})
       def optional(*names, **options, &)
-        register(:input, *names, required: false, **options, &)
+        register(:input, *names, **options, required: false, &)
       end
 
       # Declares required inputs (shorthand for `inputs ..., required: true`).
+      # An explicit `required:` in `options` is ignored — use {.inputs} when
+      # you need to set the flag dynamically.
       #
       # @param names [Array<Symbol>]
       # @param options [Hash{Symbol => Object}] see {Input#initialize}
@@ -316,7 +333,7 @@ module CMDx
       # @option options [Object] :validate (see {Validators#extract})
       # @yield nested-input DSL block (see {Inputs::ChildBuilder})
       def required(*names, **options, &)
-        register(:input, *names, required: true, **options, &)
+        register(:input, *names, **options, required: true, &)
       end
 
       # @return [Hash{Symbol => Hash}] serialized input definitions
@@ -382,23 +399,29 @@ module CMDx
 
       private
 
-      # @param input [Input] defines `##{input.accessor_name}` when not already taken
-      # @return [void]
-      # @raise [DefinitionError] when the accessor name collides
       def define_input_reader(input)
         accessor = input.accessor_name
 
         if method_defined?(accessor) || private_method_defined?(accessor)
-          raise DefinitionError,
-            "cannot define input #{accessor.inspect}: ##{accessor} is already defined on #{self}"
+          raise DefinitionError, <<~MSG.chomp
+            Cannot define input #{accessor.inspect}: ##{accessor} is already defined on #{self}.
+
+            Typical cause #1: there's a method or private method with the same name as the input.
+
+            Typical cause #2: two sibling `inputs` groups declare the same nested name
+            (for example `inputs :a, :b do ... required :x ... end`, which defines `:x` twice).
+
+            Fix: rename with `:as`, `:prefix`, or `:suffix`, or give each parent its own
+            `inputs ... do ... end` block so nested accessors do not collide.
+
+            https://drexed.github.io/cmdx/inputs/definitions
+          MSG
         end
 
         define_method(accessor) { instance_variable_get(input.ivar_name) }
         input.children.each { |child| define_input_reader(child) }
       end
 
-      # @param input [Input] removes `##{input.accessor_name}` if defined on this class
-      # @return [void]
       def undefine_input_reader(input)
         accessor = input.accessor_name
         undef_method(accessor) if method_defined?(accessor)
@@ -449,65 +472,87 @@ module CMDx
     # @return [void]
     # @raise [ImplementationError] when the subclass doesn't override
     def work
-      raise ImplementationError, "undefined method #{self.class}#work"
+      raise ImplementationError, <<~MSG.chomp
+        #{self.class} must implement #work.
+        See https://drexed.github.io/cmdx/basics/setup/#structure
+      MSG
     end
 
-    private
-
-    # Signals a successful halt.
+    # Halts `#work` early with a successful outcome. Any `sigdata` is merged
+    # onto {#metadata} before the signal is thrown.
     #
-    # @param reason [String, nil]
-    # @param sigdata [Hash{Symbol => Object}] arbitrary metadata merged into {#metadata} before throwing
-    # @option sigdata [Object] arbitrary entries merged via `metadata.merge!`
-    # @return [void] throws `Signal::TAG`; never returns
-    # @raise [FrozenError] when the task has already been frozen (post-execution)
-    # @note Must be called from inside `work` (inside Runtime's `catch(:cmdx_signal)`).
+    # @param reason [String, nil] human-readable explanation surfaced on the {Result}
+    # @param sigdata [Hash{Symbol => Object}] extra metadata merged into {#metadata}
+    # @return [void] never returns; throws {Signal::TAG}
+    # @raise [FrozenTaskError] when the task has already been executed
     def success!(reason = nil, **sigdata)
-      raise FrozenError, "cannot throw signals" if frozen?
+      if frozen?
+        raise FrozenTaskError, <<~MSG.chomp
+          cannot call :success! on #{self.class}; the task has already been executed and frozen.
+          See https://drexed.github.io/cmdx/outcomes/result/#lifecycle-predicates
+        MSG
+      end
 
       metadata.merge!(sigdata) unless sigdata.empty?
       throw(Signal::TAG, Signal.success(reason, metadata:))
     end
 
-    # Signals a skip (interrupted + skipped).
+    # Halts `#work` and marks the {Result} as `skipped`. Any `sigdata` is merged
+    # onto {#metadata} before the signal is thrown.
     #
-    # @param reason [String, nil]
-    # @param sigdata [Hash{Symbol => Object}] arbitrary metadata merged into {#metadata} before throwing
-    # @option sigdata [Object] arbitrary entries merged via `metadata.merge!`
-    # @return [void] throws `Signal::TAG`; never returns
-    # @raise [FrozenError]
+    # @param reason [String, nil] human-readable explanation surfaced on the {Result}
+    # @param sigdata [Hash{Symbol => Object}] extra metadata merged into {#metadata}
+    # @return [void] never returns; throws {Signal::TAG}
+    # @raise [FrozenTaskError] when the task has already been executed
     def skip!(reason = nil, **sigdata)
-      raise FrozenError, "cannot throw signals" if frozen?
+      if frozen?
+        raise FrozenTaskError, <<~MSG.chomp
+          cannot call :skip! on #{self.class}; the task has already been executed and frozen.
+          See https://drexed.github.io/cmdx/outcomes/result/#lifecycle-predicates
+        MSG
+      end
 
       metadata.merge!(sigdata) unless sigdata.empty?
       throw(Signal::TAG, Signal.skipped(reason, metadata:))
     end
 
-    # Signals a failure. Captures current call frames as the signal
-    # backtrace for Fault propagation.
+    # Halts `#work` and marks the {Result} as `failed`. Captures the current
+    # caller frames for the {Fault} backtrace and merges any `sigdata` onto
+    # {#metadata} before the signal is thrown.
     #
-    # @param reason [String, nil]
-    # @param sigdata [Hash{Symbol => Object}] arbitrary metadata merged into {#metadata} before throwing
-    # @option sigdata [Object] arbitrary entries merged via `metadata.merge!`
-    # @return [void] throws `Signal::TAG`; never returns
-    # @raise [FrozenError]
+    # @param reason [String, nil] human-readable explanation surfaced on the {Result}/{Fault}
+    # @param sigdata [Hash{Symbol => Object}] extra metadata merged into {#metadata}
+    # @return [void] never returns; throws {Signal::TAG}
+    # @raise [FrozenTaskError] when the task has already been executed
     def fail!(reason = nil, **sigdata)
-      raise FrozenError, "cannot throw signals" if frozen?
+      if frozen?
+        raise FrozenTaskError, <<~MSG.chomp
+          cannot call :fail! on #{self.class}; the task has already been executed and frozen.
+          See https://drexed.github.io/cmdx/outcomes/result/#lifecycle-predicates
+        MSG
+      end
 
       metadata.merge!(sigdata) unless sigdata.empty?
       throw(Signal::TAG, Signal.failed(reason, metadata:, backtrace: caller_locations(1)))
     end
 
-    # Re-throws a failed peer Result's signal through this task. No-op when
-    # `other` didn't fail.
+    # Echoes another {Result} or {Signal}'s failure outcome from this task. A
+    # no-op when `other` is not failed, letting callers conditionally bubble up
+    # nested failures without branching. Captures caller frames for the {Fault}
+    # backtrace and merges any `sigdata` onto {#metadata} before the signal is
+    # thrown.
     #
-    # @param other [Result]
-    # @param sigdata [Hash{Symbol => Object}] arbitrary metadata merged into {#metadata} before echoing
-    # @option sigdata [Object] arbitrary entries merged via `metadata.merge!`
-    # @return [void]
-    # @raise [FrozenError]
+    # @param other [Result, Signal] upstream outcome to mirror
+    # @param sigdata [Hash{Symbol => Object}] extra metadata merged into {#metadata}
+    # @return [void, nil] returns `nil` when `other` is not failed; otherwise throws {Signal::TAG}
+    # @raise [FrozenTaskError] when the task has already been executed
     def throw!(other, **sigdata)
-      raise FrozenError, "cannot throw signals" if frozen?
+      if frozen?
+        raise FrozenTaskError, <<~MSG.chomp
+          cannot call :throw! on #{self.class}; the task has already been executed and frozen.
+          See https://drexed.github.io/cmdx/outcomes/result/#lifecycle-predicates
+        MSG
+      end
 
       return unless other.failed?
 

data/lib/cmdx/telemetry.rb

@@ -57,11 +57,17 @@ module CMDx
       subscriber = callable || block
 
       if callable && block
-        raise ArgumentError, "provide either a callable or a block, not both"
+        raise ArgumentError, "subscriber: provide either a callable or a block, not both"
       elsif !subscriber.respond_to?(:call)
-        raise ArgumentError, "subscriber must respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          subscriber must respond to #call (got #{subscriber.class}).
+          See https://drexed.github.io/cmdx/configuration/#telemetry
+        MSG
       elsif !EVENTS.include?(event)
-        raise ArgumentError, "unknown event #{event.inspect}, must be one of #{EVENTS.join(', ')}"
+        raise ArgumentError, <<~MSG.chomp
+          unknown telemetry event #{event.inspect}, must be one of #{EVENTS.inspect}.
+          See https://drexed.github.io/cmdx/configuration/#telemetry
+        MSG
       end
 
       (registry[event] ||= []) << subscriber
@@ -74,14 +80,20 @@ module CMDx
     # @param event [Symbol] one of {EVENTS}
     # @param callable [#call] the subscriber to remove
     # @return [Telemetry] self for chaining
-    # @raise [ArgumentError] when `event` is unknown
+    # @raise [UnknownEntryError] when `event` is unknown
     def unsubscribe(event, callable)
-      raise ArgumentError, "unknown event #{event.inspect}, must be one of #{EVENTS.join(', ')}" unless EVENTS.include?(event)
+      unless EVENTS.include?(event)
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown telemetry event #{event.inspect}, must be one of #{EVENTS.inspect}.
+          See https://drexed.github.io/cmdx/configuration/#telemetry
+        MSG
+      end
 
-      return self unless subscribed?(event)
+      if (subscribers = registry[event])
+        subscribers.delete(callable)
+        registry.delete(event) if subscribers.empty?
+      end
 
-      registry[event].delete(callable)
-      registry.delete(event) if registry[event].empty?
       self
     end
 
@@ -91,6 +103,18 @@ module CMDx
       registry.key?(event)
     end
 
+    # @param event [Symbol]
+    # @return [#call]
+    # @raise [UnknownEntryError] when `event` isn't registered
+    def lookup(event)
+      registry[event] || begin
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown telemetry event #{event.inspect}; registered: #{registry.keys.inspect}.
+          See https://drexed.github.io/cmdx/configuration/#telemetry
+        MSG
+      end
+    end
+
     # @return [Boolean]
     def empty?
       registry.empty?
@@ -113,9 +137,12 @@ module CMDx
     # @param payload [Event]
     # @return [void]
     def emit(event, payload)
-      return unless (subscribers = registry[event])
+      return if empty?
+
+      subscribers = lookup(event)
+      return if subscribers.nil? || subscribers.empty?
 
-      subscribers.each { |s| s.call(payload) }
+      subscribers.each { |callable| callable.call(payload) }
     end
 
   end

data/lib/cmdx/util.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Shared helpers for resolving `:if` / `:unless` conditional options across
-  # tasks, callbacks, inputs, outputs, validators, and deprecations. Normalizes
-  # booleans, symbols (method names), procs, and call-ables into a truth value.
+  # Shared helpers for `:if` / `:unless` gates, recursive hash merge/dup, and
+  # related tree utilities used across tasks, context, and i18n.
   module Util
 
     extend self
@@ -28,7 +27,8 @@ module CMDx
       else
         return condition.call(receiver, *args) if condition.respond_to?(:call)
 
-        raise ArgumentError, "condition must be a Symbol, Proc, or respond to #call"
+        raise ArgumentError,
+          "condition must be a Symbol, Proc, or respond to #call (got #{condition.class})"
       end
     end
 
@@ -69,5 +69,51 @@ module CMDx
         unless?(condition_unless, receiver, *args)
     end
 
+    # Recursively merges two Hash-like trees. When both values at a key are
+    # Hashes, they merge recursively; otherwise the right-hand value wins
+    # (last-write-wins). When either top-level operand is not a Hash, returns
+    # `rhs` unchanged — useful when folding unknown YAML roots.
+    #
+    # @param lhs [Object] left tree (typically a Hash)
+    # @param rhs [Object] right tree (typically a Hash)
+    # @return [Object] merged Hash or `rhs` when a Hash-only merge is impossible
+    def deep_merge(lhs, rhs)
+      return rhs unless lhs.is_a?(Hash) && rhs.is_a?(Hash)
+
+      lhs.merge(rhs) { |_key, l, r| deep_merge(l, r) }
+    end
+
+    # Returns a deep copy of `value`. Immutable scalars (`Numeric`, `Symbol`,
+    # booleans, `nil`) are returned as-is; `Hash` and `Array` are walked
+    # recursively; other objects use `#dup`, falling back to the original when
+    # `#dup` raises.
+    #
+    # @param value [Object]
+    # @return [Object]
+    def deep_dup(value)
+      case value
+      when Numeric, Symbol, TrueClass, FalseClass, NilClass
+        value
+      when Hash
+        value.each_with_object({}) { |(k, v), acc| acc[k] = deep_dup(v) }
+      when Array
+        value.map { |e| deep_dup(e) }
+      else
+        begin
+          value.dup
+        rescue StandardError
+          value
+        end
+      end
+    end
+
+    # Returns a string representation of `error` in the format `[Class] Message`.
+    #
+    # @param error [Exception]
+    # @return [String]
+    def to_error_s(error)
+      "[#{error.class}] #{error.message}"
+    end
+
   end
 end

data/lib/cmdx/validators/absence.rb

@@ -19,7 +19,7 @@ module CMDx
           elsif value.respond_to?(:empty?)
             !value.empty?
           else
-            !value.nil?
+            !!value
           end
 
         return unless present

data/lib/cmdx/validators/exclusion.rb

@@ -19,22 +19,29 @@ module CMDx
       # @raise [ArgumentError] when neither `:in` nor `:within` is given
       def call(value, options = EMPTY_HASH)
         values = options[:in] || options[:within]
-        raise ArgumentError, "exclusion validator requires :in or :within option" if values.nil?
+        if values.nil?
+          raise ArgumentError, <<~MSG.chomp
+            exclusion validator requires :in or :within (got #{options.keys.inspect}).
+            See https://drexed.github.io/cmdx/inputs/validations/#exclusion
+          MSG
+        elsif values.is_a?(Hash)
+          raise ArgumentError, <<~MSG.chomp
+            exclusion validator :in/:within does not accept a Hash; pass an Array,
+            Set, Range, or other Enumerable (e.g. `#{values.inspect}.keys`).
+            See https://drexed.github.io/cmdx/inputs/validations/#exclusion
+          MSG
+        end
 
         if values.is_a?(Range)
           within_failure(values.begin, values.end, options) if values.cover?(value)
-        elsif Array(values).any? { |v| v === value }
-          of_failure(values, options)
+        else
+          enum = values.is_a?(Enumerable) ? values : [values]
+          of_failure(enum, options) if enum.any? { |v| v === value }
         end
       end
 
       private
 
-      # @param values [Enumerable] collection rendered into the failure message
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :of_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def of_failure(values, options)
         values = values.map(&:inspect).join(", ")
         message = options[:of_message] || options[:message]
@@ -43,13 +50,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.exclusion.of", values:))
       end
 
-      # @param min [Object] range/exclusion lower bound
-      # @param max [Object] range/exclusion upper bound
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :in_message
-      # @option options [String] :within_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def within_failure(min, max, options)
         message = options[:in_message] || options[:within_message] || options[:message]
         message %= { min:, max: } unless message.nil?