tasker-engine 0.1.0

data/app/models/tasker/task_transition.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module Tasker
+  # TaskTransition represents state transitions for Task entities using Statesman
+  #
+  # This model stores the audit trail of all task state changes, providing
+  # a complete history of task lifecycle events with metadata and timestamps.
+  class TaskTransition < ApplicationRecord
+    # NOTE: We don't include Statesman::Adapters::ActiveRecordTransition
+    # because we're using PostgreSQL JSONB column for metadata
+
+    # Associations
+    belongs_to :task, inverse_of: :task_transitions
+
+    # Validations
+    validates :to_state, inclusion: {
+      in: %w[pending in_progress complete error cancelled resolved_manually],
+      message: 'is not a valid task state'
+    }
+
+    # Validate that the task exists before creating transition
+    validate :task_must_exist
+
+    validates :sort_key, presence: true, uniqueness: { scope: :task_id }
+    # Custom validation for metadata that allows empty hash but not nil
+    validate :metadata_must_be_hash
+
+    # Ensure metadata is always a hash
+    after_initialize :ensure_metadata_hash
+    # Ensure metadata defaults to empty hash if not provided
+    before_validation :ensure_metadata_presence
+
+    # Scopes
+    scope :recent, -> { order(sort_key: :desc) }
+    scope :to_state, ->(state) { where(to_state: state) }
+    scope :with_metadata_key, ->(key) { where('metadata ? :key', key: key.to_s) }
+
+    # Class methods for querying transitions
+    class << self
+      # Find the most recent transition to a specific state
+      #
+      # @param state [String, Symbol] The state to find the most recent transition to
+      # @return [TaskTransition, nil] The most recent transition to the given state
+      def most_recent_to_state(state)
+        to_state(state.to_s).order(sort_key: :desc).first
+      end
+
+      # Find all transitions that occurred within a time range
+      #
+      # @param start_time [Time] The start of the time range
+      # @param end_time [Time] The end of the time range
+      # @return [ActiveRecord::Relation] Transitions within the time range
+      def in_time_range(start_time, end_time)
+        where(created_at: start_time..end_time)
+      end
+
+      # Find transitions with specific metadata values
+      #
+      # @param key [String, Symbol] The metadata key to search for
+      # @param value [Object] The value to match
+      # @return [ActiveRecord::Relation] Transitions with matching metadata
+      def with_metadata_value(key, value)
+        where('metadata->:key = :value', key: key.to_s, value: value.to_json.delete('"'))
+      end
+
+      # Get transition statistics for analytics
+      #
+      # @return [Hash] Statistics about transitions
+      def statistics
+        {
+          total_transitions: count,
+          states: group(:to_state).count,
+          recent_activity: where(created_at: 24.hours.ago..Time.current).count,
+          average_time_between_transitions: average_time_between_transitions
+        }
+      end
+
+      private
+
+      # Calculate average time between transitions
+      #
+      # @return [Float, nil] Average seconds between transitions
+      def average_time_between_transitions
+        transitions = order(:created_at).pluck(:created_at)
+        return nil if transitions.size < 2
+
+        total_time = 0
+        (1...transitions.size).each do |i|
+          total_time += (transitions[i] - transitions[i - 1])
+        end
+
+        total_time / (transitions.size - 1)
+      end
+    end
+
+    # Instance methods
+
+    # Get the duration since the previous transition
+    #
+    # @return [Float, nil] Duration in seconds since previous transition
+    def duration_since_previous
+      previous_transition = self.class.where(task_id: task_id)
+                                .where(sort_key: ...sort_key)
+                                .order(sort_key: :desc)
+                                .first
+
+      return nil unless previous_transition
+
+      created_at - previous_transition.created_at
+    end
+
+    # Check if this transition represents an error state
+    #
+    # @return [Boolean] True if transitioning to an error state
+    def error_transition?
+      to_state == 'error'
+    end
+
+    # Check if this transition represents completion
+    #
+    # @return [Boolean] True if transitioning to a completion state
+    def completion_transition?
+      %w[complete resolved_manually].include?(to_state)
+    end
+
+    # Check if this transition represents cancellation
+    #
+    # @return [Boolean] True if transitioning to cancelled state
+    def cancellation_transition?
+      to_state == 'cancelled'
+    end
+
+    # Get human-readable description of the transition
+    #
+    # @return [String] Description of what this transition represents
+    def description
+      case to_state
+      when 'pending'
+        'Task initialized and ready for processing'
+      when 'in_progress'
+        'Task execution started'
+      when 'complete'
+        'Task completed successfully'
+      when 'error'
+        'Task encountered an error'
+      when 'cancelled'
+        'Task was cancelled'
+      when 'resolved_manually'
+        'Task was manually resolved'
+      else
+        "Task transitioned to #{to_state}"
+      end
+    end
+
+    # Get formatted metadata for display
+    #
+    # @return [Hash] Formatted metadata with additional computed fields
+    def formatted_metadata
+      base_metadata = metadata.dup
+
+      # Add computed fields
+      base_metadata['duration_since_previous'] = duration_since_previous
+      base_metadata['transition_description'] = description
+      base_metadata['transition_timestamp'] = created_at.iso8601
+
+      base_metadata
+    end
+
+    # Check if transition has specific metadata
+    #
+    # @param key [String, Symbol] The metadata key to check for
+    # @return [Boolean] True if the metadata contains the key
+    def has_metadata?(key)
+      metadata.key?(key.to_s)
+    end
+
+    # Get metadata value with default
+    #
+    # @param key [String, Symbol] The metadata key
+    # @param default [Object] Default value if key not found
+    # @return [Object] The metadata value or default
+    def get_metadata(key, default = nil)
+      metadata.fetch(key.to_s, default)
+    end
+
+    # Set metadata value
+    #
+    # @param key [String, Symbol] The metadata key
+    # @param value [Object] The value to set
+    # @return [Object] The set value
+    def set_metadata(key, value)
+      self.metadata = metadata.merge(key.to_s => value)
+      value
+    end
+
+    private
+
+    # Ensure metadata is always initialized as a hash
+    #
+    # @return [void]
+    def ensure_metadata_hash
+      self.metadata ||= {}
+    end
+
+    # Ensure metadata is present for validation
+    #
+    # @return [void]
+    def ensure_metadata_presence
+      self.metadata = {} if metadata.blank?
+    end
+
+    # Custom validation for metadata
+    #
+    # @return [void]
+    def metadata_must_be_hash
+      if metadata.nil?
+        self.metadata = {}
+      elsif !metadata.is_a?(Hash)
+        errors.add(:metadata, 'must be a hash')
+      end
+    end
+
+    # Validate that the task exists
+    #
+    # @return [void]
+    def task_must_exist
+      return if task_id.blank?
+
+      errors.add(:task, 'must exist before creating transition') unless Tasker::Task.exists?(task_id: task_id)
+    rescue ActiveRecord::StatementInvalid => e
+      # Handle cases where the table might not exist (e.g., during migrations)
+      Rails.logger.warn { "Could not validate task existence: #{e.message}" }
+    end
+  end
+end

