cmdx 1.0.1 → 1.1.1

data/lib/cmdx/task.rb

@@ -1,157 +1,43 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # Task is the base class for all command objects in CMDx, providing a framework
-  # for encapsulating business logic with parameter validation, callbacks, and result tracking.
+  # Core task implementation providing executable units of work with parameter management.
   #
-  # Tasks follow a single-use pattern where each instance can only be executed once,
-  # after which it becomes frozen and immutable. This ensures predictable execution
-  # and prevents side effects from multiple calls.
-  #
-  # @example Basic task definition
-  #   class ProcessOrderTask < CMDx::Task
-  #     required :order_id, type: :integer
-  #     optional :notify_user, type: :boolean, default: true
-  #
-  #     def call
-  #       # Business logic here
-  #       context.order = Order.find(order_id)
-  #       skip!(reason: "Order already processed") if context.order.processed?
-  #
-  #       context.order.process!
-  #       NotificationService.call(order_id: order_id) if notify_user
-  #     end
-  #   end
-  #
-  # @example Task execution
-  #   result = ProcessOrderTask.call(order_id: 123, notify_user: false)
-  #   result.success? #=> true
-  #   result.context.order #=> <Order id: 123>
-  #
-  # @example Task chaining with Result objects
-  #   # First task extracts data
-  #   class ExtractDataTask < CMDx::Task
-  #     required :source_id, type: :integer
-  #
-  #     def call
-  #       context.extracted_data = DataSource.extract(source_id)
-  #       context.extraction_time = Time.now
-  #     end
-  #   end
-  #
-  #   # Second task processes the extracted data
-  #   class ProcessDataTask < CMDx::Task
-  #     def call
-  #       # Access data from previous task's context
-  #       fail!(reason: "No data to process") unless context.extracted_data
-  #
-  #       context.processed_data = DataProcessor.process(context.extracted_data)
-  #       context.processing_time = Time.now
-  #     end
-  #   end
-  #
-  #   # Chain tasks by passing Result objects
-  #   extraction_result = ExtractDataTask.call(source_id: 123)
-  #   processing_result = ProcessDataTask.call(extraction_result)
-  #
-  #   # Result object context is automatically extracted
-  #   processing_result.context.extracted_data #=> data from first task
-  #   processing_result.context.processed_data #=> data from second task
-  #
-  # @example Using callbacks
-  #   class ProcessOrderTask < CMDx::Task
-  #     before_validation :log_start
-  #     after_execution :cleanup_resources
-  #     on_success :send_confirmation
-  #     on_failure :alert_support, if: :critical_order?
-  #
-  #     def call
-  #       # Implementation
-  #     end
-  #
-  #     private
-  #
-  #     def critical_order?
-  #       context.order.value > 10_000
-  #     end
-  #   end
-  #
-  # == Task Chaining and Data Flow
-  #
-  # Tasks can be seamlessly chained by passing Result objects between them.
-  # This enables powerful workflows where the output of one task becomes the
-  # input for the next, maintaining data consistency and enabling complex
-  # business logic composition.
-  #
-  # Benefits of Result object chaining:
-  # - Automatic context extraction and data flow
-  # - Preserves all context data including custom attributes
-  # - Maintains execution chain relationships
-  # - Enables conditional task execution based on previous results
-  # - Simplifies error handling and rollback scenarios
-  #
-  # @see Result Result object for execution outcomes
-  # @see Context Context object for parameter access
-  # @see ParameterRegistry Parameter definition and validation
-  # @see Workflow Workflow for executing multiple tasks
-  # @since 1.0.0
+  # Task is the fundamental building block of the CMDx framework, providing a structured
+  # approach to implementing business logic with built-in parameter validation, middleware
+  # support, callback handling, and comprehensive result tracking. Tasks encapsulate
+  # discrete units of work that can be chained together into workflows or executed
+  # independently with rich execution context and error handling.
   class Task
 
