cmdx 1.21.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1acff12a85519d3546d8c2c6b8d9a8fc6330e731826a9a4a359907631e7afa82
-  data.tar.gz: 69c814dc115c70dc36ab02e7462d00a5b802490d39b7f4bc1fb2c9e5c666c55e
+  metadata.gz: b679253afacaaa6d2b1ef842026e3b535ee1b0378167bfa0ebfe5b8c93508e83
+  data.tar.gz: 1751b980c3af7d2e4950d6f1447d17883f94ba1e26ff1a550d90043fbb30b956
 SHA512:
-  metadata.gz: f2bc1eb34789f888bffc84b9ebb65252fc23ea8d598465c9ff853670ab44c9e640988b2a528ed97ff53cc1774a26e35a87706a9056aa7fc55f6604e73540cb29
-  data.tar.gz: 5c7af44bda7a2d7371c8f62183dde2195bf9b27382c65c379bc8bfd94321d7b3ab61ad41888a9a1dad57c4e606de843f4d479581cc2cea20aeb3fb8996afcd52
+  metadata.gz: b6998f0a2d795797ca412008afb29eb8c7b8240eeda91a6f88cccae9b77c3250b1b8616d67d661bb82aab6f8d8c2b7f32b9cbc5e099fe1989eb7efd3d927d457
+  data.tar.gz: a4240ac375f5488dc3b312f19d0f556f8f1e78ed84189288de3fea8d82a3eda1586094d2ef45722450c95426ec007f400d926c327f5c2ddb8ad25415f2246187

data/CHANGELOG.md

