cmdx 0.5.0 → 1.0.1

data/docs/outcomes/result.md

@@ -1,17 +1,312 @@
-# Outcomes -  Result
+# Outcomes - Result
 
-The result object is returned after a task execution. This is the main object
-that will be interacted with post call.
+The result object is the comprehensive return value of task execution, providing
+complete information about the execution outcome, state, timing, and any data
+produced during the task lifecycle. Results serve as the primary interface for
+inspecting task execution outcomes and chaining task operations.
+
+## Table of Contents
+
+- [TLDR](#tldr)
+- [Core Result Attributes](#core-result-attributes)
+- [State and Status Information](#state-and-status-information)
+- [Execution Outcome Analysis](#execution-outcome-analysis)
+- [Runtime and Performance](#runtime-and-performance)
+- [Failure Chain Analysis](#failure-chain-analysis)
+- [Index and Position](#index-and-position)
+- [Result Callbacks and Chaining](#result-callbacks-and-chaining)
+- [Pattern Matching](#pattern-matching)
+- [Serialization and Inspection](#serialization-and-inspection)
+
+## TLDR
+
+- **Result object** - Comprehensive return value from task execution with `task`, `context`, `chain`, `metadata`
+- **Status checking** - Use `result.success?`, `result.failed?`, `result.skipped?` for outcomes
+- **State checking** - Use `result.complete?`, `result.interrupted?`, `result.executed?` for lifecycle
+- **Callbacks** - Chain with `.on_success`, `.on_failed`, `.on_good`, `.on_bad` for conditional logic
+- **Failure analysis** - Use `result.caused_failure`, `result.threw_failure` to trace failure chains
+
+## Core Result Attributes
+
+Every result provides access to essential execution information:
 
 ```ruby
-result = ProcessOrderTask.call
-result.task     #=> <ProcessOrderTask ...>
-result.context  #=> <CMDx::Context ...>
-result.metadata #=> { ... }
-result.run      #=> <CMDx::Run ...>
+result = ProcessUserOrderTask.call(order_id: 123)
+
+# Core objects
+result.task     #=> <ProcessUserOrderTask instance>
+result.context  #=> <CMDx::Context with all task data>
+result.chain    #=> <CMDx::Chain execution tracking>
+result.metadata #=> Hash with execution metadata
+
+# Execution information
+result.id       #=> "abc123..." (unique task execution ID)
+result.state    #=> "complete" (execution state)
+result.status   #=> "success" (execution outcome)
+result.runtime  #=> 0.5 (execution time in seconds)
 ```
 
+> [!NOTE]
+> Result objects are immutable after task execution completes. All result data reflects the final state of the task execution and cannot be modified.
+
+## State and Status Information
+
+Results provide comprehensive methods for checking execution state and status:
+
+```ruby
+result = ProcessUserOrderTask.call
+
+# State predicates (execution lifecycle)
+result.initialized? #=> false (after execution)
+result.executing?   #=> false (after execution)
+result.complete?    #=> true (successful completion)
+result.interrupted? #=> false (no interruption)
+result.executed?    #=> true (execution finished)
+
+# Status predicates (execution outcome)
+result.success?     #=> true (successful execution)
+result.skipped?     #=> false (not skipped)
+result.failed?      #=> false (no failure)
+
+# Outcome categorization
+result.good?        #=> true (success or skipped)
+result.bad?         #=> false (skipped or failed)
+```
+
+## Execution Outcome Analysis
+
+Results provide additional methods for understanding execution outcomes:
+
+```ruby
+result = ProcessOrderWorkflowTask.call
+
+# Outcome determination
+result.outcome #=> "success" (combines state and status)
+```
+
+## Runtime and Performance
+
+Results capture detailed timing information:
+
+```ruby
+result = ProcessUserOrderTask.call
+
+# Execution timing
+result.runtime #=> 0.5 (total execution time in seconds)
+```
+
+## Failure Chain Analysis
+
+For failed results, comprehensive failure analysis is available:
+
+```ruby
+result = ProcessOrderWorkflowTask.call
+
+if result.failed?
+  # Find the original cause of failure
+  original_failure = result.caused_failure
+  if original_failure
+    puts "Original failure: #{original_failure.task.class.name}"
+    puts "Reason: #{original_failure.metadata[:reason]}"
+  end
+
+  # Find what threw the failure to this result
+  throwing_task = result.threw_failure
+  if throwing_task
+    puts "Failure thrown by: #{throwing_task.task.class.name}"
+  end
+
+  # Failure classification
+  result.caused_failure?  #=> true if this result was the original cause
+  result.threw_failure?   #=> true if this result threw a failure
+  result.thrown_failure?  #=> true if this result received a thrown failure
+end
+```
+
+> [!IMPORTANT]
+> Failure chain analysis is only available for failed results. Use these methods to trace the root cause of failures in complex task workflows.
+
+## Index and Position
+
+Results track their position within execution chains:
+
+```ruby
+result = ProcessUserOrderTask.call
+
+# Position in execution sequence
+result.index #=> 0 (first task in chain)
+
+# Access via chain
+result.chain.results[result.index] == result #=> true
+```
+
+## Result Callbacks and Chaining
+
+Results support fluent callback patterns for conditional logic:
+
+```ruby
+result = ProcessUserOrderTask.call
+
+# State-based callbacks
+result
+  .on_complete { |r| logger.info "Task completed successfully" }
+  .on_interrupted { |r| logger.warn "Task was interrupted" }
+  .on_executed { |r| update_metrics(r.runtime) }
+
+# Status-based callbacks
+result
+  .on_success { |r| send_confirmation_email(r.context) }
+  .on_skipped { |r| logger.info "Skipped: #{r.metadata[:reason]}" }
+  .on_failed { |r| handle_failure(r) }
+
+# Outcome-based callbacks
+result
+  .on_good { |r| celebrate_success }
+  .on_bad { |r| handle_problem }
+```
+
+### Callback Chaining Examples
+
+```ruby
+ProcessUserOrderTask
+  .call(order_id: 123)
+  .on_success { |result|
+    SendOrderNotificationTask.call(result.context)
+  }
+  .on_failed { |result|
+    ErrorReporter.notify(result.metadata)
+  }
+  .on_executed { |result|
+    MetricsService.record_execution_time(result.runtime)
+  }
+```
+
+> [!TIP]
+> Use result callbacks for clean, functional-style conditional logic. Callbacks return the result object, enabling method chaining and fluent interfaces.
+
+## Pattern Matching
+
+Results support Ruby's pattern matching (Ruby 3.0+) through array and hash deconstruction:
+
+### Array Pattern Matching
+
+Match against state and status in order:
+
+```ruby
+result = ProcessUserOrderTask.call
+
+case result
+in ["complete", "success"]
+  puts "Task completed successfully"
+in ["interrupted", "failed"]
+  puts "Task failed during execution"
+in ["complete", "skipped"]
+  puts "Task was skipped but completed"
+end
+```
+
+### Hash Pattern Matching
+
+Match against specific result attributes:
+
+```ruby
+result = ProcessUserOrderTask.call
+
+case result
+in { state: "complete", status: "success" }
+  puts "Perfect execution!"
+in { state: "interrupted", status: "failed", metadata: { retryable: true } }
+  puts "Failed but can retry"
+in { good: true }
+  puts "Execution went well overall"
+in { bad: true, metadata: { reason: String => reason } }
+  puts "Something went wrong: #{reason}"
+end
+```
+
+### Pattern Matching with Guards
+
+Use guard clauses for conditional matching:
+
+```ruby
+case result
+in { status: "failed", metadata: { attempts: n } } if n < 3
+  retry_task(result)
+in { status: "failed", metadata: { attempts: n } } if n >= 3
+  give_up_task(result)
+in { runtime: time } if time > threshold
+  log_performance_issue(result)
+end
+```
+
+> [!NOTE]
+> Pattern matching requires Ruby 3.0+. The `deconstruct` method returns `[state, status]` for array patterns, while `deconstruct_keys` provides hash access to `state`, `status`, `metadata`, `executed`, `good`, and `bad` attributes.
+
+## Serialization and Inspection
+
+Results provide comprehensive serialization and inspection capabilities:
+
+### Hash Serialization
+
+```ruby
+result = ProcessUserOrderTask.call
+
+result.to_h
+#=> {
+#     class: "ProcessUserOrderTask",
+#     type: "Task",
+#     index: 0,
+#     id: "abc123...",
+#     chain_id: "def456...",
+#     tags: [],
+#     state: "complete",
+#     status: "success",
+#     outcome: "success",
+#     metadata: {},
+#     runtime: 0.5
+#   }
+```
+
+### Human-Readable Inspection
+
+```ruby
+result = ProcessUserOrderTask.call
+
+result.to_s
+#=> "ProcessUserOrderTask: type=Task index=0 id=abc123... state=complete status=success outcome=success metadata={} runtime=0.5"
+```
+
+### Failure Chain Serialization
+
+Failed results include failure chain information:
+
+```ruby
+failed_result = ProcessOrderWorkflowTask.call
+
+failed_result.to_h
+#=> {
+#     # ... standard result data ...
+#     caused_failure: {
+#       class: "ValidateUserOrderTask",
+#       index: 1,
+#       id: "xyz789...",
+#       state: "interrupted",
+#       status: "failed"
+#     },
+#     threw_failure: {
+#       class: "ProcessOrderPaymentTask",
+#       index: 2,
+#       id: "uvw123...",
+#       state: "interrupted",
+#       status: "failed"
+#     }
+#   }
+```
+
+> [!NOTE]
+> Serialized results include complete failure chain information for debugging and audit trails. Use `to_h` for structured data and `to_s` for human-readable output.
+
 ---
 
-- **Prev:** [Interruptions - Exceptions](https://github.com/drexed/cmdx/blob/main/docs/interruptions/exceptions.md)
-- **Next:** [Outcomes - Statuses](https://github.com/drexed/cmdx/blob/main/docs/outcomes/statuses.md)
+- **Prev:** [Interruptions - Exceptions](../interruptions/exceptions.md)
+- **Next:** [Outcomes - Statuses](statuses.md)

data/docs/outcomes/states.md

@@ -1,52 +1,233 @@
-# Outcomes -  States
+# Outcomes - States
 
-State represents the condition of all the code task should execute.
+States represent the execution lifecycle condition of task execution, tracking
+the progress of tasks through their complete execution journey. States provide
+insight into where a task is in its lifecycle and enable lifecycle-based
+decision making and monitoring.
 
-| Status        | Description |
+## Table of Contents
+
+- [TLDR](#tldr)
+- [State Definitions](#state-definitions)
+- [State Transitions](#state-transitions)
+- [State Predicates](#state-predicates)
+- [State-Based Callbacks](#state-based-callbacks)
+- [State vs Status Distinction](#state-vs-status-distinction)
+- [State Inspection and Monitoring](#state-inspection-and-monitoring)
+- [State Persistence and Logging](#state-persistence-and-logging)
+
+## TLDR
+
+- **States** - Track execution lifecycle: `initialized` → `executing` → `complete`/`interrupted`
+- **Automatic** - States are managed automatically by the framework, never modify manually
+- **Predicates** - Check with `result.complete?`, `result.interrupted?`, `result.executed?`
+- **Callbacks** - Use `.on_complete`, `.on_interrupted`, `.on_executed` for lifecycle events
+- **vs Status** - State = where in lifecycle, Status = how execution ended
+
+## State Definitions
+
+| State         | Description |
 | ------------- | ----------- |
-| `initialized` | Initial task state prior to any execution. |
-| `executing`   | Task is actively executing code. |
-| `complete`    | Task executed to completion without halting for any reason. |
-| `interrupted` | Task could **NOT** be executed to completion due to a fault/exception. |
+| `initialized` | Task created but execution not yet started. Default state for new tasks. |
+| `executing`   | Task is actively running its business logic. Transient state during execution. |
+| `complete`    | Task finished execution successfully without any interruption or halt. |
+| `interrupted` | Task execution was stopped due to a fault, exception, or explicit halt. |
+
+## State Transitions
 
-> [!CAUTION]
-> States are automatically transitioned and should **NEVER** be altered manually.
+States follow a strict lifecycle with controlled transitions:
 
 ```ruby
-result = ProcessOrderTask.call
-result.state        #=> "complete"
+# Valid state transition flow
+initialized -> executing -> complete    (successful execution)
+initialized -> executing -> interrupted (failed/halted execution)
+```
+
+> [!IMPORTANT]
+> States are automatically managed during task execution and should **never** be modified manually. State transitions are handled internally by the CMDx framework.
 
-result.pending?     #=> false
-result.executing?   #=> false
-result.complete?    #=> true
-result.interrupted? #=> false
+### Automatic State Management
 
-# `complete` or `interrupted`
-result.executed?
+States are automatically managed during task execution and should **never** be modified manually:
+
+```ruby
+task = ProcessUserOrderTask.new
+task.result.state #=> "initialized"
+
+# During task execution, states transition automatically:
+# 1. initialized -> executing (when call begins)
+# 2. executing -> complete (successful completion)
+# 3. executing -> interrupted (on failure/halt)
+
+result = ProcessUserOrderTask.call
+result.state #=> "complete" (if successful)
 ```
 
-## Handlers
+### State Transition Methods (Internal Use)
 
-Results can be used to trigger state based callbacks. Handlers require a block
-and will have the result available as local variable. Callback handlers can be
-chained and repeated.
+These methods handle state transitions internally and are not intended for direct use:
 
 ```ruby
-result = ProcessOrderTask.call
-result.on_complete { do_work }
+result = ProcessUserOrderTask.new.result
+
+# Internal state transition methods
+result.executing!   # initialized -> executing
+result.complete!    # executing -> complete
+result.interrupt!   # executing -> interrupted
+result.executed!    # executing -> complete OR interrupted (based on status)
+```
+
+> [!WARNING]
+> State transition methods (`executing!`, `complete!`, `interrupt!`) are for internal framework use only. Never call these methods directly in your application code.
 
-# - or -
+## State Predicates
 
-ProcessOrderTask
-  .call(...)
-  .on_executing { do_work }
-  .on_executed { |result| $statsd.increment(result.state) }
+Use state predicates to check the current execution lifecycle:
+
+```ruby
+result = ProcessUserOrderTask.call
+
+# Check current state
+result.initialized? #=> false (after execution)
+result.executing?   #=> false (after execution)
+result.complete?    #=> true (successful completion)
+result.interrupted? #=> false (no interruption)
+
+# Combined state checking
+result.executed?    #=> true (complete OR interrupted)
+```
+
+## State-Based Callbacks
+
+Results provide callback methods for state-based conditional execution:
+
+```ruby
+result = ProcessUserOrderTask.call
+
+# Individual state callbacks
+result
+  .on_initialized { |r| log_task_created(r) }
+  .on_executing { |r| show_progress_indicator(r) }
+  .on_complete { |r| celebrate_success(r) }
+  .on_interrupted { |r| handle_interruption(r) }
+
+# Execution completion callback (complete OR interrupted)
+result
+  .on_executed { |r| cleanup_resources(r) }
+```
+
+### Callback Chaining and Combinations
+
+```ruby
+ProcessUserOrderTask
+  .call(order_id: 123)
+  .on_complete { |result|
+    # Only runs if task completed successfully
+    send_confirmation_email(result.context)
+    update_order_status(result.context.order)
+  }
+  .on_interrupted { |result|
+    # Only runs if task was interrupted
+    log_interruption(result.metadata)
+    schedule_retry(result) if result.metadata[:retryable]
+  }
+  .on_executed { |result|
+    # Always runs after execution (complete OR interrupted)
+    update_metrics(result.runtime)
+    cleanup_temporary_files(result.context)
+  }
 ```
 
 > [!TIP]
-> Handlers help execute you logical branches without `if/else` blocks.
+> Use state-based callbacks for lifecycle event handling. The `on_executed` callback is particularly useful for cleanup operations that should run regardless of success or failure.
+
+## State vs Status Distinction
+
+Understanding the difference between states and statuses is crucial:
+
+- **State**: Execution lifecycle position (`initialized` → `executing` → `complete`/`interrupted`)
+- **Status**: Execution outcome (`success`, `skipped`, `failed`)
+
+```ruby
+result = ProcessUserOrderTask.call
+
+# State indicates WHERE in the lifecycle
+result.state    #=> "complete" (finished executing)
+
+# Status indicates HOW the execution ended
+result.status   #=> "success" (executed successfully)
+
+# Both can be different for interrupted tasks
+failed_result = ProcessFailingOrderTask.call
+failed_result.state   #=> "interrupted" (execution stopped)
+failed_result.status  #=> "failed" (outcome was failure)
+```
+
+### State-Status Combinations
+
+| State         | Status    | Meaning |
+| ------------- | --------- | ------- |
+| `initialized` | `success` | Task created, not yet executed |
+| `executing`   | `success` | Task currently running |
+| `complete`    | `success` | Task finished successfully |
+| `complete`    | `skipped` | Task finished by skipping execution |
+| `interrupted` | `failed`  | Task stopped due to failure |
+| `interrupted` | `skipped` | Task stopped by skip condition |
+
+> [!NOTE]
+> State tracks the execution lifecycle (where the task is), while status tracks the outcome (how the task ended). Both provide valuable but different information about task execution.
+
+## State Inspection and Monitoring
+
+States provide valuable information for monitoring and debugging:
+
+```ruby
+result = ProcessUserOrderTask.call
+
+# Basic state information
+puts "Execution state: #{result.state}"
+puts "Task completed: #{result.executed?}"
+
+# State in serialized form
+result.to_h[:state]  #=> "complete"
+
+# Human-readable inspection
+result.to_s
+#=> "ProcessUserOrderTask: type=Task index=0 state=complete status=success outcome=success..."
+```
+
+## State Persistence and Logging
+
+States are automatically captured in result serialization:
+
+```ruby
+result = ProcessUserOrderTask.call
+
+# Hash representation includes state
+result.to_h
+#=> {
+#     class: "ProcessUserOrderTask",
+#     index: 0,
+#     state: "complete",
+#     status: "success",
+#     outcome: "success",
+#     # ... other attributes
+#   }
+
+# Chain-level state aggregation
+result.chain.to_h
+#=> {
+#     id: "chain-uuid...",
+#     state: "complete",      # Derived from first result
+#     status: "success",      # Derived from first result
+#     results: [
+#       { state: "complete", status: "success", ... },
+#       # ... other results
+#     ]
+#   }
+```
 
 ---
 
-- **Prev:** [Outcomes - Statuses](https://github.com/drexed/cmdx/blob/main/docs/outcomes/statuses.md)
-- **Next:** [Hooks](https://github.com/drexed/cmdx/blob/main/docs/hooks.md)
+- **Prev:** [Outcomes - Statuses](statuses.md)
+- **Next:** [Parameters - Definitions](../parameters/definitions.md)