-    ##
-    # Available callback types for task lifecycle events.
-    # Callbacks are executed in a specific order during task execution.
-    #
-    # @return [Array<Symbol>] frozen array of available callback names
-    CALLBACKS = [
-      :before_validation,
-      :after_validation,
-      :before_execution,
-      :after_execution,
-      :on_executed,
-      :on_good,
-      :on_bad,
-      *Result::STATUSES.map { |s| :"on_#{s}" },
-      *Result::STATES.map { |s| :"on_#{s}" }
-    ].freeze
-
-    __cmdx_attr_setting :task_settings,
-                        default: -> { CMDx.configuration.to_h.merge(tags: []) }
-    __cmdx_attr_setting :cmd_middlewares,
-                        default: -> { MiddlewareRegistry.new(CMDx.configuration.middlewares) }
-    __cmdx_attr_setting :cmd_callbacks,
-                        default: -> { CallbackRegistry.new(CMDx.configuration.callbacks) }
-    __cmdx_attr_setting :cmd_parameters,
-                        default: -> { ParameterRegistry.new }
-
-    __cmdx_attr_delegator :cmd_middlewares, :cmd_callbacks, :cmd_parameters, :task_setting, :task_setting?,
-                          to: :class
-    __cmdx_attr_delegator :skip!, :fail!, :throw!,
-                          to: :result
-
-    ##
-    # @!attribute [r] context
-    #   @return [Context] parameter context for this task execution
+    cmdx_attr_setting :cmd_settings,
+                      default: -> { CMDx.configuration.to_h.slice(:logger, :task_halt, :workflow_halt).merge(tags: []) }
+    cmdx_attr_setting :cmd_middlewares,
+                      default: -> { MiddlewareRegistry.new(CMDx.configuration.middlewares) }
+    cmdx_attr_setting :cmd_callbacks,
+                      default: -> { CallbackRegistry.new(CMDx.configuration.callbacks) }
+    cmdx_attr_setting :cmd_parameters,
+                      default: -> { ParameterRegistry.new }
+
+    cmdx_attr_delegator :cmd_middlewares, :cmd_callbacks, :cmd_parameters,
+                        :cmd_settings, :cmd_setting, :cmd_setting?,
+                        to: :class
+    cmdx_attr_delegator :skip!, :fail!, :throw!,
+                        to: :result
+
+    # @return [Context] parameter context for this task execution
     attr_reader :context
 
-    ##
-    # @!attribute [r] errors
-    #   @return [Errors] collection of validation and execution errors
+    # @return [Errors] collection of validation and execution errors
     attr_reader :errors
 
-    ##
-    # @!attribute [r] id
-    #   @return [String] unique identifier for this task instance
+    # @return [String] unique identifier for this task instance
     attr_reader :id
 
-    ##
-    # @!attribute [r] result
-    #   @return [Result] execution result tracking state and status
+    # @return [Result] execution result tracking state and status
     attr_reader :result
 
-    ##
-    # @!attribute [r] chain
-    #   @return [Chain] execution chain containing this task and related executions
+    # @return [Chain] execution chain containing this task and related executions
     attr_reader :chain
 
     # @return [Context] alias for context
@@ -160,21 +46,28 @@ module CMDx
     # @return [Result] alias for result
     alias res result
 
-    ##
-    # Initializes a new task instance with the given context parameters.
+    # Creates a new task instance with the given execution context.
+    #
+    # Initializes all internal state including context, errors, unique identifier,
+    # result tracking, and execution chain. The context parameter supports various
+    # input formats and will be normalized into a Context instance.
+    #
+    # @param context [Hash, Context, Object] initial execution context and parameters
     #
-    # The context can be provided as a Hash, Context object, or Result object.
-    # When a Result object is passed, its context is automatically extracted,
-    # enabling seamless task chaining and data flow between tasks.
+    # @return [Task] the newly created task instance
     #