@@ -4,7 +4,124 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [UNRELEASED]
+## [2.0.0] - UNRELEASED
+
+Full runtime rewrite: the v1 state-machine plus Zeitwerk architecture is replaced by an explicit signal-based runtime, immutable results, fiber-local chains, and a slimmer registry surface. See [docs/v2-migration.md](docs/v2-migration.md) for the full upgrade guide.
+
+### Added
+- Add `CMDx::I18nProxy.tr` helper that translates a `reason` through the i18n layer when a matching key is present and falls back to the literal reason (or the `cmdx.reasons.unspecified` default when nil). `Fault#initialize` and `Pipeline` failure aggregation now route `result.reason` through it, so failure messages can be localized via translation keys without breaking literal-string reasons.
+- Add `xid` correlation id on `Chain`, `Result`, and `Telemetry::Event`, sourced once per root execution from `CMDx.configuration.correlation_id` (a callable). Useful for threading external ids like Rails `request_id` through every task in a chain so they can be filtered together in logs/telemetry.
+- Add `Context#as_json` / `Context#to_json` — JSON serialization delegating to `#to_h`
+- Add `Errors#as_json` / `Errors#to_json` — JSON serialization delegating to `#to_h`
+- Add `Result#as_json` / `Result#to_json` — JSON serialization delegating to the memoized `#to_h`
+- Add `Input#as_json` / `Input#to_json` — JSON serialization delegating to `#to_h`
+- Add `Output#as_json` / `Output#to_json` — JSON serialization delegating to `#to_h`
+- 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::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 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
+- Add saga-style pipeline rollback: when a `Workflow` halts, `Pipeline` walks every previously executed task instance whose result is `success?` in reverse execution order and invokes `#rollback` (when defined), then flips that result's `rolled_back?` to `true`. Skipped tasks are excluded; the failing task is rolled back by Runtime and not re-invoked. Exceptions raised inside a compensator propagate — handling them is the developer's responsibility. Applies across groups, within `continue_on_failure: true` groups, and to `:parallel` groups (compensators see the per-task `deep_dup`'d context)
+- Add `Task#success!` for signaling a successful halt, joining `skip!` / `fail!` / `throw!`
+- Add `Task.execute` / `Task.execute!` as the execution entry points (aliased as `call` / `call!` for backward compatibility)
+- Add `Task#execute(strict:)` instance method (aliased as `#call`)
+- Add `Result#on(:success, :failed, ...)` chainable predicate-dispatch helper
+- Add `Result#deconstruct` / `Result#deconstruct_keys` for pattern matching; `deconstruct` returns `#to_h.to_a` pairs and `deconstruct_keys(keys)` slices `#to_h` (`nil` returns the full hash)
+- Add `Result#strict?`, `Result#deprecated?`, `Result#duration`, `Result#index`, `Result#root?`, `Result#backtrace`, `Result#errors`, `Result#tags`, `Result#origin`, and `Result#ctx` alias
+- Add `Signal#origin` / `Result#origin` — upstream `Result` a signal/result was echoed from (`nil` for locally originated failures); set by `Task#throw!`, `Pipeline` when propagating workflow failures, and `Runtime` when rescuing a `Fault` inside `work`
+- Add `Chain#unshift`, `Chain#root`, `Chain#state`, `Chain#status`, `Chain#last`, `Chain#freeze`; Runtime `unshift`s the root result (so `chain.root` and `chain[0]` point to the outermost task) and freezes the chain on root teardown
+- Add `Fault.for?(*tasks)`, `Fault.reason?(reason)`, and `Fault.matches?(&block)` anonymous matcher subclasses suitable for `rescue`
+- Add `include Enumerable` to `Errors`, `Chain`, and `Context`, exposing `map`, `select`, `find`, `include?`, `to_a`, `any?`, `all?`, `group_by`, `partition`, etc.
+- Add `Set`-backed deduping per key on `Errors`, plus `keys`, `each_key`, `each_value`, `count`, `delete`, `clear`, `full_messages`, `to_hash(full)`
+- Add `Context#keys`, `values`, `empty?`, `size`, `delete`, `clear`, `eql?` / `==`, `hash`, `deep_dup`, `respond_to_missing?`, and `Context#merge` that accepts any context-like object
+- Add `Coercions::Coerce` and `Validators::Validate` inline-callable handlers for `:coerce` / `:validate` hash entries; generic callables receive `(value, task)`, Symbol and Proc handlers still resolve against the task
+- Add `Configuration#backtrace_cleaner` and `Configuration#telemetry`
+- Add `Configuration#log_exclusions` (defaults to `[]`) and matching `Settings#log_exclusions` override — an array of `Result#to_h` keys to strip from the lifecycle log entry (e.g. `[:context, :metadata]`). When empty, `Runtime` logs the `Result` as before; otherwise it logs `result.to_h.except(*exclusions)`. Other consumers (telemetry, return values) see the full result
+- Add `Configuration#strict_context` (defaults to `false`) and matching `Settings#strict_context` override, toggling `Context#strict`; when enabled, unknown dynamic reads (`ctx.missing`) raise `NoMethodError` instead of returning `nil` — `[]`, `fetch`, `dig`, `key?`, and `?` predicates stay lenient
+- Add `CMDx.reset_configuration!` which clears global registry ivars on `Task` for clean test setup/teardown; subclasses that already cloned their registries are unaffected
+- Add `:if` / `:unless` gates to `Callbacks#register` (Symbol, Proc, or any `#call`-able); per-event DSL helpers (`before_execution`, `on_success`, etc.) forward the options through
+- Add `:if` / `:unless` gates to `Middlewares#register` (Symbol, Proc, or any `#call`-able); evaluated per task in `Middlewares#process` — skipped middlewares are bypassed and the chain continues
+- Add `:if` / `:unless` gates to `Retry` / `Task.retry_on`; gate receives `(task, error, attempt)` and, when falsy, re-raises the exception instead of retrying (no further wait). Adds `Retry#condition_if` / `Retry#condition_unless` readers
+- Add `Context#deconstruct` / `Context#deconstruct_keys` for pattern matching
+- Add `Errors#deconstruct` / `Errors#deconstruct_keys` for pattern matching
+- Add `:executor` option to parallel task groups (`Workflow.tasks ..., strategy: :parallel, executor: :threads | :fibers | #call`); `:threads` is the default and preserves current behavior, `:fibers` dispatches via `Fiber.schedule` bounded by `:pool_size` (requires a `Fiber.scheduler` such as the `async` gem's — raises `RuntimeError` when none is installed), and a user-supplied callable matching `call(jobs:, concurrency:, on_job:)` is accepted. Unknown symbols raise `ArgumentError`
+- Add `:merger` option to parallel task groups controlling how successful sibling contexts fold back into the workflow context: `:last_write_wins` (default, matches previous behavior), `:deep_merge` (recursive over `Hash` values), `:no_merge` (workflow context left untouched), or a callable `call(workflow_context, result)`. Merging always walks successful results in declaration order. Unknown symbols raise `ArgumentError`
+- Add `CMDx::Executors` registry (built-ins: `:threads` → `Executors::Thread`, `:fibers` → `Executors::Fiber`) and `CMDx::Mergers` registry (built-ins: `:last_write_wins`, `:deep_merge`, `:no_merge`) exposed on `Configuration#executors` / `#mergers` and per-task via `Task.executors` / `Task.mergers` (dup-on-inherit); `Task.register(:executor, ...)` and `Task.register(:merger, ...)` (plus matching `deregister`) let apps plug in custom dispatch/merge strategies resolvable by name from `:executor` / `:merger`
+- Add `Context#deep_merge` — in-place recursive `Hash`-value merge; scalar-vs-hash collisions follow last-write-wins. Used by the `:deep_merge` parallel merge strategy but also available directly
+- Add `:linear`, `:fibonacci`, and `:decorrelated_jitter` built-in retry jitter strategies on `Retry` / `Task.retry_on`. `:linear` sleeps `delay * (attempt + 1)`; `:fibonacci` sleeps `delay * fib(attempt + 1)`; `:decorrelated_jitter` is the AWS-recommended stateful strategy `next ∈ [delay, prev_sleep * 3]` (threaded across attempts inside a single `process` call, falls back to `delay` when no prior sleep). `Retry#wait` now accepts an optional `prev_delay` argument and returns the computed delay so callers can thread state
+- Add `CMDx::Retriers` registry (built-ins: `:exponential`, `:half_random`, `:full_random`, `:bounded_random`, `:linear`, `:fibonacci`, `:decorrelated_jitter`) exposed on `Configuration#retriers` and per-task via `Task.retriers` (dup-on-inherit). `Task.register(:retrier, ...)` / `deregister(:retrier, ...)` let apps plug in custom jitter strategies resolvable by name from `:jitter`. Strategies are pure callables matching `call(attempt, delay, prev_delay)`. Symbols not present in the registry still fall through to task instance methods, preserving existing `jitter: :method_name` semantics
+- Add `CMDx::Deprecators` registry (built-ins: `:log`, `:warn`, `:error`) exposed on `Configuration#deprecators` and per-task via `Task.deprecators` (dup-on-inherit). `Task.register(:deprecator, ...)` / `deregister(:deprecator, ...)` let apps plug in custom deprecation actions resolvable by name from `Task.deprecation`. Actions are callables matching `call(task)`. Symbols not present in the registry still fall through to task instance methods, preserving existing `deprecation :method_name` semantics. The built-in `:log`, `:warn`, `:error` arms are now strategy modules under `lib/cmdx/deprecators/` instead of inline branches in `Deprecation#execute`
+
+### Changed
+- **BREAKING**: Rename `#call` → `#work` on task subclasses; `Task.execute` / `Task.execute!` are the new entry points (`call` / `call!` kept as aliases)
+- **BREAKING**: `Result` is now frozen and read-only; all state lives in the embedded `Signal`, built once during `Runtime#finalize_result`
+- **BREAKING**: Move `STATES` / `STATUSES` constants and the `initialized` / `executing` / `executed!` transitions from `Result` to `Signal::STATES` / `Signal::STATUSES` (only `complete` / `interrupted` and `success` / `skipped` / `failed` remain)
+- **BREAKING**: Halt mechanism uses `catch(Signal::TAG)` + `throw` instead of mutating result state; `success!` / `skip!` / `fail!` / `throw!` are now private `Task` instance methods (no longer delegated through `Result`) and raise `FrozenError` when called after teardown
+- **BREAKING**: `Chain` is now fiber-local (was thread-local), keyed on `Fiber[:cmdx_chain]`, with internal `Mutex` on `push` / `unshift`; root Runtime clears the chain on teardown
+- **BREAKING**: `Result#chain` now returns the owning `Chain` object directly instead of its results array (use `result.chain.to_a` / `result.chain.results`, or iterate via `Chain`'s new Enumerable methods)
+- **BREAKING**: Drive `Result#caused_failure` / `threw_failure` / `caused_failure?` / `thrown_failure?` off `Signal#origin` instead of `signal.cause`; `caused_failure` walks `origin` recursively to the originating leaf, `threw_failure` returns `origin || self`, `caused_failure?` is true when the result originated the failure chain, `thrown_failure?` is true when the result re-threw an upstream failure
+- 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`
+- `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
+- `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`
+- `Fault#initialize` takes a single `Result`; `task`, `context`, and `chain` delegate to it; `Runtime` raises `Fault.new(@result.caused_failure)` so `fault.task` always points at the originating leaf (including in workflows and nested `execute!` chains)
+- `Runtime` finalizes the `Result` before `raise_signal!` so the `Fault` it raises always carries a fully-built `Result`
+- `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
+- 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`
+- `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
+- **BREAKING**: Remove `Result::STATES = [INITIALIZED, EXECUTING, COMPLETE, INTERRUPTED]`, the `executed!` / `executing!` transitions, and the `executed?` / `initialized?` / `executing?` predicates
+- **BREAKING**: Remove `Task#id`, `Task#result`, `Task#chain` direct accessors — read these off the `Result` returned by `execute`
+- **BREAKING**: Remove `Result#threw_failure?` predicate (`result.thrown_failure?` remains, with semantics flipped — true when the result re-threw an upstream failure)
+- **BREAKING**: Remove `Result#chain_id` — read it off the chain: `result.cid`
+- **BREAKING**: `Result#to_h` no longer produces nested `caused_failure` / `threw_failure` hashes; failure references render as `{ task:, tid: }` and `to_s` formats them as `<TaskClass uuid>`
+- Remove `CMDx::Executor` (replaced by `CMDx::Runtime`)
+- Remove `CMDx::Attribute`, `CMDx::AttributeRegistry`, `CMDx::AttributeValue` (replaced by `Input` / `Inputs` and `Output` / `Outputs`)
+- Remove `CMDx::Resolver` (value resolution is owned by `Input#resolve`)
+- Remove `CMDx::Identifier` (Runtime / Chain use `SecureRandom.uuid_v7` directly)
+- Remove `CMDx::Locale` (superseded by `I18nProxy`)
+- Remove `CMDx::Deprecator` (superseded by `Deprecation` declared per task class)
+- Remove `CMDx::Parallelizer` (parallelism now lives in `Pipeline#run_parallel`)
+- Remove `CMDx::CallbackRegistry`, `CMDx::MiddlewareRegistry`, `CMDx::CoercionRegistry`, `CMDx::ValidatorRegistry` (replaced by the simpler `Callbacks`, `Middlewares`, `Coercions`, `Validators` plain classes)
+- Remove `CMDx::Utils::Call`, `CMDx::Utils::Condition`, `CMDx::Utils::Format`, `CMDx::Utils::Normalize`, `CMDx::Utils::Wrap` (collapsed into `CMDx::Util`)
+- Remove built-in `CMDx::Middlewares::Correlate`, `CMDx::Middlewares::Runtime`, `CMDx::Middlewares::Timeout` — register equivalents on `config.middlewares` if needed
+- Remove `CMDx::Exception` file — `CMDx::Error` / `Exception` and friends are now defined in `lib/cmdx.rb`
+- Remove Zeitwerk autoloading (replaced by explicit `require_relative` ordering in `lib/cmdx.rb`); drop `forwardable`, `pathname`, `timeout`, and `zeitwerk` requires
+- Remove `CMDx.gem_path` top-level helper
+- Remove `Configuration#task_breakpoints`, `Configuration#workflow_breakpoints`, `Configuration#freeze_results`, `Configuration#exception_handler`, and the `SKIP_CMDX_FREEZING` env var — failure halting is now intrinsic to Runtime via `Signal` and `execute!` strict mode
+- Remove `Chain#dry_run?` and the `dry_run:` context flag
+
+### Migration notes
+
+See [docs/v2-migration.md](docs/v2-migration.md) for the full upgrade guide. At minimum:
+
+- Rename `def call` → `def work`; `MyTask.call(ctx)` still works (aliased) but prefer `MyTask.execute(ctx)`
+- Replace `register :attribute, ...` with `required :name, ...` / `optional :name, ...` / `output :name, ...`
+- Replace `result.chain_id` with `result.cid`
+- Replace `task.id` / `task.result` / `task.chain` with reads off the `Result` returned by `execute`
+- Subscribe to lifecycle observability via `config.telemetry.subscribe(:task_executed) { |event| ... }` instead of the removed `Runtime` / `Correlate` middlewares
 
 ## [1.21.0] - 2026-04-09
 

data/README.md

@@ -14,7 +14,7 @@
   [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) ·
+  [llms-full.txt](https://drexed.github.io/cmdx/llms-full.txt)
 
   <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">
@@ -26,14 +26,26 @@
 Say goodbye to messy service objects. CMDx helps you design business logic with clarity and consistency—build faster, debug easier, and ship with confidence.
 
 > [!NOTE]
-> [Documentation](https://drexed.github.io/cmdx/getting_started/) reflects the latest code on `main`. For version-specific documentation, please refer to the `docs/` directory within that version's tag.
+> [Documentation](https://drexed.github.io/cmdx/getting_started/) reflects the latest code on `main`. For version-specific documentation, refer to the `docs/` directory within that version's tag.
+
+## What you get
+
+- **Standardized task contract** — typed inputs, declared outputs, explicit halts
+- **Type system** — 13 coercers, 7 validators, all pluggable
+- **Built-in flow control** — `skip!` / `fail!` / `throw!` with structured metadata
+- **Retries and faults** — declarative `retry_on` with configurable jitter
+- **Middleware and callbacks** — wrap the lifecycle without touching `work`
+- **Observability** — structured logs and telemetry, no extra instrumentation
+- **Composable workflows** — chain tasks into larger processes
+
+See the [feature comparison](https://drexed.github.io/cmdx/comparison/) for how CMDx stacks up against other service-object gems.
 
 ## Requirements
 
-- Ruby: MRI 3.1+ or JRuby 9.4+
-- Dependencies: None
+- Ruby: MRI 3.3+ or a compatible JRuby/TruffleRuby release
+- Runtime dependencies: `bigdecimal` and `logger` (stdlib only — no ActiveSupport required)
 
-Rails support is built-in, but it's framework-agnostic at its core.
+Rails support is built-in, but CMDx is framework-agnostic at its core.
 
 ## Installation
 
@@ -45,24 +57,23 @@ bundle add cmdx
 
 ## Quick Example
 
-Build powerful business logic in four simple steps:
+CMDx organizes business logic around the **CERO** pattern (pronounced "zero"): **Compose**, **Execute**, **React**, **Observe**.
 
 ### 1. Compose
 
-```ruby
-# Full-featured task example
-# See docs for minimum viable task examples
+Declare inputs, outputs, retries, and callbacks, then implement `work`.
 
+```ruby
 class AnalyzeMetrics < CMDx::Task
-  register :middleware, CMDx::Middlewares::Correlate, id: -> { Current.request_id }
+  retry_on Net::ReadTimeout, limit: 3, jitter: :exponential
 
   on_success :track_analysis_completion!
 
-  required :dataset_id, type: :integer, numeric: { min: 1 }
+  required :dataset_id, coerce: :integer, numeric: { min: 1 }
 
   optional :analysis_type, default: "standard"
 
-  returns :result, :analyzed_at
+  output :result, :analyzed_at
 
   def work
     if dataset.nil?
@@ -91,6 +102,8 @@ end
 
 ### 2. Execute
 
+Every invocation returns a `Result`. Inputs are coerced and validated, exceptions are captured, outputs are verified, and the outcome is logged — automatically.
+
 ```ruby
 result = AnalyzeMetrics.execute(
   dataset_id: 123,
@@ -98,39 +111,39 @@ result = AnalyzeMetrics.execute(
 )
 ```
 
+Use `execute!` instead when you want failures to raise a `Fault`.
+
 ### 3. React
 
+Branch on the result's status and read values, reasons, or metadata from it.
+
 ```ruby
 if result.success?
   puts "Metrics analyzed at #{result.context.analyzed_at}"
 elsif result.skipped?
-  puts "Skipping analyzation due to: #{result.reason}"
+  puts "Skipped: #{result.reason}"
 elsif result.failed?
-  puts "Analyzation failed due to: #{result.reason} with code #{result.metadata[:code]}"
+  puts "Failed: #{result.reason} (code #{result.metadata[:code]})"
 end
 ```
 
 ### 4. Observe
 
+Every execution emits a structured log line with the chain id, task identity, state, status, reason, metadata, and duration — enough to correlate nested tasks and reconstruct what happened.
+
 ```log
-I, [2022-07-17T18:42:37.000000 #3784] INFO -- CMDx:
-index=1 chain_id="018c2b95-23j4-2kj3-32kj-3n4jk3n4jknf" type="Task" class="SendAnalyzedEmail" state="complete" status="success" metadata={runtime: 347}
+I, [2026-04-19T18:42:37.000000Z #3784] INFO -- cmdx: cid="018c2b95-b764-7fff-a1d2-..." index=1 root=false type="Task" task=SendAnalyzedEmail id="018c2b95-c091-..." state="complete" status="success" reason=nil metadata={} duration=34.7 tags=[]
 
-I, [2022-07-17T18:43:15.000000 #3784] INFO -- CMDx:
-index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="AnalyzeMetrics" state="complete" status="success" metadata={runtime: 187}
+I, [2026-04-19T18:43:15.000000Z #3784] INFO -- cmdx: cid="018c2b95-b764-7fff-a1d2-..." index=0 root=true type="Task" task=AnalyzeMetrics id="018c2b95-b764-..." state="complete" status="success" reason=nil metadata={} duration=187.4 tags=[]
 ```
 
-Ready to dive in? Check out the [Getting Started](https://drexed.github.io/cmdx/getting_started/) guide to learn more.
+Ready to dive in? Check out the [Getting Started](https://drexed.github.io/cmdx/getting_started/) guide.
 
 ## Ecosystem
 
+- [cmdx-i18n](https://github.com/drexed/cmdx-i18n) - 85+ translations
 - [cmdx-rspec](https://github.com/drexed/cmdx-rspec) - RSpec test matchers
 
-For backwards compatibility of certain functionality:
-
-- [cmdx-i18n](https://github.com/drexed/cmdx-i18n) - 85+ translations, `v1.5.0` - `v1.6.2`
-- [cmdx-parallel](https://github.com/drexed/cmdx-parallel) - Parallel workflow tasks, `v1.6.1` - `v1.6.2`
-
 ## Contributing
 
 Bug reports and pull requests are welcome at <https://github.com/drexed/cmdx>. We're committed to fostering a welcoming, collaborative community. Please follow our [code of conduct](CODE_OF_CONDUCT.md).

data/lib/cmdx/callbacks.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Registry of lifecycle callbacks invoked by Runtime. Callbacks can be
+  # method names (Symbols dispatched via `task.send`), blocks/Procs
+  # (`instance_exec`'d on the task), or arbitrary `#call` objects.
+  #
+  # Each registration may carry `:if` / `:unless` gates (Symbol, Proc, or
+  # any `#call`-able). Gates are evaluated against the task before the
+  # callback is invoked; non-passing gates skip the callback silently.
+  class Callbacks
+
+    # Callback event names Runtime dispatches.
+    EVENTS = Set[
+      :before_validation,
+      :before_execution,
+      :around_execution,
+      :after_execution,
+      :on_complete,
+      :on_interrupted,
+      :on_success,
+      :on_skipped,
+      :on_failed,
+      :on_ok,
+      :on_ko
+    ].freeze
+
+    attr_reader :registry
+
+    def initialize
+      @registry = {}
+    end
+
+    # @param source [Callbacks] registry to duplicate
+    # @return [void]
+    def initialize_copy(source)
+      @registry = source.registry.transform_values(&:dup)
+    end
+
+    # Adds a callback for `event`.
+    #
+    # @param event [Symbol] one of {EVENTS}
+    # @param callable [Symbol, #call, nil] method name or callable; pass either this or a block
+    # @param block [#call, nil] callback body when `callable` is omitted
+    # @param options [Hash{Symbol => Object}]
+    # @option options [Symbol, Proc, #call] :if   gate that must evaluate truthy
+    # @option options [Symbol, Proc, #call] :unless gate that must evaluate falsy
+    # @return [Callbacks] self for chaining
+    # @raise [ArgumentError] when both `callable` and a block are given, when the
+    #   callback type is invalid, or when `event` is unknown
+    # @yield the callback body
+    def register(event, callable = nil, **options, &block)
+      callback = callable || block
+
+      if callable && block
+        raise ArgumentError, "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"
+      elsif !EVENTS.include?(event)
+        raise ArgumentError, "unknown event #{event.inspect}, must be one of #{EVENTS.join(', ')}"
+      end
+
+      (registry[event] ||= []) << [callback, options.freeze]
+      self
+    end
+
+    # Drops callbacks registered for `event`. With no `callable`, removes
+    # every callback for `event`. With a `callable`, removes only the
+    # entries whose callback matches `callable` by `==` (works for Symbol
+    # method names, classes/modules, and any callable held by reference).
+    # When the last entry for `event` is removed, the key itself is dropped.
+    #
+    # @param event [Symbol] one of {EVENTS}
+    # @param callable [Symbol, #call, nil] optional specific callback to remove
+    # @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)
+
+      if callable.nil?
+        registry.delete(event)
+      elsif (entries = registry[event])
+        entries.reject! { |cb, _opts| cb == callable }
+        registry.delete(event) if entries.empty?
+      end
+
+      self
+    end
+
+    # @return [Boolean]
+    def empty?
+      registry.empty?
+    end
+
+    # @return [Integer] number of distinct events with callbacks
+    def size
+      registry.size
+    end
+
+    # @return [Integer] total callbacks across all events
+    def count
+      registry.each_value.sum(&:size)
+    end
+
+    # Fires each callback registered for `event` against `task`. Skips any
+    # callback whose `:if`/`:unless` gates fail.
+    #
+    # @param event [Symbol]
+    # @param task [Task]
+    # @return [void]
+    # @raise [ArgumentError] when a callback is neither a Symbol nor responds to `#call`
+    def process(event, task)
+      callbacks = registry[event]
+      return if callbacks.nil? || callbacks.empty?
+
+      callbacks.each do |callable, options|
+        next unless Util.satisfied?(options[:if], options[:unless], task)
+
+        invoke(callable, task)
+      end
+    end
+
+    # Wraps `block` with every callback registered for `event` as a nested
+    # chain (outer-first by declaration order). Each callback receives a
+    # continuation it must invoke exactly once: Symbol callbacks get it as
+    # their block (use `yield`); Procs/blocks are `instance_exec`'d on the
+    # task with `(task, continuation)`; arbitrary callables receive
+    # `(task, continuation)`. Gates skip individual links silently while
+    # still running the body.
+    #
+    # @param event [Symbol]
+    # @param task [Task]
+    # @param body [#call] inner continuation (Runtime lifecycle body)
+    # @yield the innermost link — the lifecycle body to wrap
+    # @return [void]
+    # @raise [CallbackError] when a callback fails to invoke its continuation
+    def around(event, task, &body)
+      callbacks = registry[event]
+      return yield if callbacks.nil? || callbacks.empty?
+
+      callbacks.reverse_each.reduce(body) do |succ, (callable, options)|
+        lambda do
+          next succ.call unless Util.satisfied?(options[:if], options[:unless], task)
+
+          called = false
+          cont = lambda do
+            called = true
+            succ.call
+          end
+
+          invoke(callable, task, cont, &cont)
+
+          called || raise(CallbackError, "#{event} callback did not invoke its continuation")
+        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
+        task.send(callable, &)
+      when Proc
+        task.instance_exec(task, *extras, &callable)
+      else
+        return callable.call(task, *extras) if callable.respond_to?(:call)
+
+        raise ArgumentError, "callback must be a Symbol, Proc, or respond to #call"
+      end
+    end
+
+  end
+end