phronomy 0.13.0 → 0.14.0

data/lib/phronomy/engine/fsm_session.rb

@@ -32,7 +32,8 @@ module Phronomy
     # @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)
+      recursion_limit:, event_loop:, timer_queue_provider:, action_timeouts: {},
+      resume_event: nil, resume_phase: nil)
       @id = id
       @ctx = context
       @entry_point = entry_point
@@ -44,6 +45,8 @@ module Phronomy
       @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
       @step = 0
@@ -79,10 +82,10 @@ module Phronomy
             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
+              @timer_queue_provider.call.schedule(seconds: timeout_secs) do
                 next if result.done?
 
-                event_loop.post(
+                @event_loop.post(
                   Event.new(
                     type: :error,
                     target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
@@ -95,13 +98,13 @@ module Phronomy
             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}))
+                @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))
+                @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))
+                @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
@@ -179,7 +182,7 @@ module Phronomy
       end
 
       if @auto_state_set.key?(@current_state)
-        event_loop.post(Event.new(type: :state_completed, target_id: @id, payload: nil))
+        @event_loop.post(Event.new(type: :state_completed, target_id: @id, payload: nil))
         return
       end
 
@@ -200,18 +203,18 @@ module Phronomy
     def finish!
       @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}))
+      @event_loop.post(Event.new(type: :finished, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: @id, result: @ctx}))
     end
 
     def halt!
       @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}))
+      @event_loop.post(Event.new(type: :halted, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: @id, result: @ctx}))
     end
 
     def finish_with_error(err)
       @done = true
-      event_loop.post(Event.new(type: :error, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: @id, result: err}))
+      @event_loop.post(Event.new(type: :error, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: @id, result: err}))
     end
 
     def fire_event!(tracker, event_name, from_state)
@@ -229,13 +232,13 @@ module Phronomy
     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
 
-    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

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

data/lib/phronomy/engine/runtime.rb

@@ -8,6 +8,7 @@ require_relative "runtime/timer_queue"
 require_relative "runtime/scheduler_timer_adapter"
 require_relative "runtime/task_registry"
 require_relative "runtime/runtime_metrics"
+require_relative "runtime/shutdown_result"
 require_relative "runtime/timer_service"
 
 module Phronomy
@@ -47,8 +48,68 @@ module Phronomy
     #
     # @return [Runtime]
     # @api private