-    # @param context [Hash, Context, Result] parameters and configuration for task execution
-    # @example With hash parameters
-    #   task = ProcessOrderTask.new(order_id: 123, notify_user: true)
+    # @example Create task with hash context
+    #   task = MyTask.new(user_id: 123, action: "process")
+    #   task.context.user_id #=> 123
     #
-    # @example With Result object (task chaining)
-    #   extraction_result = ExtractDataTask.call(source_id: 456)
-    #   processing_task = ProcessDataTask.new(extraction_result)
-    #   # Context from extraction_result is automatically extracted
+    # @example Create task with existing context
+    #   existing_context = OtherTask.call(status: "active")
+    #   task = MyTask.new(existing_context)
+    #   task.context.status #=> "active"
+    #
+    # @example Create task with empty context
+    #   task = MyTask.new
+    #   task.context #=> empty Context instance
     def initialize(context = {})
       context  = context.context if context.respond_to?(:context)
 
@@ -183,347 +76,363 @@ module CMDx
       @id      = CMDx::Correlator.generate
       @result  = Result.new(self)
       @chain   = Chain.build(@result)
+
+      TaskDeprecator.call(self)
     end
 
     class << self
 
-      ##
-      # Dynamically defines callback methods for each available callback type.
-      # Each callback method accepts callables and options for conditional execution.
-      #
-      # @example Callback with method name
-      #   before_validation :validate_permissions
-      #
-      # @example Callback with proc
-      #   on_success -> { logger.info "Task completed successfully" }
-      #
-      # @example Callback with conditions
-      #   on_failure :alert_support, if: :critical_error?
-      #   after_execution :cleanup, unless: :skip_cleanup?
-      #
-      # @param callables [Array<Symbol, Proc, #call>] methods or callables to execute
-      # @param options [Hash] conditions for callback execution
-      # @option options [Symbol, Proc, #call] :if condition that must be truthy
-      # @option options [Symbol, Proc, #call] :unless condition that must be falsy
-      # @param block [Proc] block to execute as part of the callback
-      # @return [Array] updated callbacks array
-      CALLBACKS.each do |callback|
+      CallbackRegistry::TYPES.each do |callback|
+        # Registers a callback for the specified lifecycle event.
+        #
+        # This method is dynamically defined for each callback type supported by
+        # CallbackRegistry, allowing tasks to register callbacks for various
+        # execution lifecycle events.
+        #
+        # @param callables [Array<Object>] callback objects or procs to register
+        # @param options [Hash] options for callback registration
+        # @param block [Proc] optional block to use as callback
+        #
+        # @return [void]
+        #
+        # @example Register before_execution callback with symbol
+        #   class MyTask < CMDx::Task
+        #     before_execution :setup_database
+        #   end
+        #
+        # @example Register before_execution callback with proc
+        #   class MyTask < CMDx::Task
+        #     before_execution -> { puts "Starting task execution" }
+        #   end
+        #
+        # @example Register before_execution callback with class
+        #   class MyTask < CMDx::Task
+        #     before_execution SetupCallback
+        #   end
+        #
+        # @example Register before_execution callback with block
+        #   class MyTask < CMDx::Task
+        #     before_execution { |task| task.context.started_at = Time.now }
+        #   end
+        #
+        # @example Register on_success callback with conditional options
+        #   class MyTask < CMDx::Task
+        #     on_success :send_notification, if: -> { Rails.env.production? }
+        #   end
+        #
+        # @example Register on_success callback with multiple callables
+        #   class MyTask < CMDx::Task
+        #     on_success :log_success, :send_email, :update_metrics
+        #   end
         define_method(callback) do |*callables, **options, &block|
           cmd_callbacks.register(callback, *callables, **options, &block)
         end
       end
 
