cmdx 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2cf3294b8f53c29043999fe6749ffee42f6c9a52d2e4e327f1ac4589ae96c47
-  data.tar.gz: 8d73284f355b01e171bb75f69c3fab37240462140e834f96e07831402517b89c
+  metadata.gz: 8d3bfaab740912c354bf1fb028b0ba0271760974f23490a9d6b8a67a82bd1675
+  data.tar.gz: 3c8dca3e0708d701b36dc65cbf7eefa0c14a932b783226c40f9f951886c1edb0
 SHA512:
-  metadata.gz: 5c1e9c43bddefec0085027447651b20de2e1ef16c57492c060d411b08fc036435c7358bcc910fcb7b7f14a8a3d166f45d4a856b17aaa2454bdb2f5f609ca4be3
-  data.tar.gz: 382b8a147035f476f2b03fda8fc1573a4b729bfc336d9776bf04d6c3f5bd95f6617d9efa77b0bbd3576a3feae828537618c06cfa53df1b119d8ac2425ac63682
+  metadata.gz: c6d28f1702c1034b55b9ffdad6e902f3d99b741bed3b12131d0fc5f15e7538143ac5a4e15f04e82c1f922d872415256290390b93a926f7a3bc830c046603f25c
+  data.tar.gz: 63bd3228b4b1fc75acb295d0d10f734e9f7452447568e650252b43a308c1ed9e1552c16a92f7a308e3c0acc87eebe962730ab758c3139a1b0f7c3f46c3664bfd

data/CHANGELOG.md

@@ -6,12 +6,57 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [2.x.x] - UNRELEASED
 