data/app/models/tasker/workflow_step.rb

@@ -0,0 +1,461 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative '../../../lib/tasker/state_machine/step_state_machine'
+
+module Tasker
+  class WorkflowStep < ApplicationRecord
+    PROVIDES_EDGE_NAME = 'provides'
+
+    self.primary_key = :workflow_step_id
+    belongs_to :task
+    belongs_to :named_step
+    # belongs_to :depends_on_step, class_name: 'WorkflowStep', optional: true
+    has_many  :incoming_edges,
+              class_name: 'WorkflowStepEdge',
+              foreign_key: :to_step_id,
+              dependent: :destroy,
+              inverse_of: :to_step
+    has_many  :outgoing_edges,
+              class_name: 'WorkflowStepEdge',
+              foreign_key:
+              :from_step_id,
+              dependent: :destroy,
+              inverse_of: :from_step
+    has_many :parents, through: :incoming_edges, source: :from_step
+    has_many :children, through: :outgoing_edges, source: :to_step
+    has_many :siblings, through: :outgoing_edges, source: :from_step
+    has_many :workflow_step_transitions, inverse_of: :workflow_step, dependent: :destroy
+
+    validates :named_step_id, uniqueness: { scope: :task_id, message: 'must be unique within the same task' }
+    validate :name_uniqueness_within_task
+
+    delegate :name, to: :named_step
+
+    has_one :step_dag_relationship, class_name: 'Tasker::StepDagRelationship', primary_key: :workflow_step_id
+    # NOTE: step_readiness_status is now accessed via function-based approach, not ActiveRecord association
+
+    # Optimized scopes for efficient querying using state machine transitions
+    scope :completed, lambda {
+      joins(:workflow_step_transitions)
+        .where(
+          workflow_step_transitions: {
+            most_recent: true,
+            to_state: [
+              Constants::WorkflowStepStatuses::COMPLETE,
+              Constants::WorkflowStepStatuses::RESOLVED_MANUALLY
+            ]
+          }
+        )
+    }
+
+    scope :failed, lambda {
+      joins(:workflow_step_transitions)
+        .where(
+          workflow_step_transitions: {
+            most_recent: true,
+            to_state: Constants::WorkflowStepStatuses::ERROR
+          }
+        )
+    }
+
+    scope :pending, lambda {
+      # Include steps with no transitions (initial state) AND steps with pending/in_progress transitions
+      where.missing(:workflow_step_transitions)
+           .or(
+             joins(:workflow_step_transitions)
+               .where(
+                 workflow_step_transitions: {
+                   most_recent: true,
+                   to_state: [
+                     Constants::WorkflowStepStatuses::PENDING,
+                     Constants::WorkflowStepStatuses::IN_PROGRESS
+                   ]
+                 }
+               )
+           )
+    }
+
+    scope :for_task, lambda { |task|
+      where(task_id: task.task_id)
+    }
+
+    # Scopes workflow steps by their current state using state machine transitions
+    #
+    # @scope class
+    # @param state [String, nil] The state to filter by. If nil, returns all steps with current state information
+    # @return [ActiveRecord::Relation] Steps with current state, optionally filtered by specific state
+    scope :by_current_state, lambda { |state = nil|
+      relation = joins(<<-SQL.squish)
+        INNER JOIN (
+          SELECT DISTINCT ON (workflow_step_id) workflow_step_id, to_state
+          FROM tasker_workflow_step_transitions
+          WHERE most_recent = true
+          ORDER BY workflow_step_id, sort_key DESC
+        ) current_transitions ON current_transitions.workflow_step_id = tasker_workflow_steps.workflow_step_id
+      SQL
+
+      if state.present?
+        relation.where(current_transitions: { to_state: state })
+      else
+        relation
+      end
+    }
+
+    # Scopes workflow steps completed since a specific time
+    #
+    # @scope class
+    # @param since_time [Time] The earliest completion time to include
+    # @return [ActiveRecord::Relation] Steps completed since the specified time
+    scope :completed_since, lambda { |since_time|
+      joins(:workflow_step_transitions)
+        .where('tasker_workflow_step_transitions.most_recent = ? AND tasker_workflow_step_transitions.to_state = ?', true, 'complete')
+        .where('tasker_workflow_step_transitions.created_at > ?', since_time)
+    }
+
+    # Scopes workflow steps that failed since a specific time
+    #
+    # @scope class
+    # @param since_time [Time] The earliest failure time to include
+    # @return [ActiveRecord::Relation] Steps that failed since the specified time
+    scope :failed_since, lambda { |since_time|
+      joins(:workflow_step_transitions)
+        .where('tasker_workflow_step_transitions.most_recent = ? AND tasker_workflow_step_transitions.to_state = ?', true, 'error')
+        .where('tasker_workflow_step_transitions.created_at > ?', since_time)
+    }
+
+    # Scopes workflow steps for tasks created since a specific time
+    #
+    # @scope class
+    # @param since_time [Time] The earliest task creation time to include
+    # @return [ActiveRecord::Relation] Steps for tasks created since the specified time
+    scope :for_tasks_since, lambda { |since_time|
+      joins(:task).where('tasker_tasks.created_at > ?', since_time)
+    }
+
+    # Efficient method to get task completion statistics using ActiveRecord scopes
+    # This avoids the N+1 query problem while working with the state machine system
+    #
+    # @param task [Task] The task to analyze
+    # @return [Hash] Hash with completion statistics and latest completion time
+    def self.task_completion_stats(task)
+      # Use efficient ActiveRecord queries with the state machine
+      task_steps = for_task(task)
+
+      # Get completion statistics with optimized queries
+      total_steps = task_steps.count
+      completed_steps = task_steps.completed
+      failed_steps = task_steps.failed
+
+      # Calculate counts
+      completed_count = completed_steps.count
+      failed_count = failed_steps.count
+
+      # For pending count, calculate as total minus completed and failed
+      # This handles the case where new steps don't have transitions yet
+      pending_count = total_steps - completed_count - failed_count
+
+      # Get latest completion time from completed steps
+      latest_completion_time = completed_steps.maximum(:processed_at)
+
+      {
+        total_steps: total_steps,
+        completed_steps: completed_count,
+        failed_steps: failed_count,
+        pending_steps: pending_count,
+        latest_completion_time: latest_completion_time,
+        all_complete: completed_count == total_steps && total_steps.positive?
+      }
+    end
+
+    # State machine integration
+    def state_machine
+      @state_machine ||= Tasker::StateMachine::StepStateMachine.new(
+        self,
+        transition_class: Tasker::WorkflowStepTransition,
+        association_name: :workflow_step_transitions
+      )
+    end
+
+    # Status is now entirely managed by the state machine
+    def status
+      if new_record?
+        # For new records, return the initial state
+        Tasker::Constants::WorkflowStepStatuses::PENDING
+      else
+        # For persisted records, use state machine
+        state_machine.current_state
+      end
+    end
+
+    # Finds a WorkflowStep with the given name by traversing the DAG efficiently
+    # @param steps [Array<WorkflowStep>] Collection of steps to search through
+    # @param name [String] Name of the step to find
+    # @return [WorkflowStep, nil] The first matching step found or nil if none exists
+    def self.find_step_by_name(steps, name)
+      StepFinder.find_by_name(steps, name)
+    end
+
+    # Service class to find steps by name
+    # Reduces complexity by organizing step search logic
+    class StepFinder
+      class << self
+        # Find step by name in provided collection or task hierarchy
+        #
+        # @param steps [Array<WorkflowStep>] Collection of steps to search through
+        # @param name [String] Name of the step to find
+        # @return [WorkflowStep, nil] The first matching step found or nil if none exists
+        def find_by_name(steps, name)
+          return nil if steps.empty? || name.nil?
+
+          # First check direct match in provided steps
+          direct_match = find_direct_match(steps, name)
+          return direct_match if direct_match
+
+          # Fall back to task-wide search using DAG relationships
+          find_in_task_hierarchy(steps, name)
+        end
+
+        private
+
+        # Find direct match in provided steps
+        #
+        # @param steps [Array<WorkflowStep>] Collection of steps
+        # @param name [String] Name to search for
+        # @return [WorkflowStep, nil] Matching step or nil
+        def find_direct_match(steps, name)
+          steps.find { |step| step.name == name }
+        end
+
+        # Find step in task hierarchy using efficient DAG traversal
+        #
+        # @param steps [Array<WorkflowStep>] Collection of steps to get task context
+        # @param name [String] Name to search for
+        # @return [WorkflowStep, nil] Matching step or nil
+        def find_in_task_hierarchy(steps, name)
+          task_ids = extract_task_ids(steps)
+
+          task_ids.each do |task_id|
+            found_step = find_in_single_task(task_id, name)
+            return found_step if found_step
+          end
+
+          nil
+        end
+
+        # Extract unique task IDs from steps
+        #
+        # @param steps [Array<WorkflowStep>] Collection of steps
+        # @return [Array<Integer>] Unique task IDs
+        def extract_task_ids(steps)
+          steps.map(&:task_id).uniq
+        end
+
+        # Find step by name in a single task
+        #
+        # @param task_id [Integer] Task ID to search in
+        # @param name [String] Name to search for
+        # @return [WorkflowStep, nil] Matching step or nil
+        def find_in_single_task(task_id, name)
+          # Get all workflow steps for this task with their DAG relationships
+          all_task_steps = WorkflowStep.joins(:named_step)
+                                       .includes(:step_dag_relationship)
+                                       .where(task_id: task_id)
+
+          # Find step by name using simple lookup instead of recursive traversal
+          all_task_steps.joins(:named_step)
+                        .find_by(named_steps: { name: name })
+        end
+      end
+    end
+
+    def self.get_steps_for_task(task, templates)
+      named_steps = NamedStep.create_named_steps_from_templates(templates)
+      steps =
+        templates.map do |template|
+          named_step = named_steps.find { |ns| template.name == ns.name }
+          NamedTasksNamedStep.associate_named_step_with_named_task(task.named_task, template, named_step)
+          step = where(task_id: task.task_id, named_step_id: named_step.named_step_id).first
+          step ||= build_default_step!(task, template, named_step)
+          step
+        end
+      set_up_dependent_steps(steps, templates)
+    end
+
+    def self.set_up_dependent_steps(steps, templates)
+      templates.each do |template|
+        next if template.all_dependencies.empty?
+
+        dependent_step = steps.find { |step| step.name == template.name }
+        template.all_dependencies.each do |dependency|
+          provider_step = steps.find { |step| step.name == dependency }
+          unless provider_step.outgoing_edges.exists?(to_step: dependent_step)
+            provider_step.add_provides_edge!(dependent_step)
+          end
+        end
+      end
+      steps
+    end
+
+    def self.build_default_step!(task, template, named_step)
+      # Create the step first without status
+      step_attributes = {
+        task_id: task.task_id,
+        named_step_id: named_step.named_step_id,
+        retryable: template.default_retryable,
+        retry_limit: template.default_retry_limit,
+        skippable: template.skippable,
+        in_process: false,
+        inputs: task.context,
+        processed: false,
+        attempts: 0,
+        results: {}
+      }
+
+      step = new(step_attributes)
+      step.save!
+
+      # REMOVED: Automatic state machine initialization to prevent duplicate key violations
+      # The state machine will initialize naturally when accessed, and factories may
+      # have already created transitions through their own setup
+      # step.state_machine.initialize_state_machine!
+
+      step
+    end
+
+    def self.get_viable_steps(task, sequence)
+      # Get step IDs from sequence
+      step_ids = sequence.steps.map(&:workflow_step_id)
+
+      # Use function-based approach for high-performance readiness checking
+      ready_statuses = StepReadinessStatus.for_task(task.task_id, step_ids)
+      ready_step_ids = ready_statuses.select(&:ready_for_execution).map(&:workflow_step_id)
+
+      # Return WorkflowStep objects for ready steps
+      WorkflowStep.where(workflow_step_id: ready_step_ids)
+                  .includes(:named_step)
+    end
+
+    def add_provides_edge!(to_step)
+      outgoing_edges.create!(to_step: to_step, name: PROVIDES_EDGE_NAME)
+    end
+
+    # Helper method to get step readiness status using function-based approach
+    def step_readiness_status
+      @step_readiness_status ||= StepReadinessStatus.for_task(task_id, [workflow_step_id]).first
+    end
+
+    def complete?
+      # Use function-based approach for consistent state checking
+      step_readiness_status&.current_state&.in?([
+                                                  Constants::WorkflowStepStatuses::COMPLETE,
+                                                  Constants::WorkflowStepStatuses::RESOLVED_MANUALLY
+                                                ]) || false
+    end
+
+    def in_progress?
+      # Use function-based approach for consistent state checking
+      step_readiness_status&.current_state == Constants::WorkflowStepStatuses::IN_PROGRESS
+    end
+
+    def pending?
+      # Use function-based approach for consistent state checking
+      step_readiness_status&.current_state == Constants::WorkflowStepStatuses::PENDING
+    end
+
+    def in_error?
+      # Use function-based approach for consistent state checking
+      step_readiness_status&.current_state == Constants::WorkflowStepStatuses::ERROR
+    end
+
+    def cancelled?
+      # Use function-based approach for consistent state checking
+      step_readiness_status&.current_state == Constants::WorkflowStepStatuses::CANCELLED
+    end
+
+    def ready_status?
+      # Use function-based approach for efficient ready status checking
+      Constants::UNREADY_WORKFLOW_STEP_STATUSES.exclude?(
+        step_readiness_status&.current_state || Constants::WorkflowStepStatuses::PENDING
+      )
+    end
+
+    def ready?
+      # Use function-based approach's comprehensive readiness calculation
+      step_readiness_status&.ready_for_execution || false
+    end
+
+    # Function-based predicate methods
+    def dependencies_satisfied?
+      # Use function-based approach's pre-calculated dependency analysis
+      step_readiness_status&.dependencies_satisfied || false
+    end
+
+    def retry_eligible?
+      # Use function-based approach's retry/backoff calculation
+      step_readiness_status&.retry_eligible || false
+    end
+
+    def has_retry_attempts?
+      # Check if step has made retry attempts
+      (step_readiness_status&.attempts || 0).positive?
+    end
+
+    def retry_exhausted?
+      # Check if step has exhausted retry attempts
+      return false unless step_readiness_status
+
+      attempts = step_readiness_status.attempts || 0
+      retry_limit = step_readiness_status.retry_limit || 3
+      attempts >= retry_limit
+    end
+
+    def waiting_for_backoff?
+      # Check if step is waiting for backoff period to expire
+      return false unless step_readiness_status&.next_retry_at
+
+      step_readiness_status.next_retry_at > Time.current
+    end
+
+    def can_retry_now?
+      # Comprehensive check if step can be retried right now
+      return false unless in_error?
+      return false unless retry_eligible?
+      return false if waiting_for_backoff?
+
+      true
+    end
+
+    def root_step?
+      # Check if this is a root step (no dependencies)
+      (step_readiness_status&.total_parents || 0).zero?
+    end
+
+    def leaf_step?
+      # Check if this is a leaf step using DAG relationship view
+      step_dag_relationship&.child_count&.zero?
+    end
+
+    def reload
+      # Override reload to ensure step readiness status is refreshed
+      super.tap do
+        @step_readiness_status = nil # Reset cached readiness status
+      end
+    end
+
+    private
+
+    # Custom validation to ensure step names are unique within a task
+    def name_uniqueness_within_task
+      return unless named_step && task
+
+      # Find all steps within the same task that have the same name
+      matching_steps = self.class.where(task_id: task_id)
+                           .joins(:named_step)
+                           .where(named_step: { name: name })
+                           .where.not(workflow_step_id: workflow_step_id) # Exclude self when updating
+
+      errors.add(:base, "Step name '#{name}' must be unique within the same task") if matching_steps.exists?
+    end
+  end
+end