-      ##
-      # Retrieves a task setting value, evaluating it if it's a callable.
-      #
-      # @param key [Symbol, String] setting key to retrieve
-      # @return [Object] the setting value
-      # @example
-      #   task_setting(:timeout) #=> 30
-      def task_setting(key)
-        __cmdx_yield(task_settings[key])
-      end
-
-      ##
-      # Checks if a task setting exists.
+      # Retrieves a configuration setting value by key.
+      #
+      # Provides access to task-specific configuration settings that control
+      # various aspects of task execution including logging, halt conditions,
+      # and custom settings.
+      #
+      # @param key [Symbol, String] the configuration setting key to retrieve
+      #
+      # @return [Object] the configuration value, or nil if key doesn't exist
       #
-      # @param key [Symbol, String] setting key to check
-      # @return [Boolean] true if setting exists
-      def task_setting?(key)
-        task_settings.key?(key)
+      # @example Get logger setting
+      #   MyTask.cmd_setting(:logger) #=> Logger instance
+      #
+      # @example Get custom setting
+      #   MyTask.cmd_settings!(timeout: 30)
+      #   MyTask.cmd_setting(:timeout) #=> 30
+      def cmd_setting(key)
+        cmdx_yield(cmd_settings[key])
       end
 
-      ##
-      # Updates task settings with new options.
-      #
-      # @param options [Hash] settings to merge
-      # @return [Hash] updated settings
-      # @example
-      #   task_settings!(timeout: 60, retries: 3)
-      def task_settings!(**options)
-        task_settings.merge!(options)
+      # Checks if a configuration setting exists.
+      #
+      # @param key [Symbol, String] the configuration setting key to check
+      #
+      # @return [Boolean] true if the setting key exists, false otherwise
+      #
+      # @example Check for existing setting
+      #   MyTask.cmd_setting?(:logger) #=> true
+      #
+      # @example Check for non-existing setting
+      #   MyTask.cmd_setting?(:nonexistent) #=> false
+      def cmd_setting?(key)
+        cmd_settings.key?(key)
       end
 
-      ##
-      # Adds middleware to the task execution stack.
-      #
-      # Middleware can wrap task execution to provide cross-cutting concerns
-      # like logging, authentication, caching, or error handling.
-      #
-      # @param middleware [Class, Object, Proc] middleware to add
-      # @param args [Array] arguments for middleware instantiation
-      # @param block [Proc] block for middleware instantiation
-      # @return [MiddlewareRegistry] updated middleware registry
-      # @example
-      #   use LoggingMiddleware
-      #   use AuthenticationMiddleware, "admin"
-      #   use CachingMiddleware.new(ttl: 300)
-      def use(middleware, ...)
-        cmd_middlewares.use(middleware, ...)
+      # Updates task configuration settings with the provided options.
+      #
+      # Merges the given options into the existing configuration settings,
+      # allowing tasks to customize their execution behavior.
+      #
+      # @param options [Hash] configuration options to merge
+      #
+      # @return [Hash] the updated settings hash
+      #
+      # @example Set custom timeout
+      #   MyTask.cmd_settings!(timeout: 60, retries: 3)
+      #
+      # @example Override halt condition
+      #   MyTask.cmd_settings!(task_halt: ["failed", "error"])
+      def cmd_settings!(**options)
+        cmd_settings.merge!(options)
       end
 