+### Added
+- `Result#error` — convenience returning `cause` (rescued `Exception`) when a failure was raised, otherwise the `reason` `String`; `nil` for non-failed results. Lets telemetry adapters branch on type without repeating the `cause || reason` dance
+- Middlewares and lifecycle callbacks may halt the task with `success!` / `skip!` / `fail!` / `throw!` — `Runtime#execute` now wraps the middleware chain in `catch(Signal::TAG)` so a signal thrown before yielding to `next_link` becomes the task's outcome instead of an `UncaughtThrowError`
+- `CMDx::Util.deep_merge` — recursive `Hash` merge with scalar last-write-wins; used by `Context#deep_merge` and `I18nProxy` locale YAML folding
+- `CMDx::Util.deep_dup` — recursive `Hash` / `Array` copy with scalar sharing and `#dup` fallback; used by `Context#deep_dup`
+- Add `Telemetry#lookup` (subscriber list, or `UnknownEntryError` when `event` is unknown)
+- Add `CMDx.config` as an alias for `CMDx.configuration`
+- Add `key?` to the name-keyed registries `Callbacks`, `Coercions`, `Validators`, `Executors`, `Mergers`, `Retriers`, and `Deprecators`
+- `Coercions::Symbol` accepts `:max_length` (default `256`); longer strings fail with the usual coercion message (reduces symbol-table pressure from oversized untrusted strings)
+- `Coercions::Integer` honors `:base` for non-decimal string input (e.g. `"0x10"` with `base: 16`); non-`String` values ignore `:base`
+
+### Changed
+- `Executors::Thread` and `Executors::Fiber` require `concurrency >= 1` (`ArgumentError` on zero/negative, avoiding a silent hang); worker `on_job` errors are collected and the first is re-raised after workers finish
+- `Chain` synchronizes `index`, `each`, `last`, `root`, `size`, `empty?`, `freeze`, and `results` on the existing mutex; `#results` dups while the chain stays mutable; `#root` is updated on `push` / `unshift` when the new result is the root
+- `Context#initialize_copy` copies the backing table and preserves `@strict`, so `dup` / `clone` no longer share `@table`; `Context#deep_dup` preserves `@strict`; `Context#to_h` returns `table.dup` unless the context is frozen
+- `Telemetry#emit` returns immediately when the telemetry registry is empty; `Runtime` and `Pipeline` still gate lifecycle emits with `Telemetry#subscribed?` first (calling `emit` for an unknown `event` while other events exist still goes through `lookup` and raises `UnknownEntryError`)
+- `Task.optional` / `Task.required` and the matching `Inputs::ChildBuilder` helpers merge `**options` then pin `required:` (`optional` forces `false`, `required` forces `true`) so `required:` inside `**options` cannot flip polarity
+- `Retry#wait` bounds jitter: non-`Numeric` / non-finite results fall back to base `delay`; the sleep is clamped to `[0, max_delay]` when set; registry strategies, task Symbol methods, `Proc` / `instance_exec` blocks, and `#call`-ables receive `(attempt, delay, prev_delay)`
+- `Retry#build` returns `self` only when new exceptions, new options, and a replacement block are all empty — option-only subclass updates such as `retry_on(limit: 5)` apply
+- `Retriers::Exponential` caps the doubling exponent at `30` (`2 ** attempt` saturates); `Retriers::Fibonacci` memoizes the sequence (lock-free reads, mutex-guarded growth) and caps `attempt + 1` at `78`; `Retriers::DecorrelatedJitter` draws in `[delay, max(prev_delay * 3, delay)]` so the delay never sits below the configured base
+- `Pipeline#rollback_executed!` marks successful results `rolled_back` before each compensator, logs each `#rollback` failure at `error`, continues through the remaining tasks, then re-raises the **first** compensator exception so strict runs surface rollback faults
+- `Validators::Inclusion` / `Validators::Exclusion` raise `ArgumentError` when `:in` / `:within` is a `Hash` (instead of flattening into key/value pairs)
+- `Validators::Format` sends values without `#match?` through `#to_s` before matching so non-strings do not raise `NoMethodError`
+- `Coercions::DateTime` rescues `RangeError` in addition to `ArgumentError` / `TypeError` / `Date::Error` and returns `Failure`
+- `Coercions::Boolean` coerces `nil` to `false` (unknown strings still fail)
+- `Input` resolution treats `Symbol` sources whose resolved object is `false` as absent; parent reads prefer `#fetch` with a sentinel so explicit `nil` stays distinct from a missing key
+- `LogFormatters::JSON` and `LogFormatters::Logstash` rescue `JSON.dump` failures, substitute `message.inspect`, and record `logerr` so a bad payload cannot crash the logger process
+- `Inputs#deregister` ignores unknown names (same as `Outputs#deregister`; avoids `NoMethodError` on a missing entry)
+- `Railtie` uses a `{*}.yml` locale segment when `app.config.i18n.available_locales` is empty (the old `{}` segment matched no files)
+- `Errors` coerces string keys to symbols on `add`, `[]`, `added?`, `key?` / `for?`, and `delete` to match `Context`
+- `I18nProxy.register` deep-merges locale YAML so later files patch nested keys without replacing whole branches
+- `Middlewares#process` builds the wrap chain with the same iterative reverse-reduce pattern as `Callbacks#around` (no recursive lambda trampoline)
+- `Context#to_s` uses a pre-sized `String` buffer instead of `map` / `join`
+- `CMDx.reset_configuration!` walks `ObjectSpace.each_object(Class)` and clears cached registry ivars on every `Task` subclass, not only `Task`
+- Replace selected stdlib exceptions with `CMDx::Error` subclasses so `rescue CMDx::Error` covers more framework cases: `FrozenTaskError` (was `FrozenError`) when signaling after freeze; `UnknownAccessorError` (was `NoMethodError`) on strict context reader misses; `UnknownEntryError` (was `ArgumentError`) on registry misses and on unknown `Telemetry` events in `lookup` / `unsubscribe`; `UnknownLocaleError` (was `LoadError`) when the default locale file cannot be loaded
+- Broader error copy refresh in `lib/cmdx/`: registry misses list the bad key plus registered keys; validator / option errors contrast passed vs accepted keys; type mismatches name the unexpected class; short messages name the entry point (e.g. `CMDx.configure`); `MiddlewareError` names the middleware that failed to yield; nuanced cases append https://drexed.github.io/cmdx/ anchors; multi-line text prefers squiggly heredocs (`<<~MSG`) so permalinks stay on their own line in logs
+- Document the Symbol dispatch contract for callbacks, coercions, validators, and input sources (`send` / instance hooks reach private helpers); never derive those symbols from untrusted input
+- `Workflow.included` raises `ImplementationError` immediately when the host is not a `Task` subclass (instead of failing later at execution)
+- Clearer `DefinitionError` when sibling nested inputs collide on the same accessor, pointing to `:as` / `:prefix` / `:suffix` or separate `inputs` blocks
+- `Fault.for?` / `Fault.reason?` / `Fault.matches?` YARD notes explain per-call anonymous subclass allocation; hoist matchers at module scope on hot paths
+- `Settings#correlation_id`, `Result#xid`, and `Chain#initialize` YARD: `correlation_id` is a callable evaluated when the root chain is created, not a literal `String` / xid
+- Install generator comments refreshed for strict context and current registration APIs
+
+## [2.0.1] - 2026-05-09
+
 ### Changed
 - Link cause of a raised Fault exception
 - Simplify context `method_missing` lookup order (small perf boost)
 - Attempt translation of errors `full_messages`
 - Emit `:task_rolled_back` telemetry event on workflow rollback