-    def self.instance
-      @instance ||= begin
+    @instance_mutex = Mutex.new
+
+    class << self
+      def instance
+        instance_mutex.synchronize do
+          @instance ||= build_default_runtime
+        end
+      end
+
+      # Compatibility setter retained for existing tests.
+      def instance=(runtime)
+        replace_default_for_test(runtime)
+      end
+
+      # Test-only, non-creating access to the default Runtime.
+      def default_if_initialized_for_test
+        instance_mutex.synchronize { @instance }
+      end
+
+      # Test-only replacement. The caller owns both Runtime lifecycles.
+      def replace_default_for_test(runtime)
+        instance_mutex.synchronize do
+          previous = @instance
+          @instance = runtime
+          previous
+        end
+      end
+
+      # Test-only restoration of a previously captured Runtime.
+      def restore_default_for_test(runtime)
+        instance_mutex.synchronize { @instance = runtime }
+      end
+
+      def reset_default!(timeout: Phronomy.configuration.event_loop_stop_grace_seconds)
+        runtime = instance_mutex.synchronize { @instance }
+        return ShutdownResult.not_started unless runtime
+
+        result = runtime.shutdown(timeout: timeout)
+        unless result.cleanup_complete?
+          raise Phronomy::RuntimeShutdownError,
+            "Runtime cleanup is incomplete; default Runtime was retained"
+        end
+
+        instance_mutex.synchronize do
+          @instance = nil if @instance.equal?(runtime)
+        end
+        result
+      end
+
+      # Does not create a Runtime or EventLoop.
+      def in_event_loop_context?
+        runtime = instance_mutex.synchronize { @instance }
+        runtime&.event_loop_current? || false
+      end
+
+      private
+
+      def instance_mutex
+        @instance_mutex ||= Mutex.new
+      end
+
+      def build_default_runtime
         scheduler = case Phronomy.configuration.runtime_backend
         when :cooperative
           Phronomy.configuration.logger&.warn(
@@ -74,14 +135,6 @@ module Phronomy
       end
     end
 
-    # Replaces the process-wide default Runtime.  Useful in tests.
-    # @param runtime [Runtime]
-    # @return [Runtime]
-    # @api private
-    def self.instance=(runtime)
-      @instance = runtime
-    end
-
     # Returns +true+ when the calling thread is executing inside an active
     # scheduler task (i.e. {Task.current} is non-nil).  Code running inside
     # a {Runtime#spawn} block is always in a scheduler context.
@@ -118,38 +171,29 @@ module Phronomy
     # @return [Scheduler]
     attr_reader :scheduler
 
+    # @return [Symbol] current Runtime lifecycle state
+    # @api private
+    def state
+      @lifecycle_mutex.synchronize { @state }
+    end
+
     # @param scheduler [Scheduler] execution backend (default: {ThreadScheduler})
     # @api private
     def initialize(scheduler: ThreadScheduler.new)
       @scheduler = scheduler
+      @event_loop_scheduler = ThreadScheduler.new
       @task_registry = TaskRegistry.new
       @metrics = RuntimeMetrics.new
-      @gate_registry = Phronomy::Concurrency::GateRegistry.new
-      @pool_registry = Phronomy::Concurrency::PoolRegistry.new
       @timer_service = TimerService.new(scheduler)
-    end
-
-    # Returns (or lazily creates) the {ConcurrencyGate} for the named resource.
-    #
-    # Gate caps are read from the global {Phronomy::Configuration} when the gate
-    # is first accessed; subsequent calls return the cached gate.  To change the
-    # cap at runtime, call {#reset_gate} first.
-    #
-    # @param name [:agent, :tool, :workflow, :llm, :vector] resource name
-    # @return [ConcurrencyGate]
-    # @api private
-    def gate(name)
-      @gate_registry.get(name.to_sym)
-    end
-
-    # Drops the cached gate for +name+ so that the next call to {#gate} rebuilds
-    # it from the current configuration.  Useful in tests.
-    #
-    # @param name [Symbol]
-    # @return [void]
-    # @api private
-    def reset_gate(name)
-      @gate_registry.reset(name.to_sym)
+      @pool_registry = Phronomy::Concurrency::PoolRegistry.new(
+        timer_queue_provider: -> { @timer_service.timer_queue }
+      )
+      @lifecycle_mutex = Mutex.new
+      @shutdown_mutex = Mutex.new
+      @state = :running
+      @event_loop = nil
+      @failure = nil
+      @shutdown_result = nil
     end
 
     # Cooperative yield point.
@@ -226,6 +270,7 @@ module Phronomy
     # @return [TaskGroup]
     # @api private
     def task_group(limit: Float::INFINITY, failure_policy: :fail_fast)
+      ensure_accepting_work!
       TaskGroup.new(limit: limit, failure_policy: failure_policy, runtime: self)
     end
 
@@ -246,6 +291,7 @@ module Phronomy
     # @return [Task]
     # @api private
     def spawn(name: nil, &block)
+      ensure_accepting_work!
       type = _task_type(name)
       spawn_at = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
       @metrics.record_start(type)
@@ -302,11 +348,15 @@ module Phronomy
     # constructing a Runtime with custom pool options or by replacing the
     # shared Runtime via {.instance=} in tests.
     #
-    # @param pool_size  [Integer] worker thread count (default: 10)
-    # @param queue_size [Integer] max pending operations (default: 100)
+    # @param pool_size  [Integer] worker thread count
+    #   (default: {Phronomy::Configuration#blocking_io_pool_size}, currently 10)
+    # @param queue_size [Integer] max pending operations
+    #   (default: {Phronomy::Configuration#blocking_io_queue_size}, currently 100)
     # @return [BlockingAdapterPool]
     # @api private
-    def blocking_io(pool_size: 10, queue_size: 100)
+    def blocking_io(pool_size: Phronomy.configuration.blocking_io_pool_size,
+      queue_size: Phronomy.configuration.blocking_io_queue_size)
+      ensure_accepting_work!
       @pool_registry.default_pool(pool_size: pool_size, queue_size: queue_size)
     end
 
@@ -326,6 +376,7 @@ module Phronomy
     # @return [BlockingAdapterPool]
     # @api private
     def pool(name, size: 10, queue_size: 100)
+      ensure_accepting_work!
       @pool_registry.named_pool(name, size: size, queue_size: queue_size)
     end
 
@@ -346,33 +397,172 @@ module Phronomy
     # @return [TimerQueue, SchedulerTimerAdapter]
     # @api private
     def timer_queue
+      ensure_accepting_work!
       @timer_service.timer_queue
     end
 
-    # Waits for all registered tasks to finish, then shuts down the
-    # EventLoop (if active), blocking adapter pool, named pools, and timer queue
-    # (if they were started).
-    #
-    # When EventLoop mode is enabled, all pending Workflow and Agent FSM events
-    # are drained before pools are shut down, ensuring in-flight sessions
-    # complete cleanly.
-    #
-    # Call this before process exit to avoid leaving orphaned threads or
-    # pending work items.
-    #
-    # @return [void]
+    # Returns the Runtime-owned EventLoop, creating it once on first use.
+    # During draining an existing loop remains available, but an unused loop
+    # is never created after shutdown begins.
+    # @api private
+    def event_loop
+      @lifecycle_mutex.synchronize do
+        case @state
+        when :running
+          @event_loop ||= EventLoop.new(runtime: self)
+        when :draining
+          return @event_loop if @event_loop
+
+          raise Phronomy::RuntimeShutdownError,
+            "EventLoop was not initialized before Runtime shutdown began"
+        else
+          raise Phronomy::RuntimeShutdownError,
+            "Runtime is #{@state}; EventLoop is unavailable"
+        end
+      end
+    end
+
+    # Does not create an EventLoop.
+    # @api private
+    def event_loop_current?
+      event_loop = @lifecycle_mutex.synchronize { @event_loop }
+      event_loop&.current? || false
+    end
+
+    # Internal EventLoop service spawn. Always uses a real OS thread and is
+    # deliberately excluded from the normal TaskRegistry drain.
     # @api private
-    def shutdown
-      @task_registry.drain
-      # Drain EventLoop events before stopping pools so that in-flight
-      # Workflow / Agent FSM sessions can complete their final LLM calls.
-      Phronomy::EventLoop.instance.stop(drain: true)
-      @pool_registry.shutdown
-      @timer_service.shutdown
+    def __spawn_event_loop_service(&block)
+      @event_loop_scheduler.spawn(name: "event-loop", parent: nil, &block)
+    end
+
+    # Called only for an unexpected dispatcher failure.
+    # @api private
+    def __event_loop_failed(error)
+      @lifecycle_mutex.synchronize do
+        return if @shutdown_result || @state == :terminated
+
+        @failure ||= error
+        @state = :failed
+      end
+    end
+
+    # Synchronous, bounded Runtime shutdown. Must be invoked from an external
+    # management thread, lifecycle hook, or test teardown—not a Phronomy Task.
+    #
+    # +timeout+ bounds TaskRegistry and EventLoop graceful shutdown. Existing
+    # pool and timer shutdown contracts are unchanged by this proposal.
+    # @return [Runtime::ShutdownResult]
+    # @api public
+    def shutdown(
+      timeout: Phronomy.configuration.event_loop_stop_grace_seconds,
+      cancel_grace: timeout
+    )
+      if Phronomy::Task.current
+        raise Phronomy::RuntimeShutdownReentrancyError,
+          "Runtime#shutdown must be called from an external management thread"
+      end
+      validate_timeout!(timeout, :timeout)
+      validate_timeout!(cancel_grace, :cancel_grace)
+
+      @shutdown_mutex.synchronize do
+        return @shutdown_result if @shutdown_result
+
+        deadline = monotonic_now + timeout
+        event_loop = @lifecycle_mutex.synchronize do
+          @state = :draining unless @state == :failed
+          @event_loop
+        end
+        event_loop&.begin_draining
+
+        task_status = drain_runtime_work(event_loop, deadline)
+
+        @lifecycle_mutex.synchronize do
+          @state = :stopping unless @state == :failed
+        end
+
+        event_loop_status = if event_loop
+          event_loop.shutdown(deadline: deadline, cancel_grace: cancel_grace)
+        else
+          :not_started
+        end
+
+        subsystem_error = shutdown_pools_and_timer
+        final_task_status = @task_registry.empty? ? :empty : task_status
+        cleanup_complete = final_task_status == :empty &&
+          (!event_loop || !event_loop.task_alive?) &&
+          event_loop_status != :cancel_timeout &&
+          subsystem_error.nil?
+
+        failure = @lifecycle_mutex.synchronize { @failure } || subsystem_error
+        runtime_outcome = if failure || event_loop_status == :failed
+          :failed
+        else
+          :terminated
+        end
+        result = ShutdownResult.new(
+          runtime_outcome: runtime_outcome,
+          cleanup_status: cleanup_complete ? :complete : :incomplete,
+          event_loop_status: event_loop_status,
+          task_registry_status: final_task_status,
+          error: failure
+        )
+
+        @lifecycle_mutex.synchronize do
+          @state = cleanup_complete ? runtime_outcome : :failed
+          @shutdown_result = result
+        end
+        result
+      end
     end
 
     private
 
+    def ensure_accepting_work!
+      current_state = @lifecycle_mutex.synchronize { @state }
+      return if %i[running draining].include?(current_state)
+
+      raise Phronomy::RuntimeShutdownError,
+        "Runtime is #{current_state}; new work is not accepted"
+    end
+
+    def drain_runtime_work(event_loop, deadline)
+      loop do
+        task_status = @task_registry.drain_until(deadline)
+        return :timeout if task_status == :timeout
+
+        event_loop_idle = !event_loop || event_loop.wait_until_idle(deadline)
+        return :timeout unless event_loop_idle
+        return :empty if @task_registry.empty?
+      end
+    end
+
+    def shutdown_pools_and_timer
+      error = nil
+      begin
+        @pool_registry.shutdown
+      rescue => e
+        error ||= e
+      ensure
+        begin
+          @timer_service.shutdown
+        rescue => e
+          error ||= e
+        end
+      end
+      error
+    end
+
+    def validate_timeout!(value, name)
+      return if value.is_a?(Numeric) && value >= 0
+
+      raise ArgumentError, "#{name} must be a non-negative Numeric"
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     TASK_TYPE_PREFIXES = %w[agent tool workflow rag llm vector].freeze
     private_constant :TASK_TYPE_PREFIXES
 

data/lib/phronomy/metrics.rb

@@ -20,9 +20,10 @@ module Phronomy
     # @return [Hash{Symbol => Numeric}]
     # @api public
     def self.snapshot
-      pool = Runtime.instance.blocking_io
-      el = EventLoop.instance
-      task_snap = Runtime.instance.task_snapshot
+      runtime = Runtime.instance
+      pool = runtime.blocking_io
+      el = runtime.event_loop
+      task_snap = runtime.task_snapshot
 
       {
         blocking_pool_active: pool.active_count,