phronomy 0.17.0 → 0.19.0

data/lib/phronomy/configuration.rb

@@ -2,11 +2,9 @@
 
 module Phronomy
   # Holds global configuration for the entire framework.
-  # Configure via the Phronomy.configure block.
   class Configuration
     STREAM_CALLBACK_ERROR_POLICIES = %i[report fail_task].freeze
-    RUNTIME_BACKENDS = %i[thread immediate fiber].freeze
-    private_constant :STREAM_CALLBACK_ERROR_POLICIES, :RUNTIME_BACKENDS
+    private_constant :STREAM_CALLBACK_ERROR_POLICIES
 
     attr_accessor :default_model
     attr_accessor :default_embedding_model
@@ -18,22 +16,17 @@ module Phronomy
     attr_accessor :trace_pii
     attr_accessor :logger
     attr_accessor :event_loop_stop_grace_seconds
-    attr_accessor :state_store
+    attr_accessor :persistence
     attr_accessor :tool_result_max_size
     attr_accessor :llm_adapter
     attr_accessor :event_loop_starvation_threshold_seconds
     attr_accessor :event_loop_dispatch_threshold_seconds
-    attr_accessor :scheduler_debug
-    attr_accessor :blocking_detect_threshold_ms
     attr_reader :stream_callback_error_policy
-    attr_accessor :blocking_io_pool_size
-    attr_accessor :blocking_io_queue_size
+    attr_accessor :offload_pool_size
+    attr_accessor :offload_queue_size
     attr_accessor :authorization_pool_size
     attr_accessor :authorization_queue_size
     attr_accessor :authorization_timeout
-    attr_accessor :starvation_threshold_ms
-    attr_reader :runtime_backend
-    attr_accessor :strict_runtime_guards
 
     def stream_callback_error_policy=(value)
       unless STREAM_CALLBACK_ERROR_POLICIES.include?(value)
@@ -45,18 +38,6 @@ module Phronomy
       @stream_callback_error_policy = value
     end
 
-    # Scheduler backend used for newly-created Runtime instances.
-    # Supported values are :thread, :immediate, and :fiber.
-    def runtime_backend=(value)
-      value = value.to_sym if value.respond_to?(:to_sym)
-      unless RUNTIME_BACKENDS.include?(value)
-        allowed = RUNTIME_BACKENDS.map(&:inspect).join(", ")
-        raise Phronomy::ConfigurationError,
-          "runtime_backend must be one of: #{allowed}"
-      end
-      @runtime_backend = value
-    end
-
     def initialize
       @recursion_limit = 25
       @tracer = Phronomy::Tracing::NullTracer.new
@@ -66,17 +47,13 @@ module Phronomy
       @llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
       @event_loop_starvation_threshold_seconds = nil
       @event_loop_dispatch_threshold_seconds = nil
-      @scheduler_debug = false
-      @blocking_detect_threshold_ms = nil
       @stream_callback_error_policy = :report
-      @blocking_io_pool_size = 10
-      @blocking_io_queue_size = 100
+      @offload_pool_size = 10
+      @offload_queue_size = 100
       @authorization_pool_size = 4
       @authorization_queue_size = 100
       @authorization_timeout = 5
-      @starvation_threshold_ms = 50
-      @runtime_backend = :thread
-      @strict_runtime_guards = false
+      @persistence = nil
     end
   end
 end

data/lib/phronomy/diagnostics.rb