-- `around_execution` callbacks now wrap only `Task#work` (and any `#rollback`); `before_validation` runs *before* the around-block and `after_execution` runs *after* it. Previously both were nested inside the around-block
+- Run `before_validation` before the `around_execution` stack (it used to run inside the around callbacks); the around hook still wraps input resolution, retried `work`, output verification, and post-failure `#rollback` when defined — `after_execution` remains after the stack
 
 ## [2.0.0] - 2026-05-05
 
@@ -28,14 +73,14 @@ Full runtime rewrite: the v1 state-machine plus Zeitwerk architecture is replace
 - Add `CMDx::Signal` halt token thrown via `catch(Signal::TAG)` (`:cmdx_signal`)
 - Add `Signal#ok?` / `Signal#ko?` predicates
 - Add `CMDx::Runtime` orchestrating the full task lifecycle and building the final `Result`
-- Add `CMDx::Telemetry` pub/sub for `:task_started`, `:task_deprecated`, `:task_retried`, `:task_rolled_back`, `:task_executed`; emits `Telemetry::Event` data objects with `cid`, `root`, `type`, `task`, `tid`, `name`, `payload`, `timestamp`
+- Add `CMDx::Telemetry` pub/sub for `:task_started`, `:task_deprecated`, `:task_retried`, `:task_rolled_back`, `:task_executed`; emits `Telemetry::Event` data objects with `xid`, `cid`, `root`, `type`, `task`, `tid`, `name`, `payload`, `timestamp`
 - Add `CMDx::Deprecation` for declarative class-level deprecation (`:log`, `:warn`, `:error`, Symbol, Proc, callable) with `:if` / `:unless` gating
 - Add `CMDx::Input` / `CMDx::Inputs` (replaces `Attribute` / `AttributeRegistry` / `AttributeValue`) supporting `:source`, `:default`, `:transform`, `:as`, `:prefix` / `:suffix`, and nested children via DSL block
 - Add `CMDx::Output` / `CMDx::Outputs` for first-class declared outputs verified against `task.context` after `work`. Every declared output is implicitly required — there is no `:required` option. Surface is intentionally minimal: `:default` (literal/Symbol/Proc/`#call(task)`-able fallback applied when the value is `nil`, satisfies the implicit required check), `:if` / `:unless` guards, and `:description`. Coercion, transformation, validation, and nested children are intentionally not supported on outputs — use inputs (or compute in `work`) when you need any of those
 - Add `CMDx::Util` single conditional-evaluation module (`evaluate`, `if?`, `unless?`, `satisfied?`) consolidating the v1 `Utils::*` modules
 - Add `CMDx::I18nProxy` translation façade that delegates to `I18n` when available, otherwise loads the bundled YAML and percent-interpolates with memoization
 - Add `CMDx::LoggerProxy` returning a per-task logger, `dup`-ing the base only when the task overrides `log_level` or `log_formatter`
-- Add `around_execution` callback that wraps `before_validation`, `Task#work`, any `#rollback`, and `after_execution` in a single hook. Symbol callbacks receive the continuation as their block (use `yield`); Procs/blocks/callables receive `(task, continuation)` and must invoke `continuation.call`. Multiple hooks nest in declaration order; failure to invoke the continuation raises `CMDx::CallbackError`. Sits inside middlewares but outside the state/status callbacks, so it's the right place for symmetric concerns (transactions, instrumentation, per-task logging context) without bolting them onto `middlewares.register`
+- Add `around_execution` callback nesting `before_validation`, input resolution, retried `Task#work`, output verification, `after_execution`, and post-failure `#rollback` (when defined). Symbol callbacks receive the continuation as their block (use `yield`); Procs/blocks/callables receive `(task, continuation)` and must invoke `continuation.call`. Hooks nest in declaration order; skipping the continuation raises `CMDx::CallbackError`. Lives inside middlewares but outside the `on_*` state/status callbacks — suited to transactions, instrumentation, and logging scope without extra `middlewares.register` entries (ordering of `before_validation` / `after_execution` vs this hook was refined in 2.0.1)
 - Add new exception classes: `DefinitionError`, `DeprecationError`, `ImplementationError`, `MiddlewareError`, `CallbackError`
 - Add `Task#work` abstract method (raises `ImplementationError` when not defined)
 - Add `Task#rollback` lifecycle hook, auto-invoked by Runtime on failed results when defined; surfaced via `Result#rolled_back?` and the `:task_rolled_back` event