-      ##
-      # Registers callbacks for the task execution lifecycle.
-      #
-      # Callbacks can observe or modify task execution at specific lifecycle
-      # points like before validation, on success, after execution, etc.
-      #
-      # @param callback [Symbol] The callback type to register for
-      # @param callables [Array<Symbol, Proc, Callback, #call>] Methods, callables, or Callback instances to execute
-      # @param options [Hash] Conditions for callback execution
-      # @option options [Symbol, Proc, #call] :if condition that must be truthy
-      # @option options [Symbol, Proc, #call] :unless condition that must be falsy
-      # @param block [Proc] Block to execute as part of the callback
-      # @return [CallbackRegistry] updated callback registry
-      # @example
-      #   register :before_execution, LoggingCallback.new(:debug)
-      #   register :on_success, NotificationCallback.new([:email, :slack])
-      #   register :on_failure, :alert_admin, if: :critical?
-      def register(callback, ...)
-        cmd_callbacks.register(callback, ...)
+      # Registers middleware, callbacks, validators, or coercions with the task.
+      #
+      # Provides a unified interface for registering various types of task
+      # extensions that modify or enhance task execution behavior.
+      #
+      # @param type [Symbol] the type of extension to register (:middleware, :callback, :validator, :coercion)
+      # @param object [Object] the extension object to register
+      # @param args [Array] additional arguments for registration
+      #
+      # @return [void]
+      #
+      # @raise [ArgumentError] if an unsupported type is provided
+      #
+      # @example Register coercion
+      #   class MyTask < CMDx::Task
+      #     use :coercion, TemperatureCoercion
+      #   end
+      #
+      # @example Register validator
+      #   class MyTask < CMDx::Task
+      #     use :validator, ZipcodeValidator, country: "US"
+      #   end
+      #
+      # @example Register middleware
+      #   class MyTask < CMDx::Task
+      #     use :middleware, CMDx::Middlewares::Timeout.new(seconds: 30)
+      #   end
+      #
+      # @example Register callback
+      #   class MyTask < CMDx::Task
+      #     use :callback, :before, LogCallback.new
+      #   end
+      def use(type, object, ...)
+        case type
+        when :middleware
+          cmd_middlewares.register(object, ...)
+        when :callback
+          cmd_callbacks.register(type, object, ...)
+        when :validator
+          cmd_validators.register(type, object, ...)
+        when :coercion
+          cmd_coercions.register(type, object, ...)
+        end
       end
 
-      ##
-      # Defines optional parameters for the task.
-      #
-      # @param attributes [Array<Symbol>] parameter names
-      # @param options [Hash] parameter options (type, default, validations, etc.)
-      # @param block [Proc] block for nested parameter definitions
-      # @return [ParameterRegistry] updated parameters collection
-      # @example
-      #   optional :timeout, type: :integer, default: 30
-      #   optional :options, type: :hash do
-      #     required :api_key, type: :string
+      # Defines optional parameters for the task with validation and coercion.
+      #
+      # Creates parameter definitions that are not required for task execution
+      # but will be validated and coerced if provided. Supports nested parameter
+      # structures through block syntax.
+      #
+      # @param attributes [Array<Symbol>] parameter names to define as optional
+      # @param options [Hash] parameter configuration options
+      # @option options [Symbol, Array<Symbol>] :type parameter type(s) for coercion
+      # @option options [Object] :default default value if parameter not provided
+      # @option options [Hash] :validates validation rules to apply
+      # @param block [Proc] optional block for defining nested parameters
+      #
+      # @return [Array<Parameter>] the created parameter definitions
+      #
+      # @example Define simple optional parameters
+      #   class MyTask < CMDx::Task
+      #     optional :name, :email, type: :string
+      #     optional :age, type: :integer, default: 0
+      #   end
+      #
+      # @example Define optional parameter with validation
+      #   class MyTask < CMDx::Task
+      #     optional :score, type: :integer, validates: { numeric: { greater_than: 0 } }
+      #   end
+      #
+      # @example Define nested optional parameters
+      #   class MyTask < CMDx::Task
+      #     optional :user, type: :hash do
+      #       required :name, type: :string
+      #       optional :age, type: :integer
+      #     end
       #   end
       def optional(*attributes, **options, &)
         parameters = Parameter.optional(*attributes, **options.merge(klass: self), &)
-        cmd_parameters.concat(parameters)
+        cmd_parameters.registry.concat(parameters)
       end
 
