phronomy 0.14.0 → 0.15.0

data/lib/phronomy/engine/fsm_session.rb

@@ -3,39 +3,33 @@
 module Phronomy
   # Event-driven execution wrapper for a single FSM session.
   #
-  # Used by both WorkflowRunner (for Workflow) and Agent::InvocationSession
-  # (for Agent invoke). Not Workflow-specific.
-  #
-  # Created by a runner and registered with EventLoop. All public methods
-  # are called from the EventLoop thread — FSMSession is NOT thread-safe and must
-  # not be accessed concurrently from multiple threads.
-  #
+  # All public methods are called from the Runtime-owned EventLoop thread.
+  # FSMSession owns FSM execution only; it does not own external Task handles,
+  # activity tokens, callback correlation, or domain-specific stale-event policy.
   class FSMSession
     FINISH = WorkflowRunner::FINISH
 
-    # @return [String] workflow thread_id (matches WorkflowContext#thread_id)
-    attr_reader :id
-
-    # @param id                  [String]
-    # @param context             [Object]        includes Phronomy::WorkflowContext
-    # @param entry_point         [Symbol]        initial state name
-    # @param entry_actions       [Hash]          { state_name => [callable, ...] }
-    # @param auto_state_set      [Hash]          { state_name => true }
-    # @param declared_states     [Array<Symbol>] all action state names
-    # @param wait_state_names    [Array<Symbol>]
-    # @param external_events     [Hash]          { event_name => [{from:, to:, guard:}] }
-    # @param phase_machine_class [Class]         state_machines-backed phase tracker class
-    # @param recursion_limit     [Integer]
-    # @param action_timeouts     [Hash]          { state_name => seconds }
-    # @param resume_event        [Symbol, nil]   external event to fire when resuming
-    # @param resume_phase        [Symbol, nil]   wait state name to resume from
-    # @api private
-    def initialize(id:, context:, entry_point:, entry_actions:, auto_state_set:,
-      declared_states:, wait_state_names:, external_events:, phase_machine_class:,
-      recursion_limit:, event_loop:, timer_queue_provider:, action_timeouts: {},
-      resume_event: nil, resume_phase: nil)
+    attr_reader :id, :context
+
+    def initialize(
+      id:,
+      context:,
+      entry_point:,
+      entry_actions:,
+      auto_state_set:,
+      declared_states:,
+      wait_state_names:,
+      external_events:,
+      phase_machine_class:,
+      recursion_limit:,
+      event_loop:,
+      resume_event: nil,
+      resume_phase: nil,
+      stable_observer: nil
+    )
       @id = id
       @ctx = context
+      @context = context
       @entry_point = entry_point
       @entry_actions = entry_actions
       @auto_state_set = auto_state_set
@@ -44,155 +38,145 @@ module Phronomy
       @external_events = external_events
       @phase_machine_class = phase_machine_class
       @recursion_limit = recursion_limit
-      @action_timeouts = action_timeouts
       @event_loop = event_loop
-      @timer_queue_provider = timer_queue_provider
       @resume_event = resume_event
       @resume_phase = resume_phase
+      @stable_observer = stable_observer
       @step = 0
       @done = false
       @current_state = nil
       @tracker = nil
     end
 
-    # Begins workflow execution. Called by EventLoop on :start event.
     def start
       if @resume_event
-        # Resume from wait state: position tracker at the wait state, then fire the
-        # external event. state_machines fires before_transition (exit) and
-        # after_transition (entry) callbacks, so both actions execute here.
         @current_state = @resume_phase
         @tracker = build_tracker(@current_state)
         @tracker.context = @ctx
-        @tracker.session_id = @id if @tracker.respond_to?(:session_id=)
-        fire_and_advance!(@resume_event)
+        fire_and_advance!(
+          Phronomy::Event.new(
+            type: @resume_event,
+            target_id: @id,
+            payload: nil
+          )
+        )
       else
-        # Fresh start: state_machines does not fire callbacks on initialization,
-        # so we invoke the entry action for the initial state manually.
         @current_state = @entry_point
         @tracker = build_tracker(@current_state)
         @tracker.context = @ctx
