tasker-rb 0.1.1

data/lib/tasker_core/types/batch_processing_outcome.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require 'dry-types'
+
+module TaskerCore
+  module Types
+    # BatchProcessingOutcome - TAS-59 Batch Processing Implementation
+    #
+    # Represents the outcome of a batch processing handler execution.
+    # Batch processing handlers determine whether to create worker batches
+    # based on business logic and data volume.
+    #
+    # ## Usage Patterns
+    #
+    # ### No Batches (No worker batches needed)
+    # ```ruby
+    # BatchProcessingOutcome.no_batches
+    # ```
+    #
+    # ### Create Worker Batches
+    # ```ruby
+    # # Create batches for processing large datasets
+    # cursor_configs = [
+    #   { 'batch_id' => '001', 'start_cursor' => 1, 'end_cursor' => 200 },
+    #   { 'batch_id' => '002', 'start_cursor' => 201, 'end_cursor' => 400 },
+    #   { 'batch_id' => '003', 'start_cursor' => 401, 'end_cursor' => 600 }
+    # ]
+    #
+    # BatchProcessingOutcome.create_batches(
+    #   worker_template_name: 'process_batch_worker',
+    #   worker_count: 3,
+    #   cursor_configs: cursor_configs,
+    #   total_items: 250
+    # )
+    # ```
+    #
+    # ## Integration with Step Handlers
+    #
+    # Batch processing handlers should return this outcome in their result:
+    #
+    # ```ruby
+    # def call(context)
+    #   # Business logic to determine if batching is needed
+    #   total_records = context.get_task_field('total_records')
+    #
+    #   outcome = if total_records > 1000
+    #     # Create batches for parallel processing
+    #     cursor_configs = calculate_cursor_configs(total_records)
+    #     BatchProcessingOutcome.create_batches(
+    #       worker_template_name: 'batch_processor',
+    #       worker_count: cursor_configs.size,
+    #       cursor_configs: cursor_configs,
+    #       total_items: total_records
+    #     )
+    #   else
+    #     # Process inline, no batches needed
+    #     BatchProcessingOutcome.no_batches
+    #   end
+    #
+    #   StepHandlerCallResult.success(
+    #     result: {
+    #       batch_processing_outcome: outcome.to_h
+    #     },
+    #     metadata: {
+    #       operation: 'batch_decision',
+    #       batches_created: outcome.requires_batch_creation? ? cursor_configs.size : 0
+    #     }
+    #   )
+    # end
+    # ```
+    module BatchProcessingOutcome
+      module Types
+        include Dry.Types()
+      end
+
+      # NoBatches outcome - no worker batches needed
+      class NoBatches < Dry::Struct
+        # Type discriminator (matches Rust serde tag field)
+        attribute :type, Types::String.default('no_batches')
+
+        # Convert to hash for serialization to Rust
+        # Note: Rust expects lowercase snake_case due to #[serde(rename_all = "snake_case")]
+        def to_h
+          { 'type' => 'no_batches' }
+        end
+
+        # Check if this outcome requires batch creation
+        def requires_batch_creation?
+          false
+        end
+      end
+
+      # CreateBatches outcome - create worker batches for parallel processing
+      class CreateBatches < Dry::Struct
+        # Type discriminator (matches Rust serde tag field)
+        attribute :type, Types::String.default('create_batches')
+
+        # Name of the worker template to use for batch processing
+        attribute :worker_template_name, Types::Strict::String
+
+        # Number of worker batches to create
+        attribute :worker_count, Types::Strict::Integer.constrained(gteq: 0)
+
+        # Array of cursor configurations for batch processing
+        # Each config is a flexible hash (e.g., batch_id, start_cursor, end_cursor, batch_size)
+        attribute :cursor_configs, Types::Array.of(Types::Hash).constrained(min_size: 1)
+
+        # Total number of items to be processed across all batches
+        attribute :total_items, Types::Strict::Integer.constrained(gteq: 0)
+
+        # Convert to hash for serialization to Rust
+        # Note: Rust expects lowercase snake_case due to #[serde(rename_all = "snake_case")]
+        def to_h
+          {
+            'type' => 'create_batches',
+            'worker_template_name' => worker_template_name,
+            'worker_count' => worker_count,
+            'cursor_configs' => cursor_configs,
+            'total_items' => total_items
+          }
+        end
+
+        # Check if this outcome requires batch creation
+        def requires_batch_creation?
+          true
+        end
+      end
+
+      # Factory methods for creating outcomes
+      class << self
+        # Create a NoBatches outcome
+        #
+        # Use when the batch processing handler determines that no worker
+        # batches are needed (e.g., small dataset, inline processing).
+        #
+        # @return [NoBatches] A no-batches outcome instance
+        #
+        # @example
+        #   BatchProcessingOutcome.no_batches
+        def no_batches
+          NoBatches.new
+        end
+
+        # Create a CreateBatches outcome with specified batch configuration
+        #
+        # Use when the batch processing handler determines that worker batches
+        # should be created for parallel processing.
+        #
+        # @param worker_template_name [String] Name of worker template to use
+        # @param worker_count [Integer] Number of worker batches to create (must be >= 0)
+        # @param cursor_configs [Array<Hash>] Array of cursor configurations
+        # @param total_items [Integer] Total number of items to process (must be >= 0)
+        # @return [CreateBatches] A create-batches outcome instance
+        # @raise [ArgumentError] if required parameters are invalid
+        #
+        # @example Create batches for CSV row processing
+        #   cursor_configs = [
+        #     { 'batch_id' => '001', 'start_cursor' => 1, 'end_cursor' => 200, 'batch_size' => 200 },
+        #     { 'batch_id' => '002', 'start_cursor' => 201, 'end_cursor' => 400, 'batch_size' => 200 }
+        #   ]
+        #   BatchProcessingOutcome.create_batches(
+        #     worker_template_name: 'process_csv_batch',
+        #     worker_count: 2,
+        #     cursor_configs: cursor_configs,
+        #     total_items: 400
+        #   )
+        def create_batches(worker_template_name:, worker_count:, cursor_configs:, total_items:)
+          if worker_template_name.nil? || worker_template_name.empty?
+            raise ArgumentError,
+                  'worker_template_name cannot be empty'
+          end
+          raise ArgumentError, 'cursor_configs cannot be empty' if cursor_configs.nil? || cursor_configs.empty?
+
+          # Validate cursor_configs count matches worker_count
+          if cursor_configs.size != worker_count
+            raise ArgumentError,
+                  "cursor_configs length (#{cursor_configs.size}) must equal worker_count (#{worker_count})"
+          end
+
+          # Validate batch_size consistency for numeric cursors
+          # Only validate when both cursors are integers (flexible cursors like UUIDs/timestamps don't have batch_size)
+          cursor_configs.each_with_index do |config, index|
+            next unless config.key?('batch_size') || config.key?(:batch_size)
+
+            # Extract values supporting both string and symbol keys
+            start_cursor = config['start_cursor'] || config[:start_cursor]
+            end_cursor = config['end_cursor'] || config[:end_cursor]
+            batch_size = config['batch_size'] || config[:batch_size]
+
+            # Only validate for numeric cursors
+            next unless start_cursor.is_a?(Integer) && end_cursor.is_a?(Integer)
+
+            expected_batch_size = end_cursor - start_cursor
+
+            next unless batch_size != expected_batch_size
+
+            raise ArgumentError,
+                  "cursor_configs[#{index}] batch_size (#{batch_size}) must equal " \
+                  "end_cursor - start_cursor (#{end_cursor} - #{start_cursor} = #{expected_batch_size})"
+          end
+
+          CreateBatches.new(
+            worker_template_name: worker_template_name,
+            worker_count: worker_count,
+            cursor_configs: cursor_configs,
+            total_items: total_items
+          )
+        end
+
+        # Parse a BatchProcessingOutcome from a hash
+        #
+        # Used to deserialize outcomes from step handler results.
+        # Supports both symbol and string keys for maximum flexibility.
+        #
+        # @param hash [Hash] The hash representation of an outcome
+        # @return [NoBatches, CreateBatches] The parsed outcome
+        # @raise [ArgumentError] If hash is invalid or missing required fields
+        #
+        # @example Parse no-batches outcome
+        #   outcome = BatchProcessingOutcome.from_hash({
+        #     type: 'no_batches'
+        #   })
+        #
+        # @example Parse create-batches outcome
+        #   outcome = BatchProcessingOutcome.from_hash({
+        #     'type' => 'create_batches',
+        #     'worker_template_name' => 'batch_worker',
+        #     'worker_count' => 3,
+        #     'cursor_configs' => [
+        #       { 'cursor_key' => 'offset', 'cursor_value' => 0 }
+        #     ],
+        #     'total_items' => 300
+        #   })
+        def from_hash(hash)
+          raise ArgumentError, 'Expected Hash, got nil' if hash.nil?
+          raise ArgumentError, "Expected Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+          # Support both symbol and string keys
+          # Note: Rust sends lowercase snake_case due to #[serde(rename_all = "snake_case")]
+          hash = deep_symbolize_keys(hash)
+          outcome_type = hash[:type]
+
+          case outcome_type
+          when 'no_batches'
+            NoBatches.new
+          when 'create_batches'
+            worker_template_name = hash[:worker_template_name]
+            worker_count = hash[:worker_count]
+            cursor_configs = hash[:cursor_configs]
+            total_items = hash[:total_items]
+
+            if worker_template_name.nil? || worker_template_name.empty?
+              raise ArgumentError, 'worker_template_name is required for create_batches outcome'
+            end
+
+            if worker_count.nil? || worker_count.negative?
+              raise ArgumentError,
+                    'worker_count is required and must be >= 0'
+            end
+
+            unless cursor_configs.is_a?(Array) && !cursor_configs.empty?
+              raise ArgumentError, 'cursor_configs must be a non-empty array'
+            end
+            raise ArgumentError, 'total_items is required and must be >= 0' if total_items.nil? || total_items.negative?
+
+            CreateBatches.new(
+              worker_template_name: worker_template_name,
+              worker_count: worker_count,
+              cursor_configs: cursor_configs,
+              total_items: total_items
+            )
+          else
+            raise ArgumentError, "Unknown outcome type: #{outcome_type.inspect}"
+          end
+        end
+
+        private
+
+        # Deep symbolize hash keys for consistent access
+        # Handles nested hashes and arrays of hashes
+        def deep_symbolize_keys(hash)
+          return hash unless hash.is_a?(Hash)
+
+          hash.each_with_object({}) do |(key, value), result|
+            new_key = key.to_sym
+            new_value = case value
+                        when Hash
+                          deep_symbolize_keys(value)
+                        when Array
+                          value.map { |v| v.is_a?(Hash) ? deep_symbolize_keys(v) : v }
+                        else
+                          value
+                        end
+            result[new_key] = new_value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tasker_core/types/client_types.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require 'dry-types'
+
+module TaskerCore
+  module Types
+    # TAS-231: Client API response types for orchestration client FFI.
+    #
+    # These types match the JSON responses from the orchestration API,
+    # as returned by the client FFI functions (client_create_task, etc.).
+    module ClientTypes
+      module Types
+        include Dry.Types()
+      end
+
+      # Step readiness status within a task response
+      class StepReadiness < Dry::Struct
+        attribute :workflow_step_uuid, Types::String
+        attribute :task_uuid, Types::String
+        attribute :named_step_uuid, Types::String
+        attribute :name, Types::String
+        attribute :current_state, Types::String
+        attribute :dependencies_satisfied, Types::Bool
+        attribute :retry_eligible, Types::Bool
+        attribute :ready_for_execution, Types::Bool
+        attribute? :last_failure_at, Types::String.optional
+        attribute? :next_retry_at, Types::String.optional
+        attribute :total_parents, Types::Integer
+        attribute :completed_parents, Types::Integer
+        attribute :attempts, Types::Integer
+        attribute :max_attempts, Types::Integer
+        attribute? :backoff_request_seconds, Types::Integer.optional
+        attribute? :last_attempted_at, Types::String.optional
+      end
+
+      # Task response from the orchestration API.
+      # Returned by client_create_task and client_get_task.
+      class TaskResponse < Dry::Struct
+        attribute :task_uuid, Types::String
+        attribute :name, Types::String
+        attribute :namespace, Types::String
+        attribute :version, Types::String
+        attribute :status, Types::String
+        attribute :created_at, Types::String
+        attribute :updated_at, Types::String
+        attribute? :completed_at, Types::String.optional
+        attribute :context, Types::Hash
+        attribute :initiator, Types::String
+        attribute :source_system, Types::String
+        attribute :reason, Types::String
+        attribute? :priority, Types::Integer.optional
+        attribute? :tags, Types::Array.of(Types::String).optional
+        attribute :correlation_id, Types::String
+        attribute? :parent_correlation_id, Types::String.optional
+
+        # Execution context
+        attribute :total_steps, Types::Integer
+        attribute :pending_steps, Types::Integer
+        attribute :in_progress_steps, Types::Integer
+        attribute :completed_steps, Types::Integer
+        attribute :failed_steps, Types::Integer
+        attribute :ready_steps, Types::Integer
+        attribute :execution_status, Types::String
+        attribute :recommended_action, Types::String
+        attribute :completion_percentage, Types::Float
+        attribute :health_status, Types::String
+
+        # Step readiness
+        attribute :steps, Types::Array.default([].freeze)
+
+        def to_s
+          "#<ClientTaskResponse #{namespace}/#{name}:#{version} status=#{status}>"
+        end
+      end
+
+      # Pagination information in list responses
+      class PaginationInfo < Dry::Struct
+        attribute :page, Types::Integer
+        attribute :per_page, Types::Integer
+        attribute :total_count, Types::Integer
+        attribute :total_pages, Types::Integer
+        attribute :has_next, Types::Bool
+        attribute :has_previous, Types::Bool
+      end
+
+      # Task list response with pagination.
+      # Returned by client_list_tasks.
+      class TaskListResponse < Dry::Struct
+        attribute :tasks, Types::Array.default([].freeze)
+        attribute :pagination, Types::Hash
+      end
+
+      # Step response from the orchestration API.
+      # Returned by client_get_step.
+      class StepResponse < Dry::Struct
+        attribute :step_uuid, Types::String
+        attribute :task_uuid, Types::String
+        attribute :name, Types::String
+        attribute :created_at, Types::String
+        attribute :updated_at, Types::String
+        attribute? :completed_at, Types::String.optional
+        attribute? :results, Types::Hash.optional
+
+        # Readiness fields
+        attribute :current_state, Types::String
+        attribute :dependencies_satisfied, Types::Bool
+        attribute :retry_eligible, Types::Bool
+        attribute :ready_for_execution, Types::Bool
+        attribute :total_parents, Types::Integer
+        attribute :completed_parents, Types::Integer
+        attribute :attempts, Types::Integer
+        attribute :max_attempts, Types::Integer
+        attribute? :last_failure_at, Types::String.optional
+        attribute? :next_retry_at, Types::String.optional
+        attribute? :last_attempted_at, Types::String.optional
+      end
+
+      # Step audit history response (SOC2 compliance).
+      # Returned by client_get_step_audit_history.
+      class StepAuditResponse < Dry::Struct
+        attribute :audit_uuid, Types::String
+        attribute :workflow_step_uuid, Types::String
+        attribute :transition_uuid, Types::String
+        attribute :task_uuid, Types::String
+        attribute :recorded_at, Types::String
+        attribute? :worker_uuid, Types::String.optional
+        attribute? :correlation_id, Types::String.optional
+        attribute :success, Types::Bool
+        attribute? :execution_time_ms, Types::Integer.optional
+        attribute? :result, Types::Hash.optional
+        attribute :step_name, Types::String
+        attribute? :from_state, Types::String.optional
+        attribute :to_state, Types::String
+      end
+
+      # Health check response from the orchestration API.
+      # Returned by client_health_check.
+      class HealthResponse < Dry::Struct
+        attribute :status, Types::String
+        attribute :timestamp, Types::String
+      end
+    end
+  end
+end