-      ##
-      # Defines required parameters for the task.
-      #
-      # @param attributes [Array<Symbol>] parameter names
-      # @param options [Hash] parameter options (type, validations, etc.)
-      # @param block [Proc] block for nested parameter definitions
-      # @return [ParameterRegistry] updated parameters collection
-      # @example
-      #   required :user_id, type: :integer
-      #   required :profile, type: :hash do
-      #     required :name, type: :string
-      #     optional :age, type: :integer
+      # Defines required parameters for the task with validation and coercion.
+      #
+      # Creates parameter definitions that must be provided for successful task
+      # execution. Missing required parameters will cause task validation to fail.
+      # Supports nested parameter structures through block syntax.
+      #
+      # @param attributes [Array<Symbol>] parameter names to define as required
+      # @param options [Hash] parameter configuration options
+      # @option options [Symbol, Array<Symbol>] :type parameter type(s) for coercion
+      # @option options [Object] :default default value if parameter not provided
+      # @option options [Hash] :validates validation rules to apply
+      # @param block [Proc] optional block for defining nested parameters
+      #
+      # @return [Array<Parameter>] the created parameter definitions
+      #
+      # @example Define simple required parameters
+      #   class MyTask < CMDx::Task
+      #     required :user_id, type: :integer
+      #     required :action, type: :string
+      #   end
+      #
+      # @example Define required parameter with validation
+      #   class MyTask < CMDx::Task
+      #     required :email, type: :string, validates: { format: /@/ }
+      #   end
+      #
+      # @example Define nested required parameters
+      #   class MyTask < CMDx::Task
+      #     required :payment, type: :hash do
+      #       required :amount, type: :big_decimal
+      #       required :currency, type: :string
+      #       optional :description, type: :string
+      #     end
       #   end
       def required(*attributes, **options, &)
         parameters = Parameter.required(*attributes, **options.merge(klass: self), &)
-        cmd_parameters.concat(parameters)
+        cmd_parameters.registry.concat(parameters)
       end
 
-      ##
-      # Executes the task with the given parameters, returning a result object.
-      # This method handles all exceptions and ensures the task completes properly.
-      #
-      # Parameters can be provided as a Hash, Context object, or Result object.
-      # When a Result object is passed, its context is automatically extracted,
-      # enabling seamless task chaining.
-      #
-      # @param args [Array] arguments passed to task initialization
-      # @return [Result] execution result with state and status information
-      # @example With hash parameters
-      #   result = ProcessOrderTask.call(order_id: 123)
-      #   result.success? #=> true or false
-      #   result.context.order #=> processed order
-      #
-      # @example With Result object (task chaining)
-      #   extraction_result = ExtractDataTask.call(source_id: 456)
-      #   processing_result = ProcessDataTask.call(extraction_result)
-      #   # Context from extraction_result is automatically used
-      #   processing_result.context.source_id #=> 456
+      # Executes a task instance and returns the result without raising exceptions.
+      #
+      # Creates a new task instance with the provided context, processes it through
+      # the complete execution pipeline, and returns the result. This method will
+      # not raise exceptions for task failures but will capture them in the result.
+      #
+      # @param args [Array] arguments passed to task constructor
+      #
+      # @return [Result] the execution result containing state, status, and metadata
+      #
+      # @example Execute task
+      #   result = MyTask.call(user_id: 123, action: "process")
+      #   puts result.status #=> "success" or "failed" or "skipped"
       def call(...)
         instance = new(...)
-        instance.perform
+        instance.process
         instance.result
       end
 
