cmdx 1.1.2 → 1.5.1

data/docs/outcomes/states.md

@@ -7,39 +7,12 @@ decision making and monitoring.
 
 ## 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 Persistence and Logging](#state-persistence-and-logging)
+- [Definitions](#definitions)
+- [Transitions](#transitions)
+- [Predicates](#predicates)
+- [Handlers](#handlers)
 
-## TLDR
-
-```ruby
-# Check 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 (complete OR interrupted)
-
-# State-based callbacks
-result
-  .on_complete { |r| send_confirmation_email(r.context) }
-  .on_interrupted { |r| log_error_and_retry(r) }
-  .on_executed { |r| cleanup_resources(r) }
-
-# States: WHERE in lifecycle, Status: HOW it ended
-result.state   #=> "complete" (finished executing)
-result.status  #=> "success" (executed successfully)
-```
-
-## State Definitions
-
-> [!IMPORTANT]
-> States are automatically managed during task execution and should **never** be modified manually. State transitions are handled internally by the CMDx framework.
+## Definitions
 
 | State | Description |
 | ----- | ----------- |
@@ -48,221 +21,60 @@ result.status  #=> "success" (executed successfully)
 | `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
-
-States follow a strict lifecycle with controlled transitions:
-
-```ruby
-# Valid state transition flow
-initialized → executing → complete    (successful execution)
-initialized → executing → interrupted (failed/halted execution)
-```
-
-### Automatic State Management
-
-```ruby
-class ProcessPaymentTask < CMDx::Task
-  def call
-    # State automatically managed:
-    # 1. initialized → executing (when call begins)
-    # 2. executing → complete (successful completion)
-    # 3. executing → interrupted (on failure/halt)
-
-    charge_customer(amount)
-    send_receipt(email)
-  end
-end
+State-Status combinations:
 
-task = ProcessPaymentTask.new
-task.result.state #=> "initialized"
-
-result = ProcessPaymentTask.call
-result.state #=> "complete" (if successful)
-```
+| 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 |
 
-### Internal State Transition Methods
+## Transitions
 
-> [!WARNING]
-> State transition methods (`executing!`, `complete!`, `interrupt!`) are for internal framework use only. Never call these methods directly in your application code.
+> [!CAUTION]
+> States are automatically managed during task execution and should **never** be modified manually. State transitions are handled internally by the CMDx framework.
 
 ```ruby
-result = ProcessPaymentTask.new.result
-
-# Internal state transition methods (DO NOT USE)
-result.executing!   # initialized → executing
-result.complete!    # executing → complete
-result.interrupt!   # executing → interrupted
-result.executed!    # executing → complete OR interrupted (based on status)
+# Valid state transition flow
+initialized → executing → complete    (successful execution)
+initialized → executing → interrupted (skipped/failed execution)
 ```
 
-## State Predicates
+## Predicates
 
 Use state predicates to check the current execution lifecycle:
 
 ```ruby
-class OrderFulfillmentTask < CMDx::Task
-  def call
-    process_order
-    ship_items
-  end
-end
+result = ProcessVideoUpload.execute
 
-result = OrderFulfillmentTask.call
-
-# Check current state
+# Individual state checks
 result.initialized? #=> false (after execution)
 result.executing?   #=> false (after execution)
 result.complete?    #=> true (successful completion)
 result.interrupted? #=> false (no interruption)
 
-# Combined state checking
+# State categorization
 result.executed?    #=> true (complete OR interrupted)
 ```
 
-### State Checking in Conditional Logic
-
-```ruby
-def handle_task_result(result)
-  if result.complete?
-    notify_success(result.context)
-  elsif result.interrupted?
-    handle_failure(result.metadata)
-  end
+## Handlers
 
-  # Always cleanup when execution finished
-  cleanup_resources if result.executed?
-end
-```
-
-## State-Based Callbacks
-
-> [!TIP]
-> 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.
+Use state-based handlers for lifecycle event handling. The `on_executed` handler is particularly useful for cleanup operations that should run regardless of success, skipped, or failure.
 
 ```ruby
-class ProcessOrderTask < CMDx::Task
-  def call
-    validate_inventory
-    charge_payment
-    update_stock
-  end
-end
-
-result = ProcessOrderTask.call
+result = ProcessVideoUpload.execute
 
-# Individual state callbacks
+# Individual state handlers
 result
-  .on_complete { |r| send_confirmation_email(r.context.customer_email) }
-  .on_interrupted { |r| log_error(r.metadata) && schedule_retry(r) }
-  .on_executed { |r| update_analytics(r.runtime) }
-```
-
-### Advanced Callback Patterns
-
-```ruby
-ProcessOrderTask
-  .call(order_id: 123)
-  .on_complete { |result|
-    # Only runs if task completed successfully
-    OrderMailer.confirmation(result.context.order).deliver_now
-    Analytics.track("order_processed", order_id: result.context.order_id)
-  }
-  .on_interrupted { |result|
-    # Only runs if task was interrupted
-    ErrorLogger.log(result.metadata[:error])
-
-    if result.metadata[:retryable]
-      RetryWorker.perform_later(result.context.order_id)
-    end
-  }
-  .on_executed { |result|
-    # Always runs after execution (complete OR interrupted)
-    PerformanceTracker.record(result.runtime)
-    TempFileCleanup.perform(result.context.temp_files)
-  }
-```
-
-## State vs Status Distinction
-
-> [!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.
-
-Understanding the difference between states and statuses is crucial:
-
-- **State**: Execution lifecycle position (`initialized` → `executing` → `complete`/`interrupted`)
-- **Status**: Execution outcome (`success`, `skipped`, `failed`)
-
-```ruby
-class ProcessRefundTask < CMDx::Task
-  def call
-    return unless eligible_for_refund?
-
-    process_refund
-    notify_customer
-  end
-end
-
-# Successful execution
-result = ProcessRefundTask.call
-result.state    #=> "complete" (finished executing)
-result.status   #=> "success" (executed successfully)
-
-# Failed execution
-failed_result = ProcessRefundTask.call(invalid_order_id: "xyz")
-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 |
-
-## State Persistence and Logging
-
-> [!IMPORTANT]
-> States are automatically captured in result serialization and logging. All state information persists through the complete task execution lifecycle.
-
-```ruby
-result = ProcessOrderTask.call
-
-# Hash representation includes state
-result.to_h
-#=> {
-#     class: "ProcessOrderTask",
-#     index: 0,
-#     state: "complete",
-#     status: "success",
-#     outcome: "success",
-#     runtime: 0.045,
-#     metadata: {},
-#     context: { order_id: 123 }
-#   }
-
-# Human-readable inspection
-result.to_s
-#=> "ProcessOrderTask: type=Task index=0 state=complete status=success outcome=success runtime=0.045s"
-
-# Chain-level state aggregation
-result.chain.to_h
-#=> {
-#     id: "chain-550e8400-e29b-41d4-a716-446655440000",
-#     state: "complete",      # Derived from overall chain state
-#     status: "success",      # Derived from overall chain status
-#     results: [
-#       { state: "complete", status: "success", ... },
-#       { state: "complete", status: "success", ... }
-#     ]
-#   }
+  .on_complete { |result| send_upload_notification(result) }
+  .on_interrupted { |result| cleanup_temp_files(result) }
+  .on_executed { |result| log_upload_metrics(result) }
 ```
 
 ---
 
-- **Prev:** [Outcomes - Statuses](statuses.md)
-- **Next:** [Parameters - Definitions](../parameters/definitions.md)
+- **Prev:** [Outcomes - Result](result.md)
+- **Next:** [Outcomes - Statuses](statuses.md)

data/docs/outcomes/statuses.md

@@ -4,43 +4,12 @@ Statuses represent the business outcome of task execution logic, indicating how
 
 ## Table of Contents
 
-- [TLDR](#tldr)
-- [Status Definitions](#status-definitions)
-- [Status Transitions](#status-transitions)
-- [Status Predicates](#status-predicates)
-- [Status-Based Callbacks](#status-based-callbacks)
-- [Status Metadata](#status-metadata)
-- [Outcome-Based Logic](#outcome-based-logic)
-- [Status vs State vs Outcome](#status-vs-state-vs-outcome)
-- [Status Serialization and Inspection](#status-serialization-and-inspection)
+- [Definitions](#definitions)
+- [Transitions](#transitions)
+- [Predicates](#predicates)
+- [Handlers](#handlers)
 
-## TLDR
-
-```ruby
-# Check business outcomes
-result.success?  # → true (default outcome)
-result.skipped?  # → false (via skip!)
-result.failed?   # → false (via fail!)
-
-# Outcome-based logic
-result.good?     # → true (success OR skipped)
-result.bad?      # → false (skipped OR failed)
-
-# Status-based callbacks
-result
-  .on_success { |r| process_success(r) }
-  .on_skipped { |r| handle_skip_condition(r) }
-  .on_failed { |r| handle_business_failure(r) }
-
-# Statuses: HOW it ended, States: WHERE in lifecycle
-result.status  #=> "success" (business outcome)
-result.state   #=> "complete" (execution lifecycle)
-```
-
-## Status Definitions
-
-> [!IMPORTANT]
-> Statuses represent business outcomes, not technical execution states. A task can be technically "complete" but have a "failed" status if business logic determined the operation could not succeed.
+## Definitions
 
 | Status | Description |
 | ------ | ----------- |
@@ -48,13 +17,11 @@ result.state   #=> "complete" (execution lifecycle)
 | `skipped` | Task intentionally stopped execution because conditions weren't met or continuation was unnecessary. |
 | `failed` | Task stopped execution due to business rule violations, validation errors, or exceptions. |
 
-## Status Transitions
+## Transitions
 
-> [!WARNING]
+> [!IMPORTANT]
 > Status transitions are unidirectional and final. Once a task is marked as skipped or failed, it cannot return to success status. Design your business logic accordingly.
 
-Unlike states, statuses can only transition from success to skipped/failed:
-
 ```ruby
 # Valid status transitions
 success → skipped    # via skip!
@@ -67,46 +34,12 @@ failed → success     # ❌ Cannot transition
 failed → skipped     # ❌ Cannot transition
 ```
 
-### Status Transition Examples
-
-```ruby
-class ProcessOrderTask < CMDx::Task
-  def call
-    # Task starts with success status
-    context.result.success? #=> true
-
-    # Conditional skip
-    if context.order.already_processed?
-      skip!(reason: "Order already processed")
-      # Status is now skipped, execution halts
-    end
-
-    # Conditional failure
-    unless context.user.authorized?
-      fail!(reason: "Insufficient permissions")
-      # Status is now failed, execution halts
-    end
-
-    # Continue with business logic
-    process_order
-    # Status remains success
-  end
-end
-```
-
-## Status Predicates
+## Predicates
 
 Use status predicates to check execution outcomes:
 
 ```ruby
-class PaymentProcessingTask < CMDx::Task
-  def call
-    charge_customer
-    send_receipt
-  end
-end
-
-result = PaymentProcessingTask.call
+result = ProcessNotification.execute
 
 # Individual status checks
 result.success? #=> true/false
@@ -118,249 +51,26 @@ result.good?    #=> true if success OR skipped
 result.bad?     #=> true if skipped OR failed (not success)
 ```
 
-### Status Checking in Business Logic
+## Handlers
 
-```ruby
-def handle_payment_result(result)
-  if result.success?
-    send_confirmation_email(result.context.customer)
-  elsif result.skipped?
-    log_skip_reason(result.metadata[:reason])
-  elsif result.failed?
-    handle_payment_failure(result.metadata)
-  end
-end
-```
-
-## Status-Based Callbacks
-
-> [!TIP]
-> Use status-based callbacks for business logic branching. The `on_good` and `on_bad` callbacks are particularly useful for handling success/skip vs failed outcomes respectively.
+Use status-based handlers for business logic branching. The `on_good` and `on_bad` handlers are particularly useful for handling success/skip vs failed outcomes respectively.
 
 ```ruby
-class OrderFulfillmentTask < CMDx::Task
-  def call
-    validate_inventory
-    process_payment
-    schedule_shipping
-  end
-end
-
-result = OrderFulfillmentTask.call
+result = ProcessNotification.execute
 
-# Individual status callbacks
+# Individual status handlers
 result
-  .on_success { |r| schedule_delivery(r.context.order) }
-  .on_skipped { |r| notify_backorder(r.context.customer) }
-  .on_failed { |r| refund_payment(r.context.payment_id) }
+  .on_success { |result| mark_notification_sent(result) }
+  .on_skipped { |result| log_notification_skipped(result) }
+  .on_failed { |result| queue_retry_notification(result) }
 
-# Outcome-based callbacks
+# Outcome-based handlers
 result
-  .on_good { |r| update_inventory(r.context.items) }
-  .on_bad { |r| log_negative_outcome(r.metadata) }
-```
-
-## Status Metadata
-
-> [!NOTE]
-> Always include rich metadata with skip and fail operations. This information is invaluable for debugging, user feedback, and automated error handling.
-
-### Success Metadata
-
-```ruby
-class ProcessRefundTask < CMDx::Task
-  def call
-    refund = create_refund(context.payment_id)
-    context.refund_id = refund.id
-    context.processed_at = Time.now
-  end
-end
-
-result = ProcessRefundTask.call(payment_id: "pay_123")
-result.success?  #=> true
-result.metadata  #=> {} (typically empty for success)
-```
-
-### Skip Metadata
-
-```ruby
-class ProcessSubscriptionTask < CMDx::Task
-  def call
-    subscription = Subscription.find(context.subscription_id)
-
-    if subscription.cancelled?
-      skip!(
-        reason: "Subscription already cancelled",
-        cancelled_at: subscription.cancelled_at,
-        skip_code: "ALREADY_CANCELLED"
-      )
-    end
-
-    process_subscription(subscription)
-  end
-end
-
-result = ProcessSubscriptionTask.call(subscription_id: 123)
-if result.skipped?
-  result.metadata[:reason]       #=> "Subscription already cancelled"
-  result.metadata[:cancelled_at] #=> 2023-10-01 10:30:00 UTC
-  result.metadata[:skip_code]    #=> "ALREADY_CANCELLED"
-end
-```
-
-### Failure Metadata
-
-```ruby
-class ValidateUserDataTask < CMDx::Task
-  def call
-    user = User.find(context.user_id)
-
-    unless user.valid?
-      fail!(
-        reason: "User validation failed",
-        errors: user.errors.full_messages,
-        error_code: "VALIDATION_FAILED",
-        retryable: false
-      )
-    end
-
-    context.validated_user = user
-  end
-end
-
-result = ValidateUserDataTask.call(user_id: 123)
-if result.failed?
-  result.metadata[:reason]      #=> "User validation failed"
-  result.metadata[:errors]      #=> ["Email is invalid", "Name can't be blank"]
-  result.metadata[:error_code]  #=> "VALIDATION_FAILED"
-  result.metadata[:retryable]   #=> false
-end
-```
-
-## Outcome-Based Logic
-
-Statuses enable sophisticated outcome-based decision making:
-
-### Good vs Bad Outcomes
-
-```ruby
-class EmailDeliveryTask < CMDx::Task
-  def call
-    # Business logic here
-    send_email
-  end
-end
-
-result = EmailDeliveryTask.call
-
-# Good outcomes (success OR skipped)
-if result.good?
-  # Both success and skipped are "good" outcomes
-  update_user_interface(result)
-  track_completion_metrics(result)
-end
-
-# Bad outcomes (skipped OR failed, excluding success)
-if result.bad?
-  # Handle any non-success outcome
-  show_error_message(result.metadata[:reason])
-  track_failure_metrics(result)
-end
-```
-
-### Conditional Processing
-
-```ruby
-def process_batch_results(results)
-  successful_count = results.count(&:success?)
-  skipped_count = results.count(&:skipped?)
-  failed_count = results.count(&:failed?)
-
-  if results.all?(&:good?)
-    mark_batch_complete
-  elsif results.any?(&:failed?)
-    schedule_batch_retry(results.select(&:failed?))
-  end
-end
-```
-
-## Status vs State vs Outcome
-
-> [!NOTE]
-> Status tracks the business outcome (how the task ended), while state tracks the execution lifecycle (where the task is). Both provide valuable but different information about task execution.
-
-Understanding the relationship between these concepts:
-
-- **Status**: Business execution outcome (`success`, `skipped`, `failed`)
-- **State**: Technical execution lifecycle (`initialized`, `executing`, `complete`, `interrupted`)
-- **Outcome**: Combined representation for unified logic
-
-```ruby
-class DataImportTask < CMDx::Task
-  def call
-    import_data
-    validate_data
-  end
-end
-
-result = DataImportTask.call
-
-# Successful execution
-result.state    #=> "complete" (execution finished)
-result.status   #=> "success" (business outcome)
-result.outcome  #=> "success" (same as status when complete)
-
-# Skipped execution
-skipped_result = DataImportTask.call(skip_import: true)
-skipped_result.state    #=> "complete" (execution finished)
-skipped_result.status   #=> "skipped" (business outcome)
-skipped_result.outcome  #=> "skipped" (same as status)
-
-# Failed execution
-failed_result = DataImportTask.call(invalid_data: true)
-failed_result.state     #=> "interrupted" (execution stopped)
-failed_result.status    #=> "failed" (business outcome)
-failed_result.outcome   #=> "interrupted" (reflects state for interrupted tasks)
-```
-
-## Status Serialization and Inspection
-
-> [!IMPORTANT]
-> Statuses are automatically captured in result serialization and logging. All status information persists through the complete task execution lifecycle.
-
-```ruby
-result = ProcessOrderTask.call
-
-# Hash representation includes status
-result.to_h
-#=> {
-#     class: "ProcessOrderTask",
-#     index: 0,
-#     state: "complete",
-#     status: "success",
-#     outcome: "success",
-#     runtime: 0.045,
-#     metadata: {},
-#     context: { order_id: 123 }
-#   }
-
-# Human-readable inspection
-result.to_s
-#=> "ProcessOrderTask: type=Task index=0 state=complete status=success outcome=success runtime=0.045s"
-
-# Chain-level status aggregation
-result.chain.to_h
-#=> {
-#     id: "chain-550e8400-e29b-41d4-a716-446655440000",
-#     state: "complete",
-#     status: "success",
-#     results: [
-#       { state: "complete", status: "success", ... }
-#     ]
-#   }
+  .on_good { |result| update_message_stats(result) }
+  .on_bad { |result| track_delivery_failure(result) }
 ```
 
 ---
 
-- **Prev:** [Outcomes - Result](result.md)
-- **Next:** [Outcomes - States](states.md)
+- **Prev:** [Outcomes - States](states.md)
+- **Next:** [Attributes - Definitions](../attributes/definitions.md)