@@ -81,11 +126,11 @@ Full runtime rewrite: the v1 state-machine plus Zeitwerk architecture is replace
 - Generated input accessors are now plain instance methods backed by `@_input_<name>` ivars set during input resolution; outputs have no accessors and are read/written directly on `task.context`
 - `Workflow` declares groups via `task` / `tasks` (still aliased) and supports `:strategy => :parallel`, `:pool_size`, `:continue_on_failure`, `:if` / `:unless` per group; defining `#work` on a workflow raises `ImplementationError`
 - `Pipeline` gains a `:parallel` strategy with `:pool_size` (replacing the removed `Parallelizer`); parallel workers share the parent fiber's chain, each get a `deep_dup`-ed context, successful child contexts are merged back into the workflow's context, and the first failed result is echoed via `throw!` to halt the pipeline. By default pending tasks are cancelled on the first failure (in-flight tasks still finish and successful contexts still merge); opt into batch semantics with `:continue_on_failure => true` to run every task to completion and aggregate failures into the workflow's `errors` (keys namespaced as `"TaskClass.input"` for input/validation errors and `"TaskClass.<status>"` for bare `fail!` reasons). `:continue_on_failure` works for both `:sequential` and `:parallel` groups.
-- `Task.callbacks`, `Task.middlewares`, `Task.coercions`, `Task.validators`, `Task.executors`, `Task.mergers`, `Task.telemetry`, `Task.inputs`, `Task.outputs` lazy-clone from the superclass (or global `Configuration`) on first access — subclasses extend rather than replace
-- `Settings` is now a frozen value object holding only `logger`, `log_formatter`, `log_level`, `log_exclusions`, `backtrace_cleaner`, `tags`, `strict_context`; every getter falls back to `CMDx.configuration`
+- `Task.callbacks`, `Task.middlewares`, `Task.coercions`, `Task.validators`, `Task.executors`, `Task.mergers`, `Task.retriers`, `Task.deprecators`, `Task.telemetry`, `Task.inputs`, `Task.outputs` lazy-clone from the superclass (or global `Configuration`) on first access — subclasses extend rather than replace
+- `Settings` is now a frozen value object holding only `logger`, `log_formatter`, `log_level`, `log_exclusions`, `backtrace_cleaner`, `tags`, `strict_context`, `correlation_id`; every getter falls back to `CMDx.configuration`
 - `Context.build` accepts anything that responds to `#context` (e.g. another `Task`), unwraps repeatedly, and only re-wraps frozen contexts; symbolizes hash keys via `#to_hash` / `#to_h`
 - `Retry` becomes a value object; `Task.retry_on` accumulates exceptions and options across the inheritance chain via `Retry#build`; supports built-in jitter strategies (`:exponential`, `:half_random`, `:full_random`, `:bounded_random`) plus Symbol / Proc / callable; retry wraps `work` only (input resolution and output verification run once, outside the retry loop)
-- All registries (`Callbacks`, `Middlewares`, `Coercions`, `Validators`, `Telemetry`, `Inputs`, `Outputs`) implement `initialize_copy` for cheap copy-on-write inheritance; `register` / `deregister` validate types up-front and raise `ArgumentError` on misuse
+- All registries (`Callbacks`, `Middlewares`, `Coercions`, `Validators`, `Executors`, `Mergers`, `Retriers`, `Deprecators`, `Telemetry`, `Inputs`, `Outputs`) implement `initialize_copy` for cheap copy-on-write inheritance; `register` / `deregister` validate types up-front and raise `ArgumentError` on misuse
 - `Coercions#coerce` returns a `Coercions::Failure` sentinel with an i18n message recorded on `task.errors`; when multiple declared coercion rules match none (and none were inline), an aggregated `cmdx.coercions.into_any` message is reported instead of the per-rule messages
 - `Validators#validate` records a message on `task.errors` for each failed rule (the individual built-in validators return `Validators::Failure`)
 - Extend `Validators::Numeric` and `Validators::Length` with `:gt` / `:lt` (strict comparison, with `:gt_message` / `:lt_message` overrides and `cmdx.validators.{numeric,length}.{gt,lt}` i18n keys), plus `:gte` / `:lte` / `:eq` / `:not_eq` aliases that normalize to `:min` / `:max` / `:is` / `:is_not`
@@ -94,10 +139,10 @@ Full runtime rewrite: the v1 state-machine plus Zeitwerk architecture is replace
 - `Result#to_h` / `to_s` / `deconstruct_keys` now include `:origin` (compact `{ task:, tid: }` hash, or `nil` for locally originated failures)
 - **BREAKING**: `Result#deconstruct` now returns `#to_h.to_a` (array of `[key, value]` pairs) instead of the fixed `[type, task, state, status, reason, metadata, cause, origin]` tuple — update any array-pattern matches to use find-patterns (`in [*, [:status, "failed"], *]`)
 - `Result#deconstruct_keys` now honors its `keys` argument — `nil` returns the full `#to_h`, a key list slices it; previously it always returned the full hash