data/lib/tasker_core/types/decision_point_outcome.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require 'dry-types'
+
+module TaskerCore
+  module Types
+    # DecisionPointOutcome - TAS-53 Dynamic Workflow Decision Points
+    #
+    # Represents the outcome of a decision point handler execution.
+    # Decision point handlers make runtime decisions about which workflow steps
+    # to create dynamically based on business logic.
+    #
+    # ## Usage Patterns
+    #
+    # ### No Branches (No additional steps needed)
+    # ```ruby
+    # DecisionPointOutcome.no_branches
+    # ```
+    #
+    # ### Create Specific Steps
+    # ```ruby
+    # # Simple: create one or more steps by name
+    # DecisionPointOutcome.create_steps(["approval_required"])
+    #
+    # # Multiple branches based on condition
+    # if high_value?
+    #   DecisionPointOutcome.create_steps(["manager_approval", "finance_review"])
+    # else
+    #   DecisionPointOutcome.create_steps(["auto_approve"])
+    # end
+    # ```
+    #
+    # ## Integration with Step Handlers
+    #
+    # Decision point handlers should return this outcome in their result:
+    #
+    # ```ruby
+    # def call(context)
+    #   # Business logic to determine which steps to create
+    #   steps_to_create = if context.get_task_field('amount') > 1000
+    #     ['manager_approval', 'finance_review']
+    #   else
+    #     ['auto_approve']
+    #   end
+    #
+    #   outcome = DecisionPointOutcome.create_steps(steps_to_create)
+    #
+    #   StepHandlerCallResult.success(
+    #     result: {
+    #       decision_point_outcome: outcome.to_h
+    #     },
+    #     metadata: {
+    #       operation: 'routing_decision',
+    #       branches_created: steps_to_create.size
+    #     }
+    #   )
+    # end
+    # ```
+    module DecisionPointOutcome
+      module Types
+        include Dry.Types()
+      end
+
+      # NoBranches outcome - no additional steps needed
+      class NoBranches < Dry::Struct
+        # Type discriminator (matches Rust serde tag field)
+        attribute :type, Types::String.default('no_branches')
+
+        # Convert to hash for serialization to Rust
+        # Note: Rust expects lowercase snake_case due to #[serde(rename_all = "snake_case")]
+        def to_h
+          { type: 'no_branches' }
+        end
+
+        # Check if this outcome requires step creation
+        def requires_step_creation?
+          false
+        end
+
+        # Get step names (empty for NoBranches)
+        def step_names
+          []
+        end
+      end
+
+      # CreateSteps outcome - dynamically create specified workflow steps
+      class CreateSteps < Dry::Struct
+        # Type discriminator (matches Rust serde tag field)
+        attribute :type, Types::String.default('create_steps')
+
+        # Array of step names to create
+        attribute :step_names, Types::Array.of(Types::Strict::String).constrained(min_size: 1)
+
+        # Convert to hash for serialization to Rust
+        # Note: Rust expects lowercase snake_case due to #[serde(rename_all = "snake_case")]
+        def to_h
+          {
+            type: 'create_steps',
+            step_names: step_names
+          }
+        end
+
+        # Check if this outcome requires step creation
+        def requires_step_creation?
+          true
+        end
+      end
+
+      # Factory methods for creating outcomes
+      class << self
+        # Create a NoBranches outcome
+        #
+        # Use when the decision point determines that no additional workflow
+        # steps are needed.
+        #
+        # @return [NoBranches] A no-branches outcome instance
+        #
+        # @example
+        #   DecisionPointOutcome.no_branches
+        def no_branches
+          NoBranches.new
+        end
+
+        # Create a CreateSteps outcome with specified step names
+        #
+        # Use when the decision point determines that one or more workflow
+        # steps should be dynamically created.
+        #
+        # @param step_names [Array<String>] Names of steps to create (must be valid step names from template)
+        # @return [CreateSteps] A create-steps outcome instance
+        # @raise [ArgumentError] if step_names is empty
+        #
+        # @example Create single step
+        #   DecisionPointOutcome.create_steps(['approval_required'])
+        #
+        # @example Create multiple steps
+        #   DecisionPointOutcome.create_steps(['manager_approval', 'finance_review'])
+        def create_steps(step_names)
+          raise ArgumentError, 'step_names cannot be empty' if step_names.nil? || step_names.empty?
+
+          CreateSteps.new(step_names: step_names)
+        end
+
+        # Parse a DecisionPointOutcome from a hash
+        #
+        # Used to deserialize outcomes from step handler results.
+        #
+        # @param hash [Hash] The hash representation of an outcome
+        # @return [NoBranches, CreateSteps, nil] The parsed outcome or nil if invalid
+        #
+        # @example
+        #   outcome = DecisionPointOutcome.from_hash({
+        #     type: 'create_steps',
+        #     step_names: ['approval_required']
+        #   })
+        def from_hash(hash)
+          return nil unless hash.is_a?(Hash)
+
+          # Support both symbol and string keys
+          # Note: Rust sends lowercase snake_case due to #[serde(rename_all = "snake_case")]
+          outcome_type = hash[:type] || hash['type']
+
+          case outcome_type
+          when 'no_branches'
+            NoBranches.new
+          when 'create_steps'
+            step_names = hash[:step_names] || hash['step_names']
+            return nil unless step_names.is_a?(Array) && !step_names.empty?
+
+            CreateSteps.new(step_names: step_names)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tasker_core/types/error_types.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  module Types
+    # Standard error type constants for cross-language consistency.
+    #
+    # These error types are used across Ruby, Python, and Rust workers
+    # to categorize step execution failures consistently.
+    #
+    # Note: Values use PascalCase to match StepHandlerCallResult::Error constraints.
+    #
+    # @example Using error types in a handler
+    #   failure(
+    #     message: "Invalid order total",
+    #     error_type: TaskerCore::Types::ErrorTypes::VALIDATION_ERROR,
+    #     retryable: false
+    #   )
+    #
+    # @example Checking if an error type is valid
+    #   TaskerCore::Types::ErrorTypes.valid?('ValidationError')  # => true
+    #   TaskerCore::Types::ErrorTypes.valid?('unknown_type')     # => false
+    module ErrorTypes
+      # Permanent error that should not be retried
+      PERMANENT_ERROR = 'PermanentError'
+
+      # Retryable error that may succeed on subsequent attempts
+      RETRYABLE_ERROR = 'RetryableError'
+
+      # Validation error due to invalid input data
+      VALIDATION_ERROR = 'ValidationError'
+
+      # Unexpected error from unknown causes
+      UNEXPECTED_ERROR = 'UnexpectedError'
+
+      # Step completion error
+      STEP_COMPLETION_ERROR = 'StepCompletionError'
+
+      # All valid error types (matching StepHandlerCallResult::Error constraints)
+      ALL = [
+        PERMANENT_ERROR,
+        RETRYABLE_ERROR,
+        VALIDATION_ERROR,
+        UNEXPECTED_ERROR,
+        STEP_COMPLETION_ERROR
+      ].freeze
+
+      # Check if an error type is a recognized standard type
+      #
+      # @param error_type [String] The error type to check
+      # @return [Boolean] True if the error type is recognized
+      def self.valid?(error_type)
+        ALL.include?(error_type)
+      end
+
+      # Check if an error type is typically retryable
+      #
+      # @param error_type [String] The error type to check
+      # @return [Boolean] True if the error type typically allows retry
+      def self.typically_retryable?(error_type)
+        [RETRYABLE_ERROR, UNEXPECTED_ERROR].include?(error_type)
+      end
+
+      # Check if an error type is typically permanent (not retryable)
+      #
+      # @param error_type [String] The error type to check
+      # @return [Boolean] True if the error type is typically permanent
+      def self.typically_permanent?(error_type)
+        [PERMANENT_ERROR, VALIDATION_ERROR].include?(error_type)
+      end
+    end
+  end
+end