-        @tracker.session_id = @id if @tracker.respond_to?(:session_id=)
-        (@entry_actions[@current_state] || []).each do |c|
-          result = c.call(@ctx)
-          if result.is_a?(Phronomy::Task)
-            # Awaitable action: resume via on_complete without blocking EventLoop.
-            @tracker.async_pending = true
-            session_id = @id
-            current_state_name = @current_state
-            timeout_secs = @action_timeouts[current_state_name]
-            if timeout_secs
-              @timer_queue_provider.call.schedule(seconds: timeout_secs) do
-                next if result.done?
-
-                @event_loop.post(
-                  Event.new(
-                    type: :error,
-                    target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
-                    payload: {session_id: session_id, result: Phronomy::ActionTimeoutError.new(
-                      "Action in state #{current_state_name.inspect} timed out after #{timeout_secs}s"
-                    )}
-                  )
-                )
-              end
-            end
-            result.on_complete do |task_result, error|
-              if error
-                @event_loop.post(Event.new(type: :error, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: session_id, result: error}))
-                next
-              end
-              if _fsm_context?(task_result)
-                @event_loop.post(Event.new(type: :action_completed, target_id: session_id, payload: task_result))
-              else
-                @event_loop.post(Event.new(type: :state_completed, target_id: session_id, payload: nil))
-              end
-            end
-            break # Only one async action at a time per state
-          elsif _fsm_context?(result)
-            @ctx = result
-          end
-        end
+        run_initial_entry_actions!
         @tracker.context = @ctx
-        advance_or_halt unless @tracker.async_pending
+        advance_or_halt
       end
-    rescue => e
-      finish_with_error(e)
+    rescue => error
+      finish_with_error(error)
     end
 
-    # Processes an event dispatched from EventLoop.
-    # Called for :state_completed, :action_completed, and all user-defined external events.
-    #
-    # @param event [Phronomy::Event]
-    # @api private
     def handle(event)
       return if @done
 
-      if event.type == :action_completed
-        # An awaitable entry action completed: update context and advance.
-        @ctx = event.payload if _fsm_context?(event.payload)
-        @tracker.context = @ctx
-        @tracker.async_pending = false  # Reset flag set by start or fire_and_advance!
-        advance_or_halt
+      context_disposition = apply_context_event(event)
+      return if context_disposition == :consume
+
+      if context_disposition &&
+          !has_external_event_from?(@current_state, event.type)
         return
       end
 
-      # When :state_completed arrives from an async Task (non-WorkflowContext result),
-      # async_pending may still be true from the spawn. Clear it before advancing.
-      @tracker.async_pending = false if event.type == :state_completed && @tracker.async_pending
-
-      fire_and_advance!(event.type)
-    rescue => e
-      finish_with_error(e)
+      fire_and_advance!(event)
+    rescue => error
+      finish_with_error(error)
     end
 
     private
 
-    # Fires event_name on the phase tracker, updates @current_state, then
-    # calls advance_or_halt to decide what to do next.
-    def fire_and_advance!(event_name)
+    def run_initial_entry_actions!
+      Array(@entry_actions[@current_state]).each do |callable|
+        result = callable.call(@ctx)
+        apply_synchronous_action_result!(result, @current_state)
+      end
+    end
+
+    def apply_synchronous_action_result!(result, state_name)
+      if result.is_a?(Phronomy::Task)
+        raise Phronomy::InvalidAsyncEntryActionError,
+          "Entry action for state #{state_name.inspect} returned Phronomy::Task. " \
+          "Start the asynchronous operation, register its callback/listener, " \
+          "and return the WorkflowContext or nil."
+      end
+
+      if _fsm_context?(result)
+        @ctx = result
+        @context = result
+      end
+    end
+
+    def apply_context_event(event)
+      return false unless @ctx.respond_to?(:handle_fsm_event)
+
+      result = @ctx.handle_fsm_event(event)
+      return :consume if result == :consume
+
+      if _fsm_context?(result)
+        @ctx = result
+        @context = result
+        @tracker.context = @ctx
+        true
+      else
+        !!result
+      end
+    end
+
+    def fire_and_advance!(event)
       if @step >= @recursion_limit
         raise Phronomy::RecursionLimitError,
           "Recursion limit (#{@recursion_limit}) exceeded"
       end
 
