cmdx 2.0.0 → 2.1.0

data/lib/cmdx/retriers/fibonacci.rb

@@ -11,27 +11,44 @@ module CMDx
 
       extend self
 
+      # Hard cap on the index to keep multipliers/integer allocations bounded.
+      # `fib(78) < 2**63`, well past any realistic retry attempt. Pair with
+      # `:max_delay` for the actual sleep ceiling.
+      MAX_INDEX = 78
+
+      # Cache of computed Fibonacci numbers. Shared across calls so consecutive
+      # retries reuse prior work instead of recomputing from zero. Reads are
+      # lock-free; growth is performed on a local dup and swapped atomically
+      # under the mutex.
+      @cache = [0, 1].freeze
+      @mutex = Mutex.new
+
       # @param attempt [Integer] zero-based retry attempt
       # @param delay [Float] base delay in seconds
       # @param _prev_delay [Float, nil] ignored
       # @return [Float] computed delay
       def call(attempt, delay, _prev_delay = nil)
-        delay * sequence(attempt + 1)
+        index = attempt + 1
+        index = MAX_INDEX if index > MAX_INDEX
+        delay * fib(index)
       end
 
       private
 
-      # Iterative Fibonacci. `sequence(1) == 1`, `sequence(2) == 1`,
-      # `sequence(3) == 2`, ...
-      #
-      # @param n [Integer] one-based index into the Fibonacci sequence
-      # @return [Integer]
-      # @api private
-      def sequence(n)
-        a = 0
-        b = 1
-        n.times { a, b = b, a + b }
-        a
+      def fib(n)
+        cache = @cache
+        return cache[n] if n < cache.size
+
+        @mutex.synchronize do
+          cache = @cache
+          if cache.size <= n
+            grown = cache.dup
+            grown << (grown[-1] + grown[-2]) while grown.size <= n
+            @cache = grown.freeze
+          end
+        end
+
+        @cache[n]
       end
 
     end

data/lib/cmdx/retriers.rb

@@ -41,9 +41,12 @@ module CMDx
       retrier = callable || block
 
       if callable && block
-        raise ArgumentError, "provide either a callable or a block, not both"
+        raise ArgumentError, "retrier: provide either a callable or a block, not both"
       elsif !retrier.respond_to?(:call)
-        raise ArgumentError, "retrier must respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          retrier must respond to #call (got #{retrier.class}).
+          See https://drexed.github.io/cmdx/retries/#custom-strategies-via-the-retriers-registry
+        MSG
       end
 
       registry[name.to_sym] = retrier
@@ -53,22 +56,25 @@ module CMDx
     # @param name [Symbol]
     # @return [Retriers] self for chaining
     def deregister(name)
-      registry.delete(name.to_sym)
+      registry.delete(name)
       self
     end
 
     # @param name [Symbol]
     # @return [Boolean] whether a retrier is registered under `name`
     def key?(name)
-      registry.key?(name.to_sym)
+      registry.key?(name)
     end
 
     # @param name [Symbol]
     # @return [#call] the registered retrier
-    # @raise [ArgumentError] when `name` isn't registered
+    # @raise [UnknownEntryError] when `name` isn't registered
     def lookup(name)
       registry[name] || begin
-        raise ArgumentError, "unknown retrier: #{name.inspect}"
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown retrier #{name.inspect}; registered: #{registry.keys.inspect}.
+          See https://drexed.github.io/cmdx/retries/#built-in-strategies
+        MSG
       end
     end
 
@@ -78,7 +84,7 @@ module CMDx
     #
     # @param spec [Symbol, #call, nil]
     # @return [#call, nil]
-    # @raise [ArgumentError] when `spec` is an unknown symbol or not callable
+    # @raise [UnknownEntryError] when `spec` is an unknown symbol or not callable
     def resolve(spec)
       case spec
       when NilClass
@@ -88,7 +94,10 @@ module CMDx
       else
         return spec if spec.respond_to?(:call)
 
-        raise ArgumentError, "unknown retrier: #{spec.inspect}"
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown retrier #{spec.inspect}; expected a Symbol from #{registry.keys.inspect} or a callable.
+          See https://drexed.github.io/cmdx/retries/#built-in-strategies
+        MSG
       end
     end
 

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
@@ -90,12 +91,12 @@ module CMDx
     def run_lifecycle
       measure_duration do
         run_callbacks(:before_execution)
+        run_callbacks(:before_validation)
         run_around(:around_execution) do
-          run_callbacks(:before_validation)
           perform_work
           perform_rollback if @signal.failed?
-          run_callbacks(:after_execution)
         end
+        run_callbacks(:after_execution)
         run_callbacks(:"on_#{@signal.state}")
         run_callbacks(:"on_#{@signal.status}")
         run_callbacks(:on_ok) if @signal.ok?
@@ -104,12 +105,12 @@ 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
+      raise Fault, @result.caused_failure, cause:
     end
 
     def finalize_result
@@ -151,8 +152,6 @@ module CMDx
       @duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - start
     end
 
-    # @param event [Symbol] callback event from {Callbacks::EVENTS}
-    # @return [void]
     def run_callbacks(event)
       callbacks = @task.class.callbacks
       return if callbacks.empty?
@@ -160,9 +159,6 @@ module CMDx
       callbacks.process(event, @task)
     end
 
-    # @param event [Symbol] callback event from {Callbacks::EVENTS}
-    # @yield nested lifecycle segment wrapped by `around_execution` callbacks
-    # @return [Object] the wrapped block's return value
     def run_around(event, &)
       callbacks = @task.class.callbacks
       return yield if callbacks.empty?
@@ -181,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
 
@@ -225,25 +221,11 @@ module CMDx
       throw(Signal::TAG, Signal.failed(@task.errors.to_s, metadata: @task.metadata))
     end
 
-    # @param name [Symbol] telemetry channel from {Telemetry::EVENTS}
-    # @param payload [Hash{Symbol => Object}] forwarded onto {Telemetry::Event#payload}
-    # @return [void]
     def emit_telemetry(name, payload = EMPTY_HASH)
       telemetry = @task.class.telemetry
       return unless telemetry.subscribed?(name)
 
-      event = Telemetry::Event.new(
-        xid: Chain.current.xid,
-        cid: Chain.current.id,
-        root: @root,
-        type: @task.class.type,
-        task: @task.class,
-        tid: @task.tid,
-        name:,
-        payload:,
-        timestamp: Time.now.utc
-      )
-
+      event = Telemetry::Event.build(@task, name, root: @root, payload:)
       telemetry.emit(name, event)
     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?