cmdx 1.1.0 → 1.1.1

data/docs/workflows.md

@@ -1,6 +1,6 @@
 # Workflow
 
-A CMDx::Workflow orchestrates sequential execution of multiple tasks in a linear pipeline. Workflows provide a declarative DSL for composing complex business workflows from individual task components, with support for conditional execution, context propagation, and configurable halt behavior.
+CMDx::Workflow orchestrates sequential execution of multiple tasks in a linear pipeline. Workflows provide a declarative DSL for composing complex business workflows from individual task components, with support for conditional execution, context propagation, and configurable halt behavior.
 
 Workflows inherit from Task, gaining all task capabilities including callbacks, parameter validation, result tracking, and configuration. The key difference is that workflows coordinate other tasks rather than implementing business logic directly.
 
@@ -17,55 +17,68 @@ Workflows inherit from Task, gaining all task capabilities including callbacks,
   - [Group-Level Configuration](#group-level-configuration)
   - [Available Result Statuses](#available-result-statuses)
 - [Process Method Options](#process-method-options)
-  - [Condition Callables](#condition-callables)
+- [Error Handling](#error-handling)
 - [Nested Workflows](#nested-workflows)
 - [Task Settings Integration](#task-settings-integration)
 - [Generator](#generator)
 
 ## TLDR
 
-- **Purpose** - Orchestrate sequential execution of multiple tasks in linear pipeline
-- **Declaration** - Use `process` method to declare tasks in execution order
-- **Context sharing** - Context object shared across all tasks for data pipeline
-- **Conditional execution** - Support `:if` and `:unless` options for conditional tasks
-- **Halt behavior** - Configurable stopping on failed/skipped results (default: halt on failed only)
-- **No call method** - Workflows automatically provide execution logic, don't define `call`
+```ruby
+# Basic workflow - sequential task execution
+class OrderWorkflow < CMDx::Workflow
+  process ValidateOrderTask      # Step 1
+  process CalculateTaxTask       # Step 2
+  process ChargePaymentTask      # Step 3
+end
+
+# Conditional execution
+process SendEmailTask, if: proc { context.notify_user? }
+process SkipableTask, unless: :should_skip?
+
+# Halt behavior control
+process CriticalTask, workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED]
+process OptionalTask, workflow_halt: []  # Never halt
+
+# Context flows through all tasks automatically
+result = OrderWorkflow.call(order: order)
+result.context.tax_amount    # Set by CalculateTaxTask
+result.context.payment_id    # Set by ChargePaymentTask
+```
 
 ## Basic Usage
 
 > [!WARNING]
-> Do **NOT** define a `call` method in workflow classes. The workflow class automatically provides the call logic.
+> Do **NOT** define a `call` method in workflow classes. The workflow automatically provides execution logic.
 
 ```ruby
 class OrderProcessingWorkflow < CMDx::Workflow
-  # Sequential task execution
   process ValidateOrderTask
   process CalculateTaxTask
   process ChargePaymentTask
   process FulfillOrderTask
 end
 
-# Execute the workflow
-result = WorkflowProcessOrders.call(order: order, user: current_user)
+# Execute workflow
+result = OrderProcessingWorkflow.call(order: order, user: current_user)
 
 if result.success?
-  redirect_to success_path
+  redirect_to order_path(result.context.order)
 elsif result.failed?
-  flash[:error] = "Order processing failed: #{result.metadata[:reason]}"
-  redirect_to cart_path
+  handle_error(result.metadata[:reason])
 end
 ```
 
 ## Task Declaration
 
-Tasks are declared using the `process` method and organized into groups with shared execution options:
+Tasks are declared using the `process` method in execution order:
 
 ```ruby
-class NotificationDeliveryWorkflow < CMDx::Workflow
-  # Single task declaration
+class NotificationWorkflow < CMDx::Workflow
+  # Single task
   process PrepareNotificationTask
 
-  # Multiple tasks in one declaration (grouped)
+  # Multiple tasks (grouped with same options)
   process SendEmailTask, SendSmsTask, SendPushTask
 
   # Tasks with conditions
@@ -81,34 +94,32 @@ end
 ```
 
 > [!IMPORTANT]
-> Process steps are executed in the order they are declared (FIFO: first in, first out).
+> Tasks execute in declaration order (FIFO). Use grouping to apply the same options to multiple tasks.
 
 ## Context Propagation
 
-The context object is shared across all tasks in the workflow, creating a data pipeline:
+The context object flows through all tasks, creating a data pipeline:
 
 ```ruby
-class EcommerceProcessingWorkflow < CMDx::Workflow
-  process ValidateOrderTask # Sets context.validation_result
-  process CalculateTaxTask  # Uses context.order, sets context.tax_amount
-  process ChargePaymentTask # Uses context.tax_amount, sets context.payment_id
-  process FulfillOrderTask  # Uses context.payment_id, sets context.tracking_number
+class PaymentWorkflow < CMDx::Workflow
+  process ValidateOrderTask  # Sets context.validation_errors
+  process CalculateTaxTask   # Uses context.order, sets context.tax_amount
+  process ChargePaymentTask  # Uses context.tax_amount, sets context.payment_id
 end
 
-result = WorkflowProcessEcommerce.call(order: order)
-# Final context contains data from all executed tasks
-result.context.validation_result # From ValidateOrderTask
-result.context.tax_amount        # From CalculateTaxTask
-result.context.payment_id        # From ChargePaymentTask
-result.context.tracking_number   # From FulfillOrderTask
+result = PaymentWorkflow.call(order: order)
+# Context contains cumulative data from all executed tasks
+result.context.validation_errors  # From ValidateOrderTask
+result.context.tax_amount         # From CalculateTaxTask
+result.context.payment_id         # From ChargePaymentTask
 ```
 
 ## Conditional Execution
 
-Tasks can be executed conditionally using `:if` and `:unless` options. Conditions can be procs, lambdas, or method names:
+Tasks can execute conditionally using `:if` and `:unless` options:
 
 ```ruby
-class UserProcessingWorkflow < CMDx::Workflow
+class UserWorkflow < CMDx::Workflow
   process ValidateUserTask
 
   # Proc condition
@@ -124,7 +135,7 @@ class UserProcessingWorkflow < CMDx::Workflow
   process SendSpecialOfferTask, if: proc {
     context.user.active? &&
     context.feature_enabled?(:offers) &&
-    Time.now.hour.between?(9, 17)
+    business_hours?
   }
 
   private
@@ -132,31 +143,38 @@ class UserProcessingWorkflow < CMDx::Workflow
   def debug_enabled?
     Rails.env.development?
   end
+
+  def business_hours?
+    Time.now.hour.between?(9, 17)
+  end
 end
 ```
 
+> [!NOTE]
+> Conditions are evaluated in the workflow instance context. Skipped tasks return `SKIPPED` status but don't halt execution by default.
+
 ## Halt Behavior
 
-Workflows control execution flow through halt behavior, which determines when to stop processing based on task results.
+Workflows control execution flow by halting on specific result statuses.
 
 ### Default Behavior
 
-By default, workflows halt on `FAILED` status but continue on `SKIPPED`. This reflects the philosophy that skipped tasks are bypass mechanisms, not execution blockers.
+By default, workflows halt on `FAILED` status but continue on `SKIPPED`:
 
 ```ruby
-class DataProcessingWorkflow < CMDx::Workflow
-  process LoadDataTask     # If this fails, workflow stops
-  process ValidateDataTask # If this is skipped, workflow continues
-  process SaveDataTask     # This only runs if LoadDataTask and ValidateDataTask don't fail
+class DataWorkflow < CMDx::Workflow
+  process LoadDataTask      # If fails → workflow stops
+  process ValidateDataTask  # If skipped → workflow continues
+  process SaveDataTask      # Only runs if no failures occurred
 end
 ```
 
 ### Class-Level Configuration
 
-Configure halt behavior for the entire workflow using `cmd_settings!`:
+Configure halt behavior for the entire workflow:
 
 ```ruby
-class CriticalDataProcessingWorkflow < CMDx::Workflow
+class CriticalWorkflow < CMDx::Workflow
   # Halt on both failed and skipped results
   cmd_settings!(workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
 
@@ -164,7 +182,7 @@ class CriticalDataProcessingWorkflow < CMDx::Workflow
   process ValidateCriticalDataTask
 end
 
-class OptionalDataProcessingWorkflow < CMDx::Workflow
+class OptionalWorkflow < CMDx::Workflow
   # Never halt, always continue
   cmd_settings!(workflow_halt: [])
 
@@ -176,73 +194,102 @@ end
 
 ### Group-Level Configuration
 
-Different groups can have different halt behavior:
+Different task groups can have different halt behavior:
 
 ```ruby
-class UserAccountProcessingWorkflow < CMDx::Workflow
+class AccountWorkflow < CMDx::Workflow
   # Critical tasks - halt on any failure or skip
   process CreateUserTask, ValidateUserTask,
     workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED]
 
-  # Optional tasks - never halt execution
-  process SendWelcomeEmailTask, CreateProfileTask, workflow_halt: []
+  # Optional tasks - never halt
+  process SendWelcomeEmailTask, CreateProfileTask,
+    workflow_halt: []
 
-  # Notification tasks - use default behavior (halt on failed only)
+  # Default behavior for remaining tasks
   process NotifyAdminTask, LogUserCreationTask
 end
 ```
 
 ### Available Result Statuses
 
-The following result statuses can be used in `workflow_halt` arrays:
+Use these statuses in `workflow_halt` arrays:
 
-- `CMDx::Result::SUCCESS` - Task completed successfully
-- `CMDx::Result::SKIPPED` - Task was skipped intentionally
-- `CMDx::Result::FAILED` - Task failed due to error or validation
+| Status | Description |
+|--------|-------------|
+| `CMDx::Result::SUCCESS` | Task completed successfully |
+| `CMDx::Result::SKIPPED` | Task was skipped intentionally |
+| `CMDx::Result::FAILED` | Task failed due to error or validation |
 
 ## Process Method Options
 
-The `process` method supports the following options:
+The `process` method supports these options:
 
-| Option        | Description |
-| ------------- | ----------- |
-| `:if`         | Specifies a callable method, proc or string to determine if processing steps should occur. |
-| `:unless`     | Specifies a callable method, proc, or string to determine if processing steps should not occur. |
-| `:workflow_halt` | Sets which result statuses processing of further steps should be prevented. (default: `CMDx::Result::FAILED`) |
+| Option | Description | Example |
+|--------|-------------|---------|
+| `:if` | Execute task if condition is true | `if: proc { context.enabled? }` |
+| `:unless` | Execute task if condition is false | `unless: :should_skip?` |
+| `:workflow_halt` | Which statuses should halt execution | `workflow_halt: [CMDx::Result::FAILED]` |
 
-### Condition Callables
+Conditions can be procs, lambdas, symbols, or strings referencing instance methods.
 
-Conditions can be provided in several formats:
+## Error Handling
 
-```ruby
-class AccountProcessingWorkflow < CMDx::Workflow
-  # Proc - executed in workflow instance context
-  process UpgradeAccountTask, if: proc { context.user.admin? }
+> [!WARNING]
+> Workflow failures provide detailed information about which task failed and why, enabling precise error handling and debugging.
 
-  # Lambda - executed in workflow instance context
-  process MaintenanceModeTask, unless: -> { context.maintenance_mode? }
+```ruby
+class OrderWorkflow < CMDx::Workflow
+  process ValidateOrderTask
+  process CalculateTaxTask
+  process ChargePaymentTask
+end
 
-  # Symbol - method name called on workflow instance
-  process AdvancedFeatureTask, if: :feature_enabled?
+result = OrderWorkflow.call(order: invalid_order)
+
+if result.failed?
+  result.metadata
+  # {
+  #   reason: "ValidateOrderTask failed: Order ID is required",
+  #   failed_task: "ValidateOrderTask",
+  #   task_index: 0,
+  #   executed_tasks: ["ValidateOrderTask"],
+  #   skipped_tasks: [],
+  #   context_at_failure: { order: {...} }
+  # }
+end
+```
 
-  # String - method name called on workflow instance
-  process OptionalTask, unless: "skip_task?"
+### Common Error Scenarios
 
-  private
+```ruby
+# Task raises exception
+class ProcessDataWorkflow < CMDx::Workflow
+  process ValidateDataTask  # Raises validation error
+  process TransformDataTask # Never executes
+end
 
-  def feature_enabled?
-    context.features.include?(:advanced)
-  end
+result = ProcessDataWorkflow.call(data: nil)
+result.failed?  # → true
+result.metadata[:reason]  # → "ValidateDataTask failed: Data cannot be nil"
 
-  def skip_task?
-    context.skip_optional_tasks?
-  end
+# Halt on skipped task
+class StrictWorkflow < CMDx::Workflow
+  process RequiredTask, workflow_halt: [CMDx::Result::SKIPPED]
+  process OptionalTask, if: proc { false }  # Always skipped
+  process FinalTask  # Never executes
 end
+
+result = StrictWorkflow.call
+result.failed?  # → true (halted on skipped task)
 ```
 
+> [!TIP]
+> Use specific halt configurations to implement different failure strategies: strict validation, best-effort processing, or fault-tolerant pipelines.
+
 ## Nested Workflows
 
-Workflows can process other workflows, creating hierarchical workflows:
+Workflows can process other workflows for hierarchical composition:
 
 ```ruby
 class DataPreProcessingWorkflow < CMDx::Workflow
@@ -255,35 +302,33 @@ class DataProcessingWorkflow < CMDx::Workflow
   process ApplyBusinessLogicTask
 end
 
-class DataPostProcessingWorkflow < CMDx::Workflow
-  process GenerateReportTask
-  process SendNotificationTask
-end
-
-class CompleteDataProcessingWorkflow < CMDx::Workflow
+class CompleteDataWorkflow < CMDx::Workflow
   process DataPreProcessingWorkflow
   process DataProcessingWorkflow, if: proc { context.pre_processing_successful? }
-  process DataPostProcessingWorkflow, unless: proc { context.skip_post_processing? }
+  process GenerateReportTask
 end
 ```
 
+> [!NOTE]
+> Nested workflows share the same context object, enabling seamless data flow across workflow boundaries.
+
 ## Task Settings Integration
 
-Workflows support all task settings and can be configured like regular tasks:
+Workflows support all task capabilities including parameters, callbacks, and configuration:
 
 ```ruby
-class PaymentProcessingWorkflow < CMDx::Workflow
-  # Configure workflow-specific settings
+class PaymentWorkflow < CMDx::Workflow
+  # Parameter validation
+  required :order_id, type: :integer
+  optional :notify_user, type: :boolean, default: true
+
+  # Workflow settings
   cmd_settings!(
     workflow_halt: [CMDx::Result::FAILED],
     log_level: :debug,
     tags: [:critical, :payment]
   )
 
-  # Parameter validation
-  required :order_id, type: :integer
-  optional :notify_user, type: :boolean, default: true
-
   # Callbacks
   before_execution :setup_context
   after_execution :cleanup_resources
@@ -306,22 +351,22 @@ end
 
 ## Generator
 
-Generate a new workflow using the Rails generator:
+Generate workflow scaffolding using the Rails generator:
 
 ```bash
 rails g cmdx:workflow ProcessOrder
 ```
 
-This creates a workflow template file under `app/cmds`:
+Creates `app/commands/process_order_workflow.rb`:
 
 ```ruby
-class OrderProcessingWorkflow < ApplicationWorkflow
-  process # TODO
+class ProcessOrderWorkflow < ApplicationWorkflow
+  process # TODO: Add your tasks here
 end
 ```
 
 > [!NOTE]
-> The generator creates workflow files in `app/commands/workflow_[name].rb`, inherits from `ApplicationWorkflow` if available (otherwise `CMDx::Workflow`) and handles proper naming conventions.
+> The generator creates workflow files in `app/commands/`, inherits from `ApplicationWorkflow` if available (otherwise `CMDx::Workflow`), and handles proper naming conventions.
 
 ---
 

data/lib/cmdx/callback.rb

@@ -1,47 +1,51 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Base class for implementing callback functionality in task execution.
+  # Base class for implementing callback functionality in task processing.
   #
-  # Callbacks are executed at specific points during task lifecycle to
-  # provide hooks for custom behavior, logging, validation, or cleanup.
-  # All callback implementations must inherit from this class and implement
-  # the abstract call method.
+  # Callbacks are executed at specific points in the task lifecycle, such as
+  # before execution, after success, or on failure. All callback implementations
+  # must inherit from this class and implement the abstract call method.
   class Callback
 
     # Executes a callback by creating a new instance and calling it.
     #
-    # @param task [Task] the task instance executing the callback
-    # @param type [Symbol] the callback type identifier
+    # @param task [CMDx::Task] the task instance triggering the callback
+    # @param type [Symbol] the callback type being executed (e.g., :before_execution, :on_success, :on_failure)
     #
-    # @return [Object] the result of the callback execution
+    # @return [void]
     #
     # @raise [UndefinedCallError] when the callback subclass doesn't implement call
     #
-    # @example Execute a callback on a task
-    #   MyCallback.call(task, :before)
+    # @example Execute a callback for task success
+    #   LogSuccessCallback.call(task, :on_success)
+    #
+    # @example Execute a callback before task execution
+    #   SetupCallback.call(task, :before_execution)
     def self.call(task, type)
       new.call(task, type)
     end
 
     # Abstract method that must be implemented by callback subclasses.
     #
-    # This method contains the actual callback logic to be executed.
-    # Subclasses must override this method to provide their specific
-    # callback implementation.
+    # This method contains the actual callback logic to be executed at the
+    # specified point in the task lifecycle. Subclasses must override this method
+    # to provide their specific callback implementation.
     #
-    # @param _task [Task] the task instance executing the callback
-    # @param _type [Symbol] the callback type identifier
+    # @param task [CMDx::Task] the task instance triggering the callback
+    # @param type [Symbol] the callback type being executed
     #
-    # @return [Object] the result of the callback execution
+    # @return [void]
     #
     # @raise [UndefinedCallError] always raised in the base class
     #
     # @example Implement in a subclass
-    #   def call(task, type)
-    #     puts "Executing #{type} callback for #{task.class.name}"
+    #   class NotificationCallback < CMDx::Callback
+    #     def call(task, type)
+    #       puts "Task #{task.class.name} triggered #{type} callback"
+    #     end
     #   end
-    def call(_task, _type)
+    def call(task, type) # rubocop:disable Lint/UnusedMethodArgument
       raise UndefinedCallError, "call method not defined in #{self.class.name}"
     end
 

data/lib/cmdx/callback_registry.rb

@@ -20,8 +20,6 @@ module CMDx
       *Result::STATES.map { |s| :"on_#{s}" }
     ].freeze
 
-    # The internal hash storing callback definitions.
-    #
     # @return [Hash] hash containing callback type keys and callback definition arrays
     attr_reader :registry
 
@@ -106,7 +104,7 @@ module CMDx
     #
     # @example Getting registry contents
     #   registry.to_h
-    #   # => { before_execution: [[:setup, {}]], on_good: [[:notify, { if: -> { true } }]] }
+    #   #=> { before_execution: [[:setup, {}]], on_good: [[:notify, { if: -> { true } }]] }
     def to_h
       registry.transform_values(&:dup)
     end

data/lib/cmdx/chain_inspector.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Provides formatted inspection and display functionality for execution chains.
+  # Provides formatted inspection and display functionality for chain execution results.
   #
-  # This module formats chain execution information into a human-readable string
-  # representation, including the chain ID, individual task results, and summary
-  # information about the chain's final state.
+  # ChainInspector creates human-readable string representations of execution chains,
+  # displaying chain metadata, individual task results, and execution summary information
+  # in a formatted layout. The inspector processes chain data to provide comprehensive
+  # debugging and monitoring output for task execution sequences.
   module ChainInspector
 
     FOOTER_KEYS = %i[
@@ -14,31 +15,30 @@ module CMDx
 
     module_function
 
-    # Formats a chain into a human-readable inspection string.
+    # Formats a chain into a human-readable inspection string with headers, results, and summary.
     #
-    # Creates a formatted display showing the chain ID, individual task results,
-    # and summary footer with execution state information. The output includes
-    # visual separators and structured formatting for easy reading.
+    # Creates a comprehensive string representation of the execution chain including
+    # a header with the chain ID, formatted individual task results, and a footer
+    # summary with key execution metadata. The output uses visual separators for
+    # clear section delineation and consistent formatting.
     #
-    # @param chain [CMDx::Chain] the chain object to inspect
+    # @param chain [Chain] the execution chain to format and inspect
     #
-    # @return [String] formatted multi-line string representation of the chain
+    # @return [String] formatted multi-line string representation of the chain execution
     #
-    # @raise [NoMethodError] if chain doesn't respond to required methods (id, results, state, status, outcome, runtime)
-    #
-    # @example Inspect a simple chain
-    #   chain = CMDx::Chain.new(id: "abc123")
-    #   result = CMDx::Result.new(task)
-    #   chain.results << result
-    #   puts CMDx::ChainInspector.call(chain)
-    #   # Output:
-    #   # chain: abc123
-    #   # ===================
+    # @example Format a simple chain
+    #   chain = MyWorkflow.call(user_id: 123)
+    #   output = ChainInspector.call(chain.chain)
+    #   puts output
+    #   # =>
+    #   # chain: abc123-def456-789
+    #   # ===============================
     #   #
-    #   # {:state=>"complete", :status=>"success", ...}
+    #   # {:task=>"MyTask", :state=>"complete", :status=>"success"}
+    #   # {:task=>"OtherTask", :state=>"complete", :status=>"success"}
     #   #
-    #   # ===================
-    #   # state: complete | status: success | outcome: success | runtime: 0.001
+    #   # ===============================
+    #   # state: complete | status: success | outcome: good | runtime: 0.025
     def call(chain)
       header = "\nchain: #{chain.id}"
       footer = FOOTER_KEYS.map { |key| "#{key}: #{chain.send(key)}" }.join(" | ")

data/lib/cmdx/chain_serializer.rb

@@ -1,33 +1,52 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Serializes Chain objects into hash representations for external consumption.
-  # Provides a consistent interface for converting chain execution data into
-  # structured format suitable for logging, API responses, or persistence.
+  # Serialization module for converting chain objects to hash representation.
+  #
+  # ChainSerializer provides functionality to serialize chain objects into a
+  # standardized hash format that includes essential metadata about the chain
+  # execution including unique identification, execution state, status, outcome,
+  # runtime, and all contained task results. The serialized format is commonly
+  # used for debugging, logging, introspection, and data exchange throughout
+  # the task execution pipeline.
   module ChainSerializer
 
     module_function
 
-    # Converts a chain object into a hash representation containing execution metadata.
-    # Extracts key chain attributes and serializes all contained results for complete
-    # execution state capture.
+    # Serializes a chain object into a hash representation.
     #
-    # @param chain [Chain] the chain instance to serialize
+    # Converts a chain instance into a standardized hash format containing
+    # key metadata about the chain's execution context and all contained results.
+    # The serialization includes information delegated from the first result in
+    # the chain (state, status, outcome, runtime) along with the chain's unique
+    # identifier and complete collection of task results converted to hashes.
     #
-    # @return [Hash] hash containing chain metadata and serialized results
+    # @param chain [CMDx::Chain] the chain object to serialize
     #
-    # @raise [NoMethodError] if chain doesn't respond to required methods
+    # @return [Hash] a hash containing the chain's metadata and execution information
+    # @option return [String] :id the unique identifier of the chain
+    # @option return [String] :state the execution state delegated from first result
+    # @option return [String] :status the execution status delegated from first result
+    # @option return [String] :outcome the execution outcome delegated from first result
+    # @option return [Float] :runtime the execution runtime in seconds delegated from first result
+    # @option return [Array<Hash>] :results array of serialized result hashes from all tasks in the chain
     #
-    # @example Serializing a workflow chain
-    #   chain = UserWorkflow.call(user_id: 123)
-    #   ChainSerializer.call(chain)
-    #   # => {
-    #   #   id: "abc123",
-    #   #   state: :complete,
-    #   #   status: :success,
-    #   #   outcome: :good,
-    #   #   runtime: 0.045,
-    #   #   results: [...]
+    # @raise [NoMethodError] if the chain doesn't respond to required methods (id, state, status, outcome, runtime, results)
+    #
+    # @example Serialize a workflow chain with multiple tasks
+    #   workflow = DataProcessingWorkflow.call(input: "data")
+    #   ChainSerializer.call(workflow.chain)
+    #   #=> {
+    #   #   id: "def456",
+    #   #   state: "complete",
+    #   #   status: "success",
+    #   #   outcome: "success",
+    #   #   runtime: 0.123,
+    #   #   results: [
+    #   #     { index: 0, class: "ValidateDataTask", status: "success", ... },
+    #   #     { index: 1, class: "ProcessDataTask", status: "success", ... },
+    #   #     { index: 2, class: "SaveDataTask", status: "success", ... }
+    #   #   ]
     #   # }
     def call(chain)
       {