-      ##
-      # Executes the task with the given parameters, raising exceptions for failures.
-      # This method is useful in background jobs where retries are handled via exceptions.
-      #
-      # Parameters can be provided as a Hash, Context object, or Result object.
-      # When a Result object is passed, its context is automatically extracted,
-      # enabling seamless task chaining with exception propagation.
-      #
-      # @param args [Array] arguments passed to task initialization
-      # @return [Result] execution result if successful
-      # @raise [Fault] if task fails and task_halt includes the failure status
-      # @example With hash parameters
-      #   begin
-      #     result = ProcessOrderTask.call!(order_id: 123)
-      #   rescue CMDx::Failed => e
-      #     # Handle failure
-      #   end
+      # Executes a task instance and returns the result, raising exceptions on failure.
+      #
+      # Creates a new task instance with the provided context, processes it through
+      # the complete execution pipeline, and returns the result. This method will
+      # raise appropriate fault exceptions if the task fails or is skipped.
       #
-      # @example With Result object (task chaining)
+      # @param args [Array] arguments passed to task constructor
+      #
+      # @return [Result] the execution result containing state, status, and metadata
+      #
+      # @raise [Failed] when task execution fails
+      # @raise [Skipped] when task execution is skipped
+      #
+      # @example Execute task
       #   begin
-      #     extraction_result = ExtractDataTask.call!(source_id: 456)
-      #     processing_result = ProcessDataTask.call!(extraction_result)
+      #     result = MyTask.call!(user_id: 123)
+      #     puts "Success: #{result.status}"
       #   rescue CMDx::Failed => e
-      #     # Handle failure from either task
+      #     puts "Task failed: #{e.message}"
       #   end
       def call!(...)
         instance = new(...)
-        instance.perform!
+        instance.process!
         instance.result
       end
 
     end
 
-    ##
-    # The main execution method that must be implemented by subclasses.
-    # This method contains the core business logic of the task.
+    # Abstract method that must be implemented by task subclasses.
+    #
+    # This method contains the actual business logic for the task. Subclasses
+    # must override this method to provide their specific implementation.
+    # The method has access to the task's context, can modify it, and can
+    # use skip!, fail!, or throw! to control execution flow.
     #
-    # @abstract Subclasses must implement this method
     # @return [void]
-    # @raise [UndefinedCallError] if not implemented in subclass
-    # @example
-    #   def call
-    #     context.user = User.find(user_id)
-    #     fail!(reason: "User not found") unless context.user
     #
-    #     context.user.activate!
-    #     context.activation_date = Time.now
+    # @raise [UndefinedCallError] always raised in the base Task class
+    #
+    # @example Implement in a subclass
+    #   class ProcessUserTask < CMDx::Task
+    #     required :user_id, type: :integer
+    #
+    #     def call
+    #       user = User.find(context.user_id)
+    #       skip!(reason: "User already processed") if user.processed?
+    #
+    #       user.process!
+    #       context.processed_at = Time.now
+    #     end
     #   end
     def call
       raise UndefinedCallError, "call method not defined in #{self.class.name}"
     end
 
-    ##
-    # Executes the task with full exception handling for the non-bang call method.
-    # Captures all exceptions and converts them to appropriate result states.
+    # Executes the task through the middleware pipeline without raising exceptions.
     #
-    # @return [void]
-    def perform
-      return execute_call if cmd_middlewares.empty?
-
-      cmd_middlewares.call(self) { |task| task.send(:execute_call) }
-    end
-
-    ##
-    # Executes the task with exception propagation for the bang call method.
-    # Allows exceptions to bubble up for external handling.
+    # Processes the task by running it through all registered middleware and
+    # the TaskProcessor. This method captures exceptions and converts them
+    # into result states rather than propagating them.
     #
     # @return [void]
-    # @raise [Fault] if task fails and task_halt includes the failure status
-    def perform!
-      return execute_call! if cmd_middlewares.empty?
-
-      cmd_middlewares.call(self) { |task| task.send(:execute_call!) }
-    end
-
-    private
-
-    ##
-    # Returns the logger instance for this task.
     #
-    # @return [Logger] configured logger instance
-    # @api private
-    def logger
-      Logger.call(self)
+    # @example Process a task instance
+    #   task = MyTask.new(data: "input")
+    #   task.process
+    #   puts task.result.status #=> "success", "failed", or "skipped"
+    def process
+      cmd_middlewares.call(self) { |task| TaskProcessor.call(task) }
     end
 