-- `Middlewares` registry entries are now `[callable, options.freeze]` tuples — callers that read `Task.middlewares.registry` directly must map `.first` to recover the callable
+- `Middlewares` registry entries are now `[callable, options.freeze]` tuples — callers that read `Task.middlewares.registry` directly should take `.first` for the callable (per-entry options live in `.last`)
 - Slim the locale file: remove `attributes.undefined`, `coercions.unknown`, `faults.invalid`, `faults.unspecified`, `returns.*`; rename `returns.missing` → `outputs.missing`; add `nil_value` to `length` / `numeric` validator messages
 - Generators emit the new `def work` template; the install template documents the new middleware / callback / telemetry / coercion / validator registration shapes
-- Slim `Configuration` to: `middlewares`, `callbacks`, `coercions`, `validators`, `telemetry`, `default_locale`, `strict_context`, `backtrace_cleaner`, `logger`, `log_level`, `log_formatter`
+- Slim `Configuration` to: `middlewares`, `callbacks`, `coercions`, `validators`, `executors`, `mergers`, `retriers`, `deprecators`, `telemetry`, `correlation_id`, `default_locale`, `strict_context`, `backtrace_cleaner`, `log_exclusions`, `logger`, `log_level`, `log_formatter`
 - `Configuration#log_level` and `Configuration#log_formatter` now default to `nil` — treat them as optional overrides on top of `config.logger` (the default `Logger` still carries `Logger::INFO` + `LogFormatters::Line.new`). `LoggerProxy` only `dup`s the logger when a non-nil override differs from the logger's own level/formatter, so swapping `config.logger` no longer requires also clearing these fields
 
 ### Removed

data/lib/cmdx/callbacks.rb

@@ -53,11 +53,17 @@ module CMDx
       callback = callable || block
 
       if callable && block
-        raise ArgumentError, "provide either a callable or a block, not both"
+        raise ArgumentError, "callback: provide either a callable or a block, not both"
       elsif !callback.is_a?(Symbol) && !callback.respond_to?(:call)
-        raise ArgumentError, "callback must be a Symbol or respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          callback must be a Symbol or respond to #call (got #{callback.class}).
+          See https://drexed.github.io/cmdx/callbacks/#how-do-i-register-one
+        MSG
       elsif !EVENTS.include?(event)
-        raise ArgumentError, "unknown event #{event.inspect}, must be one of #{EVENTS.join(', ')}"
+        raise ArgumentError, <<~MSG.chomp
+          unknown callback event #{event.inspect}, must be one of #{EVENTS.to_a.inspect}.
+          See https://drexed.github.io/cmdx/callbacks/#what-callbacks-exist
+        MSG
       end
 
       (registry[event] ||= []) << [callback, options.freeze]
@@ -75,7 +81,12 @@ module CMDx
     # @return [Callbacks] self for chaining
     # @raise [ArgumentError] when `event` is unknown
     def deregister(event, callable = nil)
-      raise ArgumentError, "unknown event #{event.inspect}, must be one of #{EVENTS.join(', ')}" unless EVENTS.include?(event)
+      unless EVENTS.include?(event)
+        raise ArgumentError, <<~MSG.chomp
+          unknown callback event #{event.inspect}, must be one of #{EVENTS.to_a.inspect}.
+          See https://drexed.github.io/cmdx/callbacks/#what-callbacks-exist
+        MSG
+      end
 
       if callable.nil?
         registry.delete(event)
@@ -87,6 +98,12 @@ module CMDx
       self
     end
 
+    # @param name [Symbol]
+    # @return [Boolean] whether a callback is registered under `name`
+    def key?(event)
+      registry.key?(event)
+    end
+
     # @return [Boolean]
     def empty?
       registry.empty?
@@ -110,6 +127,8 @@ module CMDx
     # @return [void]
     # @raise [ArgumentError] when a callback is neither a Symbol nor responds to `#call`
     def process(event, task)
+      return if empty?
+
       callbacks = registry[event]
       return if callbacks.nil? || callbacks.empty?
 
@@ -150,18 +169,16 @@ module CMDx
 
           invoke(callable, task, cont, &cont)
 
-          called || raise(CallbackError, "#{event} callback did not invoke its continuation")
+          called || raise(CallbackError, <<~MSG.chomp)
+            #{event} callback did not invoke its continuation.
+            See https://drexed.github.io/cmdx/callbacks/#around_execution-the-wrap-the-whole-thing-hook
+          MSG
         end
       end.call
     end
 
     private
 