@@ -1,62 +1,33 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Developer-facing diagnostics for blocking operation detection (Issue #279).
-  #
-  # Provides debug dump utilities that can be called from an IRB / Rails console
-  # or in test helpers to inspect the current state of the Runtime.
-  #
-  # @example Enable diagnostics and print a dump
-  #   Phronomy.configure { |c| c.scheduler_debug = true }
-  #   Phronomy::Diagnostics.dump
+  # Developer-facing diagnostics for EventLoop and offload execution boundaries.
   module Diagnostics
-    # Prints a formatted summary of the current Runtime state to +$stderr+
-    # (or the supplied IO).
-    #
-    # Includes:
-    # - BlockingAdapterPool: active workers, queue depth, abandoned count
-    # - EventLoop: last / max / average lag in milliseconds
-    #
-    # @param out [IO] output destination (default: $stderr)
-    # @return [void]
-    # @api public
     def self.dump(out: $stderr)
       snap = Phronomy::Metrics.snapshot
 
       out.puts "[Phronomy::Diagnostics] Runtime state dump"
-      out.puts "  BlockingAdapterPool:"
-      out.puts "    pool_size       : #{snap[:blocking_pool_size]}"
-      out.puts "    active_count    : #{snap[:blocking_pool_active]}"
-      out.puts "    queue_depth     : #{snap[:blocking_pool_queue_length]}"
-      out.puts "    abandoned_total : #{snap[:blocking_pool_abandoned_total]}"
+      out.puts "  OffloadPool:"
+      out.puts "    pool_size        : #{snap[:offload_pool_size]}"
+      out.puts "    active_count     : #{snap[:offload_pool_active]}"
+      out.puts "    queue_depth      : #{snap[:offload_pool_queue_length]}"
+      out.puts "    abandoned_active : #{snap[:offload_pool_abandoned_active]}"
+      out.puts "    abandoned_total  : #{snap[:offload_pool_abandoned_total]}"
       out.puts "  EventLoop:"
-      out.puts "    last_lag_ms     : #{snap[:event_loop_lag_last_ms]}"
-      out.puts "    max_lag_ms      : #{snap[:event_loop_lag_max_ms]}"
-      out.puts "    average_lag_ms  : #{snap[:event_loop_lag_average_ms]}"
+      out.puts "    last_lag_ms      : #{snap[:event_loop_lag_last_ms]}"
+      out.puts "    max_lag_ms       : #{snap[:event_loop_lag_max_ms]}"
+      out.puts "    average_lag_ms   : #{snap[:event_loop_lag_average_ms]}"
     end
 
-    # Returns the diagnostics state as a plain Hash (useful for JSON export).
-    #
-    # @return [Hash]
-    # @api public
     def self.snapshot
       Phronomy::Metrics.snapshot
     end
 
-    # Raises an error if +invoke+ (blocking) is called from inside an EventLoop
-    # action, preventing accidental scheduler stalls.
-    #
-    # Called by Agent::Base#invoke and Workflow#invoke before executing.
-    #
-    # @raise [Phronomy::SchedulerReentrancyError] when called from EventLoop thread
-    # @return [void]
-    # @api private
     def self.assert_not_in_event_loop!
       return unless Phronomy::Runtime.in_event_loop_context?
 
-      raise Phronomy::SchedulerReentrancyError,
-        "Blocking invoke called from inside an EventLoop action. " \
-        "Use invoke_async instead."
+      raise Phronomy::EventLoopReentrancyError,
+        "Blocking invoke called from inside an EventLoop action. Use invoke_async instead."
     end
   end
 end

data/lib/phronomy/engine/concurrency/async_queue.rb

@@ -2,219 +2,36 @@
 
 module Phronomy
   module Concurrency
-    # A thread-safe FIFO queue for passing values between concurrent tasks.
+    # Thread-safe FIFO queue used at explicit thread boundaries.
     #
-    # Wraps +Thread::Queue+ so that callers do not need to reference the Ruby
-    # standard-library type directly.  A future implementation may replace the
-    # backing primitive without changing call sites.
-    #
-    # @example Producer / consumer
-    #   queue = Phronomy::Concurrency::AsyncQueue.new
-    #   Runtime.instance.spawn { queue.push(expensive_io()) }
-    #   value = queue.pop   # blocks until the producer pushes
-    # @api private
+    # It intentionally contains no scheduler/Fiber semantics. Cooperative
+    # application execution is represented by FSMSession state and EventLoop events.
     class AsyncQueue
-      # @param max_size [Integer, nil] optional upper bound on queue depth.
-      #   When set, {#push} blocks the caller until a slot is available.
-      # @api private
       def initialize(max_size: nil)
         @queue = max_size ? SizedQueue.new(max_size) : Thread::Queue.new
-        @max_size = max_size
-        @waiter_mutex = Mutex.new
-        @cross_thread_waiter = nil    # [fiber, scheduler] set by _pop_cooperative; consumed by push
-        @cross_thread_scheduler = nil # set by expect_cross_thread_push
       end
 
-      # Enqueues +item+.
-      # In a cooperative scheduler context with a bounded queue (max_size:), suspends
-      # the current Fiber via a scheduler signal when the queue is full rather than
-      # blocking the OS thread.  Without a scheduler, falls back to the standard
-      # SizedQueue blocking behaviour.
-      # @param item [Object] value to enqueue
-      # @return [self]
-      # @api private
       def push(item)
-        scheduler = Phronomy::Runtime::Scheduler.current
-        if scheduler && @max_size
-          _push_cooperative(scheduler, item)
-        else
-          @queue.push(item)
-          scheduler.raise_signal(@coop_signal) if scheduler && @coop_signal
-          # Wake a cross-thread waiter if one is registered.
-          # Handles the case where a DeterministicScheduler Fiber is suspended
-          # in _pop_cooperative waiting for a push from a non-scheduler thread
-          # (e.g. EventLoop thread where Scheduler.current is nil).
-          # enqueue_fiber is thread-safe; complete_blocking_await decrements
-          # @pending_awaits so run_until_idle can eventually exit.
-          if @cross_thread_scheduler
-            waiter = @waiter_mutex.synchronize do
-              w = @cross_thread_waiter
-              @cross_thread_waiter = nil
-              w
-            end
-            if waiter
-              fiber, sched = waiter
-              sched.complete_blocking_await
-              sched.enqueue_fiber(-> { fiber.resume })
-            end
-          end
-        end
+        @queue.push(item)
         self
       end
 
-      # Dequeues and returns the next item.
-      # In a cooperative scheduler context, suspends the current Fiber (yielding
-      # control back to the scheduler) rather than blocking the OS thread.
-      #
-      # When +timeout+ is given the semantics depend on the active backend:
-      #
-      # * **Thread backend** (`:thread`) — uses real wall-clock time via
-      #   +Thread::Queue#pop(timeout:)+.  Requires Ruby 3.2+.
-      #   Returns +nil+ if no item arrives within the specified number of real seconds.
-      # * **DeterministicScheduler / `:fiber` backend** — uses the scheduler's
-      #   *virtual time* (+scheduler.virtual_time+).  The timeout elapses only when
-      #   the virtual clock is advanced (e.g. via {Phronomy::Testing::FakeClock#advance}).
-      #   In tests this means the timeout is fully deterministic and does not depend on
-      #   actual elapsed wall time.  However, in production `:fiber` mode the timeout
-      #   may never expire unless the scheduler explicitly advances virtual time.
-      #
-      # @note The `:fiber` backend is **EXPERIMENTAL**.  Real-time timeout behaviour
-      #   in production workloads is not guaranteed and may differ from wall-clock
-      #   expectations.
-      # @note **Cooperative timeout limitation**: on the cooperative path, the
-      #   deadline is re-checked *after* a wake-up signal arrives.  If virtual time
-      #   has already passed the deadline when the consumer is woken by a producer
-      #   push, the consumer returns +nil+ rather than the pushed item.  Without any
-      #   wake-up signal the waiting Fiber remains suspended even after
-      #   +scheduler.advance+ — the timeout does not self-fire.
-      # @param timeout [Numeric, nil] seconds to wait before returning +nil+.
-      #   Semantics are wall-clock on `:thread` and virtual-time on `:fiber`.
-      # @return [Object, nil] the next item, or +nil+ when timeout expires
-      # @api private
       def pop(timeout: nil)
-        scheduler = Phronomy::Runtime::Scheduler.current
-        if scheduler
-          _pop_cooperative(scheduler, timeout: timeout)
-        elsif timeout
-          @queue.pop(timeout: timeout)
-        else
-          @queue.pop
-        end
+        timeout ? @queue.pop(timeout: timeout) : @queue.pop
       end
 
-      # Returns the current number of items in the queue.
-      # @return [Integer]
-      # @api private
       def size
         @queue.size
       end
 
-      # Returns +true+ when the queue contains no items.
-      # @return [Boolean]
-      # @api private
       def empty?
         @queue.empty?
       end
 
-      # Closes the queue.  Subsequent {#pop} calls raise +ClosedQueueError+.
-      # @return [self]
-      # @api private
       def close
         @queue.close
         self
       end
-
-      # Marks this queue as expecting pushes from a non-scheduler OS thread.
-      # When set, {#pop} in cooperative mode uses +track_blocking_await+ so that
-      # {Runtime::DeterministicScheduler#run_until_idle} does not exit while
-      # waiting for the cross-thread push.  Called by {EventLoop#register} when
-      # a cooperative scheduler is active on the calling thread.
-      # @param scheduler [Runtime::Scheduler]
-      # @return [self]
-      # @api private
-      def expect_cross_thread_push(scheduler)
-        @cross_thread_scheduler = scheduler
-        self
-      end
-
-      private
-
-      # Cooperative pop for DeterministicScheduler context.
-      # Suspends the current Fiber via the scheduler's signal mechanism rather than
-      # blocking the OS thread.
-      #
-      # Two suspension paths:
-      # * **Same-scheduler** (default): uses {CoopSignal} — the producer is another
-      #   Fiber on the same DeterministicScheduler.  run_until_idle is allowed to
-      #   exit; the producer's push will enqueue the consumer Fiber.
-      # * **Cross-thread** ({#expect_cross_thread_push} was called): uses
-      #   +track_blocking_await+ so that run_until_idle does not exit while waiting
-      #   for a push from a non-scheduler OS thread (e.g. EventLoop).  The push
-      #   side calls +complete_blocking_await+ + +enqueue_fiber+ to resume.
-      #
-      # The empty?/register pair for the cross-thread path is wrapped in
-      # @waiter_mutex to eliminate the race between the empty check and the
-      # registration of the waker.
-      # @api private
-      # @param scheduler [Runtime::Scheduler]
-      # @param timeout [Numeric, nil]
-      # @return [Object, nil]
-      def _pop_cooperative(scheduler, timeout:)
-        @coop_signal ||= scheduler.new_signal
-        deadline = timeout ? (scheduler.virtual_time + timeout) : nil
-
-        loop do
-          unless @queue.empty?
-            item = @queue.pop(timeout: 0)
-            # Notify a push-waiter (bounded queue) that a slot opened up.
-            scheduler.raise_signal(@push_signal) if @push_signal
-            return item
-          end
-          return nil if deadline && scheduler.virtual_time >= deadline
-
-          if @cross_thread_scheduler
-            # Cross-thread path: atomically check the queue and register a waker
-            # so that a concurrent push cannot slip between the empty? check above
-            # and the registration below.
-            will_yield = false
-            @waiter_mutex.synchronize do
-              if @queue.empty?
-                @cross_thread_waiter = [Fiber.current, scheduler]
-                scheduler.track_blocking_await
-                will_yield = true
-              end
-              # else: push arrived between the loop's empty? check and here;
-              # will_yield stays false and the next loop iteration dequeues it.
-            end
-            Fiber.yield(:cooperative_suspend) if will_yield
-          else
-            scheduler.wait_for_signal(@coop_signal)
-          end
-
-          return nil if deadline && scheduler.virtual_time >= deadline
-        end
-      end
-
-      # Cooperative push for DeterministicScheduler context with a bounded queue.
-      # Suspends the current Fiber via a scheduler signal when the queue is full,
-      # rather than blocking the OS thread.
-      # @api private
-      # @param scheduler [Runtime::Scheduler]
-      # @param item [Object]
-      # @return [void]
-      def _push_cooperative(scheduler, item)
-        @push_signal ||= scheduler.new_signal
-
-        loop do
-          unless @queue.size >= @max_size
-            @queue.push(item)
-            # Notify any pop-waiter that an item is now available.
-            scheduler.raise_signal(@coop_signal) if @coop_signal
-            return
-          end
-          scheduler.wait_for_signal(@push_signal)
-        end
-      end
     end
   end
 end

data/lib/phronomy/engine/concurrency/cancellation_scope.rb

@@ -6,7 +6,7 @@ module Phronomy
     # optionally a {Deadline}.
     #
     # +CancellationScope+ replaces ad-hoc +Timeout.timeout+ calls in agent and
-    # tool code.  All work performed within a scope should observe the scope's
+    # tool code. All work performed within a scope should observe the scope's
     # token; when the scope is cancelled (explicitly or by deadline expiry) the
     # token is cancelled and all child tasks that check it will stop.
     #
@@ -18,10 +18,9 @@ module Phronomy
     #
     # @example Explicit cancellation
     #   scope = Phronomy::Concurrency::CancellationScope.new
-    #   Phronomy::Runtime.instance.spawn(name: "worker") do
-    #     scope.token.raise_if_cancelled!
-    #     # ... do work ...
-    #   end
+    #   operation = Phronomy::Runtime.instance.offload.submit(
+    #     cancellation_token: scope.token
+    #   ) { synchronous_operation }
     #   scope.cancel! if some_condition
     class CancellationScope
       # @return [CancellationToken] the token owned by this scope
@@ -33,7 +32,7 @@ module Phronomy
       # @param parent_token [CancellationToken, nil] when provided, cancellation of
       #   the parent token is propagated to this scope's token via a callback
       #   (for explicit cancel) and/or the Runtime timer queue (for monotonic
-      #   deadline expiry).  No polling thread is spawned.
+      #   deadline expiry). No polling thread is spawned.
       # @api private
       def initialize(parent_token: nil)
         @token = Phronomy::Concurrency::CancellationToken.new
@@ -92,7 +91,7 @@ module Phronomy
       end
 
       # Pops from +queue+ with a timeout derived from the attached deadline (or
-      # +fallback_timeout+ seconds when no deadline is set).  If the pop times out,
+      # +fallback_timeout+ seconds when no deadline is set). If the pop times out,
       # the scope is cancelled and the block is called (or a {TimeoutError} raised).
       #
       # @param queue [Phronomy::Concurrency::AsyncQueue] the queue to pop from

data/lib/phronomy/engine/concurrency/cancellation_token.rb

@@ -28,8 +28,20 @@ module Phronomy
         [remaining, 0.0].max
       end
 
+      # Registers a callback for explicit cancellation.
+      #
+      # Deadline expiry by itself only changes {#cancelled?}. Components that need
+      # callback delivery for a monotonic deadline must promote that deadline to
+      # +cancel!+ through the Runtime timer queue.
+      #
+      # Cancellation callbacks are independent notifications. Failure of one
+      # callback is logged and does not suppress delivery to other callbacks.
+      #
+      # @return [self]
       # @api public
       def on_cancel(&block)
+        raise ArgumentError, "on_cancel requires a block" unless block
+
         already_cancelled = @mutex.synchronize do
           if @cancelled
             true
@@ -38,19 +50,29 @@ module Phronomy
             false
           end
         end
-        block.call if already_cancelled
+        deliver_cancel_callback(block) if already_cancelled
         self
       end
 
+      # Explicitly cancels the token and invokes each currently registered callback
+      # once. The callback registry is cleared before callbacks run so completed
+      # registrations are not retained for the lifetime of a long-lived token.
+      #
+      # Cancellation callbacks are isolated from one another: a StandardError raised
+      # by one callback is logged and the remaining callbacks are still delivered.
+      #
+      # @return [self]
       # @api public
       def cancel!
         callbacks = @mutex.synchronize do
           return self if @cancelled
 
           @cancelled = true
-          @cancel_callbacks.dup
+          callbacks = @cancel_callbacks
+          @cancel_callbacks = []
+          callbacks
         end
-        callbacks.each(&:call)
+        callbacks.each { |callback| deliver_cancel_callback(callback) }
         self
       end
 
@@ -66,6 +88,29 @@ module Phronomy
       def raise_if_cancelled!(message = "invocation cancelled")
         raise Phronomy::CancellationError, message if cancelled?
       end
+
+      private
+
+      def deliver_cancel_callback(callback)
+        callback.call
+      rescue => error
+        Phronomy.configuration.logger&.error do
+          "[CancellationToken] on_cancel callback raised #{error.class}: #{error.message}"
+        end
+      end
+
+      # Removes an explicit-cancellation callback that is no longer needed.
+      #
+      # This exists so framework operation registrations do not keep their captured
+      # state alive when the operation completes before the token is cancelled. It is
+      # intentionally not part of the public cancellation API.
+      #
+      # A concurrent +cancel!+ may already have taken the callback for delivery;
+      # callers must therefore make their callback idempotent.
+      def unregister_cancel_callback(callback)
+        @mutex.synchronize { @cancel_callbacks.delete(callback) }
+        self
+      end
     end
   end
 end

data/lib/phronomy/engine/concurrency/deadline.rb

@@ -44,9 +44,8 @@ module Phronomy
       end
 
       # Attaches this deadline to a {CancellationToken} by cancelling the token
-      # when the deadline expires.  Uses the Runtime timer queue (a single
-      # background thread shared by all deadlines) instead of spawning one thread
-      # per deadline.
+      # when the deadline expires. The Runtime timer queue is driven by EventLoop;
+      # no timer-specific OS thread is created.
       #
       # @param token [CancellationToken]
       # @param timer_queue [Runtime::TimerQueue, nil] queue to register with;