-    ##
-    # Executes before-call callbacks and validations.
-    # Sets up the execution context and validates parameters.
+    # Executes the task through the middleware pipeline, raising exceptions on failure.
     #
-    # @return [void]
-    # @api private
-    def before_call
-      cmd_callbacks.call(self, :before_execution)
-
-      result.executing!
-      cmd_callbacks.call(self, :on_executing)
-
-      cmd_callbacks.call(self, :before_validation)
-      ParameterValidator.call(self)
-      cmd_callbacks.call(self, :after_validation)
-    end
-
-    ##
-    # Executes after-call callbacks based on execution results.
-    # Handles state and status transitions with appropriate callbacks.
+    # Processes the task by running it through all registered middleware and
+    # the TaskProcessor. This method will raise appropriate fault exceptions
+    # if the task fails or is skipped.
     #
     # @return [void]
-    # @api private
-    def after_call
-      cmd_callbacks.call(self, :"on_#{result.state}")
-      cmd_callbacks.call(self, :on_executed) if result.executed?
-
-      cmd_callbacks.call(self, :"on_#{result.status}")
-      cmd_callbacks.call(self, :on_good) if result.good?
-      cmd_callbacks.call(self, :on_bad) if result.bad?
-
-      cmd_callbacks.call(self, :after_execution)
-    end
-
-    ##
-    # Finalizes task execution by freezing the task and logging results.
     #
-    # @return [void]
-    # @api private
-    def terminate_call
-      Immutator.call(self)
-      ResultLogger.call(result)
-    end
-
-    ##
-    # Executes the task directly without middleware for the non-bang call method.
+    # @raise [Failed] when task execution fails
+    # @raise [Skipped] when task execution is skipped
     #
-    # @return [void]
-    # @api private
-    def execute_call
-      result.runtime do
-        before_call
-        call
-      rescue UndefinedCallError => e
-        raise(e)
-      rescue Fault => e
-        throw!(e.result, original_exception: e) if Array(task_setting(:task_halt)).include?(e.result.status)
-      rescue StandardError => e
-        fail!(reason: "[#{e.class}] #{e.message}", original_exception: e)
-      ensure
-        result.executed!
-        after_call
-      end
-
-      terminate_call
+    # @example Process a task instance with exception handling
+    #   task = RiskyTask.new(data: "input")
+    #   begin
+    #     task.process!
+    #     puts "Task completed successfully"
+    #   rescue CMDx::Failed => e
+    #     puts "Task failed: #{e.message}"
+    #   end
+    def process!
+      cmd_middlewares.call(self) { |task| TaskProcessor.call!(task) }
     end
 
-    ##
-    # Executes the task directly without middleware for the bang call method.
+    # Creates a logger instance configured for this task.
     #
-    # @return [void]
-    # @api private
-    def execute_call!
-      result.runtime do
-        before_call
-        call
-      rescue UndefinedCallError => e
-        Chain.clear
-        raise(e)
-      rescue Fault => e
-        result.executed!
-
-        if Array(task_setting(:task_halt)).include?(e.result.status)
-          Chain.clear
-          raise(e)
-        end
-
-        after_call # HACK: treat as NO-OP
-      else
-        result.executed!
-        after_call # ELSE: treat as success
-      end
-
-      terminate_call
+    # Returns a logger instance that is pre-configured with the task's
+    # settings and context information for consistent logging throughout
+    # task execution.
+    #
+    # @return [Logger] configured logger instance for this task
+    #
+    # @example Log task execution
+    #   def call
+    #     logger.info "Starting user processing"
+    #     # ... task logic ...
+    #     logger.info "User processing completed"
+    #   end
+    def logger
+      Logger.call(self)
     end
 
   end