-    # @param callable [Symbol, Proc, #call]
-    # @param task [Task]
-    # @param extras [Array<Object>] extra args after `task` for continuation-style callbacks
-    # @return [Object] the callback's return value
-    # @raise [ArgumentError] when `callable` is invalid
     def invoke(callable, task, *extras, &)
       case callable
       when Symbol
@@ -171,7 +188,10 @@ module CMDx
       else
         return callable.call(task, *extras) if callable.respond_to?(:call)
 
-        raise ArgumentError, "callback must be a Symbol, Proc, or respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          callback must be a Symbol, Proc, or respond to #call (got #{callable.class}).
+          See https://drexed.github.io/cmdx/callbacks/#how-do-i-register-one
+        MSG
       end
     end
 

data/lib/cmdx/chain.rb

@@ -34,16 +34,27 @@ module CMDx
 
     end
 
-    attr_reader :xid, :id, :results
+    attr_reader :xid, :id
 
     # @param xid [String, nil] external correlation id (e.g. Rails `request_id`)
     #   shared across every {Result} in this chain. Resolved once by Runtime
-    #   from {Configuration#xid} when the root chain is created.
+    #   from {Settings#correlation_id} (a callable) when the root chain is
+    #   created.
     def initialize(xid = nil)
       @xid     = xid
       @id      = SecureRandom.uuid_v7
       @mutex   = Mutex.new
       @results = []
+      @root    = nil
+    end
+
+    # @return [Array<Result>] snapshot of the results stored in this chain.
+    #   While the chain is mutable a dup is returned so callers cannot mutate
+    #   internal state and see consistent ordering despite parallel pushes;
+    #   after {#freeze} the actual frozen array is returned to preserve
+    #   `Array#frozen?` semantics.
+    def results
+      @mutex.synchronize { @results.frozen? ? @results : @results.dup }
     end
 
     # Appends `result` to the chain. Thread-safe to support parallel pipelines.
@@ -51,7 +62,10 @@ module CMDx
     # @param result [Result]
     # @return [Chain] self for chaining
     def push(result)
-      @mutex.synchronize { @results << result }
+      @mutex.synchronize do
+        @results << result
+        @root = result if @root.nil? && result.respond_to?(:root?) && result.root?
+      end
       self
     end
     alias << push
@@ -61,24 +75,29 @@ module CMDx
     # @param result [Result]
     # @return [Chain] self for chaining
     def unshift(result)
-      @mutex.synchronize { @results.unshift(result) }
+      @mutex.synchronize do
+        @results.unshift(result)
+        @root = result if result.respond_to?(:root?) && result.root?
+      end
       self
     end
 
     # @param result [Result]
     # @return [Integer, nil] zero-based position of `result`, or nil when absent
     def index(result)
-      @results.index(result)
+      @mutex.synchronize { @results.index(result) }
     end
 
     # @return [Result, nil] the most recently appended result
     def last
-      @results.last
+      @mutex.synchronize { @results.last }
     end
 
     # @return [Result, nil] the root result, or nil when absent
     def root
-      @results.find(&:root?)
+      @mutex.synchronize do
+        @root || @results.find { |r| r.respond_to?(:root?) && r.root? }
+      end
     end
 
     # @return [String, nil] the state of the root result, or nil when absent
@@ -93,18 +112,18 @@ module CMDx
 
     # @return [Boolean]
     def empty?
-      @results.empty?
+      @mutex.synchronize { @results.empty? }
     end
 
     # @return [Integer]
     def size
-      @results.size
+      @mutex.synchronize { @results.size }
     end
 
     # @yield [Result] each result in insertion order
     # @return [Enumerator, Chain]
     def each(&)
-      @results.each(&)
+      results.each(&)
     end
 
     # Freezes the chain and its results. Called by Runtime teardown.

data/lib/cmdx/coercions/big_decimal.rb

@@ -13,7 +13,7 @@ module CMDx
       # @option options [Integer] :precision (14)
       # @return [BigDecimal, Coercions::Failure]
       def call(value, options = EMPTY_HASH)
-        return value if value.is_a?(BigDecimal)
+        return value if value.is_a?(::BigDecimal)
 
         BigDecimal(value, options[:precision] || 14)
       rescue ArgumentError, TypeError

data/lib/cmdx/coercions/boolean.rb

@@ -3,8 +3,8 @@
 module CMDx
   class Coercions
     # Coerces to Boolean by matching the string form against the {TRUTHY}
-    # and {FALSEY} sets (case- and whitespace-insensitive). Anything else
-    # (including `nil`) fails.
+    # and {FALSEY} sets (case- and whitespace-insensitive). `nil` becomes
+    # `false`; anything else unrecognized fails.
     module Boolean
 
       extend self
