phronomy 0.13.0 → 0.15.0

data/lib/phronomy/engine/fsm_session.rb

@@ -3,38 +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:, 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
@@ -43,153 +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
       @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
-              Phronomy::Runtime.instance.timer_queue.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
@@ -197,33 +184,96 @@ 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)
@@ -232,17 +282,8 @@ module Phronomy
       machine
     end
 
-    def event_loop
-      Phronomy::EventLoop.instance
-    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/runtime/deterministic_scheduler.rb

@@ -38,7 +38,7 @@ module Phronomy
     class DeterministicScheduler < Scheduler
       # Scheduler-aware signal for cooperative suspension.
       #
-      # Used by {ConcurrencyGate} and {TaskGroup} to suspend a Fiber until a
+      # Used by {TaskGroup} to suspend a Fiber until a
       # slot or condition becomes available, without blocking the OS thread.
       # All methods must be called from within a {DeterministicScheduler} tick.
       # @api private

data/lib/phronomy/engine/runtime/shutdown_result.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Immutable result returned by {Runtime#shutdown}.
+    #
+    # +runtime_outcome+ records whether execution remained healthy. It is
+    # intentionally independent from +cleanup_status+: a Runtime may fail
+    # during execution but still release every owned resource successfully.
+    # @api private
+    class ShutdownResult
+      attr_reader :runtime_outcome,
+        :cleanup_status,
+        :event_loop_status,
+        :task_registry_status,
+        :error
+
+      def self.not_started
+        new(
+          runtime_outcome: :terminated,
+          cleanup_status: :complete,
+          event_loop_status: :not_started,
+          task_registry_status: :empty
+        )
+      end
+
+      def initialize(
+        runtime_outcome:,
+        cleanup_status:,
+        event_loop_status:,
+        task_registry_status:,
+        error: nil
+      )
+        @runtime_outcome = runtime_outcome
+        @cleanup_status = cleanup_status
+        @event_loop_status = event_loop_status
+        @task_registry_status = task_registry_status
+        @error = error
+        freeze
+      end
+
+      # Returns true when every Runtime-owned resource is known to have stopped.
+      def cleanup_complete?
+        @cleanup_status == :complete
+      end
+
+      # Returns true only for a graceful, error-free shutdown.
+      # A cancellation may release every resource, but is not considered clean.
+      def clean?
+        @runtime_outcome == :terminated &&
+          @cleanup_status == :complete &&
+          %i[not_started terminated].include?(@event_loop_status) &&
+          @task_registry_status == :empty
+      end
+
+      # Runtime reset is safe when cleanup completed, even if execution failed.
+      def success?
+        cleanup_complete?
+      end
+    end
+  end
+end

data/lib/phronomy/engine/runtime/task_registry.rb

@@ -5,10 +5,8 @@ module Phronomy
     # Internal registry of active {Task} instances for a {Runtime}.
     #
     # Tracks every task that has been spawned but not yet completed so that
-    # {Runtime#shutdown} can drain them.  Tasks that complete synchronously
-    # (e.g. under {FakeScheduler} / {ImmediateBackend}) deregister themselves
-    # before the caller returns from {Runtime#spawn}, so they are never added
-    # to the registry in the first place.
+    # {Runtime#shutdown} can drain them. Tasks that complete synchronously
+    # deregister themselves before the caller returns from {Runtime#spawn}.
     # @api private
     class TaskRegistry
       def initialize
@@ -16,33 +14,82 @@ module Phronomy
         @tasks = []
       end
 
-      # Adds +task+ to the registry unless it already completed synchronously.
-      # @param task [Task]
-      # @return [void]
+      # Adds +task+ unless it already completed synchronously.
       # @api private
       def register(task)
         @mutex.synchronize { @tasks << task unless task.done? }
       end
 
-      # Removes +task+ from the registry (called from the task's ensure block).
-      # @param task [Task]
-      # @return [void]
+      # Removes +task+ from the registry.
       # @api private
       def deregister(task)
         @mutex.synchronize { @tasks.delete(task) }
       end
 
-      # Waits for all registered tasks to finish (used by {Runtime#shutdown}).
-      # @return [void]
+      # Waits for registered tasks until the absolute monotonic +deadline+.
+      # The registry is re-snapshotted because tasks may create follow-up tasks
+      # while Runtime shutdown is draining accepted work.
+      #
+      # @param deadline [Numeric] absolute Process::CLOCK_MONOTONIC value
+      # @return [Symbol] +:empty+ or +:timeout+
+      # @api private
+      def drain_until(deadline)
+        loop do
+          tasks = snapshot
+          return :empty if tasks.empty?
+
+          tasks.each do |task|
+            remaining = deadline - monotonic_now
+            return :timeout if remaining <= 0
+
+            begin
+              task.join(remaining)
+            rescue
+              # Some backends re-raise the task error from join. The task's
+              # ensure block still deregisters it, so continue the drain.
+              nil
+            end
+
+            return :timeout if task.alive? && monotonic_now >= deadline
+          end
+
+          return :empty if empty?
+          return :timeout if monotonic_now >= deadline
+        end
+      end
+
+      # Compatibility helper for callers that explicitly require an unbounded
+      # drain. Runtime#shutdown uses {#drain_until}.
       # @api private
       def drain
-        tasks = @mutex.synchronize { @tasks.dup }
-        tasks.each do |t|
-          t.join
+        snapshot.each do |task|
+          task.join
         rescue
           nil
         end
       end
+
+      # @return [Boolean]
+      # @api private
+      def empty?
+        @mutex.synchronize { @tasks.empty? }
+      end
+
+      # @return [Integer]
+      # @api private
+      def size
+        @mutex.synchronize { @tasks.size }
+      end
+
+      private
+
+      def snapshot
+        @mutex.synchronize { @tasks.dup }
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
     end
   end
 end