-      fire_event!(@tracker, event_name, @current_state)
+      @tracker.context = @ctx
+      clear_selected_transition!
+      @tracker.current_event = event if @tracker.respond_to?(:current_event=)
+      transitioned = fire_event!(@tracker, event.type, @current_state)
+      return unless transitioned
+
       @ctx = @tracker.context
-      next_phase = @tracker.phase.to_sym
-      # When next_phase == @current_state, no transition matched → treat as terminal.
-      @current_state = (next_phase == @current_state) ? FINISH : next_phase
+      @context = @ctx
+      @current_state = @tracker.phase.to_sym
       @step += 1
+      advance_or_halt
+    ensure
+      @tracker.current_event = nil if @tracker&.respond_to?(:current_event=)
+      clear_selected_transition!
+    end
 
-      # If an entry action returned a Task, the after_transition callback set
-      # async_pending = true and spawned a thread. Skip advance_or_halt — the
-      # background thread will post :action_completed or :state_completed.
-      if @tracker.async_pending
-        @tracker.async_pending = false
-        return
-      end
+    def clear_selected_transition!
+      return unless @tracker
 
-      advance_or_halt
+      if @tracker.respond_to?(:selected_transition_action=)
+        @tracker.selected_transition_action = nil
+      end
+      if @tracker.respond_to?(:selected_transition_metadata=)
+        @tracker.selected_transition_metadata = nil
+      end
     end
 
-    # Determines the next action after the FSM has entered @current_state.
     def advance_or_halt
       return finish! if @current_state == FINISH
 
+      notify_stable_state!
+
       if @wait_state_names.include?(@current_state)
-        return halt!
+        halt!
+        return
       end
 
       if @auto_state_set.key?(@current_state)
-        @event_loop.post(Event.new(type: :state_completed, target_id: @id, payload: nil))
+        post_session_event(:state_completed)
         return
       end
 
-      if has_external_event_from?(@current_state)
-        # Async IO pattern: the entry action spawned an IO thread that will post
-        # an external event back. Stay registered; do nothing here.
-        return
-      end
+      return if has_external_event_from?(@current_state)
 
-      # No transition declared — validate the state is known, then treat as terminal.
       unless @declared_states.include?(@current_state)
         raise ArgumentError, "State #{@current_state.inspect} is not defined"
       end
@@ -200,52 +184,106 @@ module Phronomy
       finish!
     end
 
+    def notify_stable_state!
+      return unless @stable_observer
+
+      @stable_observer.call(
+        {
+          state: @current_state,
+          context: @ctx
+        }
+      )
+    end
+
+    def post_session_event(type, payload = nil)
+      event = Phronomy::Event.new(
+        type: type,
+        target_id: @id,
+        payload: payload
+      )
+      accepted =
+        if @event_loop.respond_to?(:post_to_session)
+          @event_loop.post_to_session(event)
+        else
+          @event_loop.post(event)
+        end
+      return if accepted
+
+      raise Phronomy::RuntimeShutdownError,
+        "EventLoop rejected #{type.inspect} for FSMSession #{@id}"
+    end
+
     def finish!
+      return if @done
+
       @done = true
       @ctx.set_graph_metadata(thread_id: @id, phase: :__end__)
-      @event_loop.post(Event.new(type: :finished, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: @id, result: @ctx}))
+      post_terminal_event(:finished, @ctx)
     end
 
     def halt!
+      return if @done
+
       @done = true
       @ctx.set_graph_metadata(thread_id: @id, phase: @current_state)
-      @event_loop.post(Event.new(type: :halted, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: @id, result: @ctx}))
+      post_terminal_event(:halted, @ctx)
     end
 
-    def finish_with_error(err)
+    def finish_with_error(error)
+      return if @done
+
       @done = true
-      @event_loop.post(Event.new(type: :error, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: @id, result: err}))
+      post_terminal_event(:error, error)
+    end
+
+    def post_terminal_event(type, result)
+      accepted = @event_loop.post(
+        Phronomy::Event.new(
+          type: type,
+          target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
+          payload: {session_id: @id, result: result}
+        )
+      )
+      return if accepted
+
+      Phronomy.configuration.logger&.warn(
+        "[Phronomy::FSMSession] EventLoop rejected terminal event " \
+        "#{type.inspect} for #{@id}"
+      )
     end
 
     def fire_event!(tracker, event_name, from_state)