@@ -17,18 +17,12 @@ module CMDx
       # @option options [Object] reserved for future per-coercion configuration (currently ignored)
       # @return [Boolean, Coercions::Failure]
       def call(value, options = EMPTY_HASH)
-        return coercion_failure if value.nil?
+        return false if value.nil?
 
         str = value.to_s.strip.downcase
         return true if TRUTHY.include?(str)
         return false if FALSEY.include?(str)
 
-        coercion_failure
-      end
-
-      private
-
-      def coercion_failure
         type = I18nProxy.t("cmdx.types.boolean")
         Failure.new(I18nProxy.t("cmdx.coercions.into_a", type:))
       end

data/lib/cmdx/coercions/coerce.rb

@@ -23,7 +23,10 @@ module CMDx
         else
           return handler.call(value, task) if handler.respond_to?(:call)
 
-          raise ArgumentError, "coerce handler must be a Symbol, Proc, or respond to #call"
+          raise ArgumentError, <<~MSG.chomp
+            coerce handler must be a Symbol, Proc, or respond to #call (got #{handler.class}).
+            See https://drexed.github.io/cmdx/inputs/coercions/#inline-coerce-callable
+          MSG
         end
       end
 

data/lib/cmdx/coercions/date_time.rb

@@ -27,7 +27,7 @@ module CMDx
         else
           coercion_failure
         end
-      rescue ArgumentError, TypeError, ::Date::Error
+      rescue ArgumentError, RangeError, TypeError, ::Date::Error
         coercion_failure
       end
 

data/lib/cmdx/coercions/integer.rb

@@ -3,16 +3,25 @@
 module CMDx
   class Coercions
     # Coerces to Integer via `Kernel#Integer` (strict; rejects floats-as-strings).
+    # Pass `base:` to parse strings written in non-decimal radix
+    # (e.g. `"0x10"` with `base: 16`). The `:base` option is applied only
+    # when `value` is a String — for numeric inputs `Kernel#Integer` is
+    # called without a base, matching its native contract.
     module Integer
 
       extend self
 
       # @param value [Object]
       # @param options [Hash{Symbol => Object}]
-      # @option options [Object] reserved for future per-coercion configuration (currently ignored)
+      # @option options [Integer] :base radix for string parsing (default 10)
       # @return [Integer, Coercions::Failure]
       def call(value, options = EMPTY_HASH)
-        Integer(value)
+        base = options[:base]
+        if base && value.is_a?(::String)
+          Integer(value, base)
+        else
+          Integer(value)
+        end
       rescue ArgumentError, FloatDomainError, RangeError, TypeError
         type = I18nProxy.t("cmdx.types.integer")
         Failure.new(I18nProxy.t("cmdx.coercions.into_an", type:))

data/lib/cmdx/coercions/symbol.rb

@@ -2,21 +2,40 @@
 
 module CMDx
   class Coercions
-    # Coerces to Symbol via `#to_s.to_sym`. Fails only when `value` has no
-    # `#to_s` (i.e. `BasicObject` instances).
+    # Coerces to Symbol via `#to_s.to_sym`. Fails when `value` has no
+    # `#to_s` (i.e. `BasicObject` instances) or when the resulting string
+    # exceeds {MAX_LENGTH} characters.
+    #
+    # Symbols are never garbage-collected when interned from arbitrary
+    # strings, so unbounded coercion of attacker-controlled input would
+    # grow the symbol table unbounded (memory DoS). The default cap is
+    # generous for legitimate identifiers; pass `max_length:` to tighten
+    # it for hot paths or untrusted boundaries.
     module Symbol
 
       extend self
 
+      MAX_LENGTH = 256
+
       # @param value [Object]
       # @param options [Hash{Symbol => Object}]
-      # @option options [Object] reserved for future per-coercion configuration (currently ignored)
+      # @option options [Integer] :max_length (256) reject strings longer than this
       # @return [Symbol, Coercions::Failure]
       def call(value, options = EMPTY_HASH)
         return value if value.is_a?(::Symbol)
 
-        value.to_s.to_sym
+        str   = value.to_s
+        limit = options[:max_length] || MAX_LENGTH
+        return coercion_failure if str.length > limit
+
+        str.to_sym
       rescue NoMethodError
+        coercion_failure
+      end
+
+      private
+
+      def coercion_failure
         type = I18nProxy.t("cmdx.types.symbol")
         Failure.new(I18nProxy.t("cmdx.coercions.into_a", type:))
       end

data/lib/cmdx/coercions.rb

@@ -52,9 +52,12 @@ module CMDx
       coercion = callable || block
 
       if callable && block
-        raise ArgumentError, "provide either a callable or a block, not both"
+        raise ArgumentError, "coercion: provide either a callable or a block, not both"
       elsif !coercion.respond_to?(:call)