-      return if tracker.send(event_name)
+      unless tracker.respond_to?(event_name)
+        raise ArgumentError,
+          "Unknown FSM event #{event_name.inspect} for state #{from_state.inspect}"
+      end
+
+      return true if tracker.public_send(event_name)
+
+      # A declared external event whose guards all reject is a valid no-op.
+      # Applications use this to reject stale or unrelated correlated events.
+      return false if has_external_event_from?(from_state, event_name)
 
       raise ArgumentError,
         "Transition from #{from_state.inspect} via event #{event_name.inspect} failed. " \
-        "Ensure at least one guard matches or add a fallback (no-guard) transition."
+        "The event is not declared for the current state."
     end
 
-    def has_external_event_from?(state)
-      @external_events.any? { |_, transitions| transitions.any? { |t| t[:from] == state } }
+    def has_external_event_from?(state, event_name = nil)
+      events = event_name ? {event_name => @external_events[event_name]} : @external_events
+      events.any? do |_name, transitions|
+        Array(transitions).any? { |transition| transition[:from] == state }
+      end
     end
 
     def build_tracker(from_state)
       machine = @phase_machine_class.new
       machine.instance_variable_set(:@phase, from_state.to_s)
-      machine.event_loop = @event_loop if machine.respond_to?(:event_loop=)
-      if machine.respond_to?(:timer_queue_provider=)
-        machine.timer_queue_provider = @timer_queue_provider
-      end
       machine
     end
 
-    # Returns true when +obj+ is an FSM execution context (responds to
-    # +set_graph_metadata+). Used to distinguish context objects from other
-    # Task return values (strings, hashes, etc.) without hard-coding a specific
-    # class. Both WorkflowContext and Agent::InvocationContext qualify.
-    # @api private
-    def _fsm_context?(obj)
-      obj.respond_to?(:set_graph_metadata)
+    def _fsm_context?(object)
+      object.respond_to?(:set_graph_metadata)
     end
   end
 end

data/lib/phronomy/engine/task.rb

@@ -212,17 +212,12 @@ module Phronomy
     # If this task fails or is cancelled, the mapped task also fails/is
     # cancelled with the same error.  The block is never called in error cases.
     #
-    # The primary use-case is transforming an agent result into a
-    # {WorkflowContext} so that a Workflow entry action can return a Task
-    # whose value is picked up by {FSMSession} via the existing
-    # +:action_completed+ path:
+    # The transformation runs from the source Task's completion callback.
+    # It is a generic value-composition API; Workflow entry actions do not await
+    # either the source Task or the mapped Task.
     #
-    # @example Returning agent output into a Workflow state field
-    #   entry :translate, ->(ctx) {
-    #     TranslationAgent.new.invoke_async(ctx.query).map do |result|
-    #       ctx.merge(answer: result[:output])   # returns WorkflowContext
-    #     end
-    #   }
+    # @example Transforming an Agent result outside a Workflow entry action
+    #   output_task = agent.invoke_async("hello").map { |result| result[:output] }
     #
     # @yield  [value] the completed value of this task
     # @yieldreturn [Object] the value for the mapped task

data/lib/phronomy/event.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Immutable event struct used for inter-FSM communication via EventLoop.
+  # Immutable event used for EventLoop communication.
   #
-  # @param type      [Symbol]  event identifier (:start, :state_completed,
-  #                            :finished, :halted, :error, or any user-defined name)
-  # @param target_id [String]  FSMSession identifier — matches WorkflowContext#thread_id
-  # @param payload   [Object]  optional data attached to the event:
-  #                            - final/halted context for :finished/:halted
-  #                            - Exception for :error
-  #                            - nil for :start / :state_completed
+  # User-defined Workflow events carry application-owned payloads unchanged.
+  # Correlation identifiers, stale-event decisions, and domain interpretation
+  # remain application concerns.
+  #
+  # @param type      [Symbol] event identifier
+  # @param target_id [String] FSMSession identifier
+  # @param payload   [Object] optional event data
   Event = Data.define(:type, :target_id, :payload)
 end