-        raise ArgumentError, "coercion must respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          coercion must respond to #call (got #{coercion.class}).
+          See https://drexed.github.io/cmdx/inputs/coercions/#declarations
+        MSG
       end
 
       registry[name.to_sym] = coercion
@@ -64,16 +67,25 @@ module CMDx
     # @param name [Symbol]
     # @return [Coercions] self for chaining
     def deregister(name)
-      registry.delete(name.to_sym)
+      registry.delete(name)
       self
     end
 
+    # @param name [Symbol]
+    # @return [Boolean] whether a coercion is registered under `name`
+    def key?(name)
+      registry.key?(name)
+    end
+
     # @param name [Symbol]
     # @return [#call] the registered coercion
-    # @raise [ArgumentError] when `name` isn't registered
+    # @raise [UnknownEntryError] when `name` isn't registered
     def lookup(name)
       registry[name] || begin
-        raise ArgumentError, "unknown coercion: #{name}"
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown coercion #{name.inspect}; registered: #{registry.keys.inspect}.
+          See https://drexed.github.io/cmdx/inputs/coercions/#built-in-coercions
+        MSG
       end
     end
 
@@ -101,7 +113,10 @@ module CMDx
       else
         return [[raw, EMPTY_HASH]] if raw.respond_to?(:call)
 
-        raise ArgumentError, "unsupported type format: #{raw.inspect}"
+        raise ArgumentError, <<~MSG.chomp
+          unsupported :coerce format #{raw.inspect}; expected Symbol, Array, Hash, or a callable.
+          See https://drexed.github.io/cmdx/inputs/coercions/#declarations
+        MSG
       end
     end
 
@@ -156,9 +171,6 @@ module CMDx
 
     private
 
-    # @param entry [Object] Array entry from a `:coerce` list
-    # @return [Array(Object, Hash)] handler + options pair
-    # @raise [ArgumentError] when `entry` is unsupported
     def normalize_entry(entry)
       case entry
       when ::Symbol, ::Proc
@@ -166,7 +178,10 @@ module CMDx
       else
         return [entry, EMPTY_HASH] if entry.respond_to?(:call)
 
-        raise ArgumentError, "unsupported coerce entry: #{entry.inspect}"
+        raise ArgumentError, <<~MSG.chomp
+          unsupported coerce entry #{entry.inspect}; expected Symbol, Proc, or a callable.
+          See https://drexed.github.io/cmdx/inputs/coercions/#inline-coerce-callable
+        MSG
       end
     end
 

data/lib/cmdx/configuration.rb

@@ -51,38 +51,53 @@ module CMDx
 
     @configuration ||= Configuration.new
   end
+  alias config configuration
 
   # Yields the global configuration for mutation.
   #
   # @yield [Configuration]
   # @return [Configuration]
   # @raise [ArgumentError] when no block is given
-  def configure
-    raise ArgumentError, "block required" unless block_given?
+  def configure(&)
+    raise ArgumentError, "CMDx.configure requires a block" unless block_given?
 
-    config = configuration
-    yield(config)
-    config
+    configuration.tap(&)
   end
 
   # Replaces the global configuration with a fresh instance and invalidates
-  # the cached registries on `Task` so new lookups rebuild from the new config.
-  # Intended for test setup/teardown.
+  # the cached registries on {Task} and every Task subclass currently in the
+  # object space, so new lookups rebuild from the new config. Intended for
+  # test setup/teardown.
+  #
+  # Walks `ObjectSpace.each_object(Class)` once — acceptable for tests but
+  # avoid calling it on a hot path.
   #
   # @return [void]
   def reset_configuration!
     @configuration = Configuration.new
     return unless defined?(Task)
 
-    Task.instance_variable_set(:@middlewares, nil)
-    Task.instance_variable_set(:@callbacks, nil)
-    Task.instance_variable_set(:@coercions, nil)
-    Task.instance_variable_set(:@validators, nil)
-    Task.instance_variable_set(:@executors, nil)
-    Task.instance_variable_set(:@mergers, nil)
-    Task.instance_variable_set(:@retriers, nil)
-    Task.instance_variable_set(:@deprecators, nil)
-    Task.instance_variable_set(:@telemetry, nil)
+    ivars = %i[
+      @middlewares
+      @callbacks
+      @coercions
+      @validators
+      @executors
+      @mergers
+      @retriers
+      @deprecators
+      @telemetry
+    ].freeze
+
+    ObjectSpace.each_object(Class) do |klass|
+      next unless klass <= Task
+
+      ivars.each do |iv|
+        next unless klass.instance_variable_defined?(iv)
+
+        klass.instance_variable_set(iv, nil)
+      end
+    end
   end
 
 end