phronomy 0.7.0 → 0.7.1

data/lib/phronomy/runtime/fake_scheduler.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Synchronous scheduler for use in tests.
+    #
+    # Each spawned task is executed immediately on the calling thread using
+    # {Task::ImmediateBackend}.  No new threads are created, so a
+    # {Runtime} that uses +FakeScheduler+ does not increase the process
+    # Thread count on {Runtime#spawn}.
+    #
+    # In addition to the basic synchronous execution, +FakeScheduler+ records
+    # all task lifecycle events in {#event_log} and all spawned tasks in
+    # {#tasks}.  This allows specs to assert event ordering and task state
+    # without relying on wall-clock sleeps.
+    #
+    # === tick / tick_until
+    #
+    # Because +FakeScheduler+ uses {Task::ImmediateBackend}, every task runs
+    # to completion before {Runtime#spawn} returns.  Consequently {#tick} is
+    # semantically a no-op -- the "ready task" has already executed.  It is
+    # provided so that test code written against the cooperative scheduler
+    # interface compiles and documents intent (e.g. "advance by one step").
+    #
+    # === pending_timers
+    #
+    # If a {Phronomy::Testing::FakeClock} is injected via {#clock=}, its
+    # pending callbacks are surfaced as +pending_timers+.
+    #
+    # @example
+    #   runtime = Phronomy::Runtime.new(scheduler: Phronomy::Runtime::FakeScheduler.new)
+    #   task = runtime.spawn(name: "agent-test") { 42 }
+    #   expect(task.await).to eq(42)
+    #   expect(task.status).to eq(:completed)
+    # @api private
+    class FakeScheduler < Scheduler
+      # @return [Array<Hash>] ordered list of task lifecycle events.
+      #   Each entry is +{ type:, task_name:, at: }+ where +type+ is one of
+      #   +:spawned+, +:started+, +:completed+, +:cancelled+, +:failed+ and
+      #   +at+ is a Float monotonic timestamp (seconds).
+      attr_reader :event_log
+
+      # @return [Array<Hash>] all tasks spawned by this scheduler.
+      #   Each entry is +{ task:, name:, status: }+.
+      attr_reader :tasks
+
+      # Optional {Phronomy::Testing::FakeClock} used to timestamp events and
+      # surface pending timers.  When +nil+, a real monotonic clock is used.
+      # @return [Phronomy::Testing::FakeClock, nil]
+      attr_accessor :clock
+
+      def initialize
+        @event_log = []
+        @tasks = []
+        @clock = nil
+        @mutex = Mutex.new
+      end
+
+      # Spawns +block+ as a {Task} backed by {Task::ImmediateBackend}.
+      # The block executes synchronously before this method returns.
+      # Lifecycle events are recorded in {#event_log}.
+      #
+      # @param name   [String, nil]
+      # @param parent [Task, nil]
+      # @return [Task]
+      # @api private
+      def spawn(name:, parent:, &block)
+        _log_event(:spawned, name)
+        task = Task.spawn(name: name, parent: parent, backend_class: Task::ImmediateBackend) do
+          _log_event(:started, name)
+          begin
+            result = block.call
+            _log_event(:completed, name)
+            result
+          rescue CancellationError
+            _log_event(:cancelled, name)
+            raise
+          rescue => e
+            _log_event(:failed, name)
+            raise e
+          end
+        end
+        @mutex.synchronize { @tasks << {task: task, name: name, status: task.status} }
+        task
+      end
+
+      # Execute one ready task.
+      #
+      # Because {Task::ImmediateBackend} runs tasks synchronously inside
+      # {#spawn}, all ready tasks have already executed by the time this
+      # method is called.  This method is a no-op provided for API
+      # compatibility with cooperative scheduler interfaces.
+      #
+      # @return [self]
+      # @api private
+      def tick
+        self
+      end
+
+      # Run +block+ repeatedly until it returns truthy or +max_ticks+ is
+      # reached.  Because tasks execute synchronously, the condition is
+      # evaluated once; if it is already met this method returns immediately.
+      #
+      # @param max_ticks [Integer] safety bound (default: 1000)
+      # @yield condition evaluated after each tick
+      # @return [Boolean] +true+ if condition was satisfied
+      # @api private
+      def tick_until(max_ticks: 1000)
+        max_ticks.times do
+          return true if yield
+          tick
+        end
+        yield ? true : false
+      end
+
+      # Returns a list of pending timer entries surfaced from the injected
+      # {clock}.  Returns an empty array when no clock is set.
+      #
+      # @return [Array<Hash>] each entry: +{ fire_at:, description: }+
+      # @api private
+      def pending_timers
+        return [] unless @clock
+
+        @clock.pending_timer_entries
+      end
+
+      # Assert that the named tasks completed in the given order.
+      # Raises +RSpec::Expectations::ExpectationNotMetError+ if order is wrong.
+      # Intended for use inside RSpec examples.
+      #
+      # @param names [Array<String, nil>] task names in expected order
+      # @return [void]
+      # @api private
+      def assert_order(*names)
+        completed = @event_log.select { |e| e[:type] == :completed }.map { |e| e[:task_name] }
+        indices = names.map { |n| completed.index(n) }
+        unless indices.none?(&:nil?) && indices == indices.sort
+          raise RSpec::Expectations::ExpectationNotMetError,
+            "Expected tasks to complete in order #{names.inspect} " + "but completed order was #{completed.inspect}"
+        end
+      end
+
+      # Assert that the named tasks reached +:cancelled+ state.
+      #
+      # @param names [Array<String, nil>] task names expected to be cancelled
+      # @return [void]
+      # @api private
+      def assert_cancelled(*names)
+        cancelled = @event_log.select { |e| e[:type] == :cancelled }.map { |e| e[:task_name] }
+        missing = names.reject { |n| cancelled.include?(n) }
+        return if missing.empty?
+
+        raise RSpec::Expectations::ExpectationNotMetError,
+          "Expected tasks #{missing.inspect} to be cancelled " + "but cancelled tasks were #{cancelled.inspect}"
+      end
+
+      private
+
+      def _log_event(type, task_name)
+        at = @clock ? @clock.now : Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @mutex.synchronize { @event_log << {type: type, task_name: task_name, at: at} }
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/gate_registry.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Lazy cache of {ConcurrencyGate} instances, keyed by resource name.
+    #
+    # Gate concurrency caps are read from {Phronomy::Configuration} when a gate
+    # is first accessed; subsequent calls return the cached instance.  Call
+    # {#reset} to drop the cache and force a rebuild on the next access.
+    # @api private
+    class GateRegistry
+      GATE_CONFIG_MAP = {
+        agent: :max_concurrent_agent_tasks,
+        tool: :max_concurrent_tool_tasks,
+        workflow: :max_concurrent_workflow_tasks,
+        llm: :max_concurrent_llm_calls,
+        rag: :max_concurrent_rag_fetches,
+        vector: :max_concurrent_vector_searches
+      }.freeze
+      private_constant :GATE_CONFIG_MAP
+
+      def initialize
+        @mutex = Mutex.new
+        @gates = {}
+      end
+
+      # Returns (or lazily creates) the gate for +name+.
+      # @param name [Symbol]
+      # @return [ConcurrencyGate]
+      # @api private
+      def get(name)
+        @mutex.synchronize { @gates[name] ||= _build(name) }
+      end
+
+      # Drops the cached gate for +name+ so the next {#get} rebuilds it.
+      # @param name [Symbol]
+      # @return [void]
+      # @api private
+      def reset(name)
+        @mutex.synchronize { @gates.delete(name) }
+      end
+
+      private
+
+      def _build(name)
+        config_key = GATE_CONFIG_MAP[name]
+        max = config_key ? Phronomy.configuration.public_send(config_key) : nil
+        ConcurrencyGate.new(max_concurrent: max, name: name)
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/pool_registry.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Registry and lifecycle manager for {BlockingAdapterPool} instances.
+    #
+    # Maintains one unnamed "default" pool (accessed via {#default_pool}) and
+    # an arbitrary number of named pools (accessed via {#named_pool}).
+    # All pools are shut down together by {#shutdown}.
+    # @api private
+    class PoolRegistry
+      def initialize
+        @mutex = Mutex.new
+        @pools = {}
+        @default = nil
+      end
+
+      # Returns (or lazily creates) the unnamed default pool.
+      # @param pool_size  [Integer]
+      # @param queue_size [Integer]
+      # @return [BlockingAdapterPool]
+      # @api private
+      def default_pool(pool_size: 10, queue_size: 100)
+        @default ||= BlockingAdapterPool.new(
+          name: :default,
+          pool_size: pool_size,
+          queue_size: queue_size
+        )
+      end
+
+      # Returns (or lazily creates) a named pool.
+      # @param name      [Symbol, String]
+      # @param size      [Integer]
+      # @param queue_size [Integer]
+      # @return [BlockingAdapterPool]
+      # @api private
+      def named_pool(name, size: 10, queue_size: 100)
+        @mutex.synchronize do
+          @pools[name.to_sym] ||= BlockingAdapterPool.new(
+            name: name,
+            pool_size: size,
+            queue_size: queue_size
+          )
+        end
+      end
+
+      # Shuts down the default pool and all named pools.
+      # @return [void]
+      # @api private
+      def shutdown
+        @default&.shutdown
+        pools = @mutex.synchronize { @pools.values.dup }
+        pools.each(&:shutdown)
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/runtime_metrics.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Internal store for task-centric counters and latency samples.
+    #
+    # All access is mutex-protected.  The ring buffers for wait/run times are
+    # bounded to {WINDOW} samples so that long-lived runtimes do not grow
+    # unbounded.
+    # @api private
+    class RuntimeMetrics
+      WINDOW = 1000
+      private_constant :WINDOW
+
+      def initialize
+        @mutex = Mutex.new
+        @active_by_type = Hash.new(0)
+        @wait_ms = []
+        @run_ms = []
+        @cancelled = Hash.new(0)
+        @failed = Hash.new(0)
+        @starvation_count = 0
+      end
+
+      # Records that a new task of +type+ has been spawned.
+      # @param type [Symbol]
+      # @return [void]
+      # @api private
+      def record_start(type)
+        @mutex.synchronize { @active_by_type[type] += 1 }
+      end
+
+      # Appends a wait-time sample (milliseconds from spawn to start).
+      # @param wait_ms [Float]
+      # @return [void]
+      # @api private
+      def record_wait(wait_ms)
+        @mutex.synchronize do
+          @wait_ms << wait_ms
+          @wait_ms.shift if @wait_ms.size > WINDOW
+        end
+      end
+
+      # Records completion of a task (decrements active count, appends run time).
+      # @param type    [Symbol]
+      # @param outcome [:completed, :cancelled, :failed]
+      # @param run_start_ms [Integer] monotonic millisecond timestamp from task start
+      # @return [void]
+      # @api private
+      def record_end(type, outcome, run_start_ms)
+        run_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - run_start_ms
+        @mutex.synchronize do
+          @active_by_type[type] = [@active_by_type[type] - 1, 0].max
+          @run_ms << run_ms
+          @run_ms.shift if @run_ms.size > WINDOW
+          case outcome
+          when :cancelled then @cancelled[type] += 1
+          when :failed then @failed[type] += 1
+          end
+        end
+      end
+
+      # Increments the CPU-starvation counter (task ran without yielding over
+      # the configured +blocking_detect_threshold_ms+ threshold).
+      # @return [void]
+      # @api private
+      def increment_starvation
+        @mutex.synchronize { @starvation_count += 1 }
+      end
+
+      # Returns the current starvation counter value.
+      # @return [Integer]
+      # @api private
+      def starvation_count
+        @mutex.synchronize { @starvation_count }
+      end
+
+      # Returns the full task-centric metrics hash (see {Runtime#task_snapshot}).
+      # @return [Hash{Symbol => Numeric}]
+      # @api private
+      def snapshot
+        @mutex.synchronize do
+          active = @active_by_type.dup
+          wait = @wait_ms.dup
+          run = @run_ms.dup
+          cancelled = @cancelled.values.sum
+          failed = @failed.values.sum
+          starvation = @starvation_count
+          {
+            active_agent_tasks: active[:agent].to_i,
+            active_tool_tasks: active[:tool].to_i,
+            active_workflow_tasks: active[:workflow].to_i,
+            active_rag_tasks: active[:rag].to_i,
+            active_llm_tasks: active[:llm].to_i,
+            task_wait_time_p50_ms: _percentile(wait, 50),
+            task_wait_time_p95_ms: _percentile(wait, 95),
+            task_run_time_p50_ms: _percentile(run, 50),
+            task_run_time_p95_ms: _percentile(run, 95),
+            cancelled_tasks: cancelled,
+            failed_tasks: failed,
+            non_yield_threshold_violation_count: starvation
+          }
+        end
+      end
+
+      private
+
+      def _percentile(samples, pct)
+        return 0.0 if samples.empty?
+
+        sorted = samples.sort
+        idx = ((pct / 100.0) * (sorted.size - 1)).round
+        sorted[idx].round(3)
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/scheduler.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Abstract base class for Runtime scheduler backends.
+    #
+    # A scheduler is responsible for turning +Runtime#spawn+ calls into
+    # runnable {Task} objects.  Concrete subclasses decide whether tasks
+    # execute on threads, Fibers, or some other execution primitive.
+    #
+    # The interface is intentionally minimal: callers only see {Task}
+    # objects and never interact with the scheduler directly.
+    class Scheduler
+      # Thread-local key under which the active scheduler is stored.
+      # Shared with {Task::FiberBackend} (same symbol).
+      # @api private
+      SCHEDULER_KEY = :phronomy_deterministic_scheduler
+
+      # Returns the scheduler currently dispatching on this OS thread, or +nil+
+      # when running outside a cooperative (Fiber-based) scheduler context.
+      #
+      # Uses +Thread#thread_variable_get+ (not +Thread#[]+) so that the value is
+      # visible across all Fibers running on the same OS thread.
+      #
+      # @return [Scheduler, nil]
+      # @api private
+      def self.current
+        Thread.current.thread_variable_get(SCHEDULER_KEY)
+      end
+
+      # Creates a new scheduler-aware signal object for this scheduler.
+      # Signalling primitives use this instead of +ConditionVariable+ when a
+      # cooperative scheduler is active.
+      #
+      # Default implementation raises +NotImplementedError+.  Subclasses that
+      # support cooperative suspension (e.g. {DeterministicScheduler}) must
+      # override this.
+      #
+      # @return [Object] an opaque signal handle understood by {#wait_for_signal}
+      #   and {#raise_signal}
+      # @api private
+      def new_signal
+        raise NotImplementedError, "#{self.class}#new_signal is not implemented"
+      end
+
+      # Suspends the current execution unit (Fiber or Thread) until +signal+ is
+      # raised via {#raise_signal}.
+      #
+      # @param signal [Object] signal handle returned by {#new_signal}
+      # @return [void]
+      # @api private
+      def wait_for_signal(signal)
+        raise NotImplementedError, "#{self.class}#wait_for_signal is not implemented"
+      end
+
+      # Wakes up one waiter suspended on +signal+.
+      #
+      # @param signal [Object] signal handle returned by {#new_signal}
+      # @return [void]
+      # @api private
+      def raise_signal(signal)
+        raise NotImplementedError, "#{self.class}#raise_signal is not implemented"
+      end
+
+      # Wakes up all waiters suspended on +signal+.
+      #
+      # @param signal [Object] signal handle returned by {#new_signal}
+      # @return [void]
+      # @api private
+      def raise_signal_all(signal)
+        raise NotImplementedError, "#{self.class}#raise_signal_all is not implemented"
+      end
+
+      # Spawns a new task.
+      #
+      # @param name   [String, nil] optional human-readable label
+      # @param parent [Task, nil]   parent task for cancellation propagation
+      # @yield block to execute concurrently (or synchronously, depending on
+      #   the concrete scheduler)
+      # @return [Task]
+      # @api private
+      def spawn(name:, parent:, &block)
+        raise NotImplementedError, "#{self.class}#spawn is not implemented"
+      end
+
+      # Cooperative yield point.
+      #
+      # Default implementation is a no-op.  Thread-based subclasses should
+      # override with +Thread.pass+; fiber-based subclasses should switch to the
+      # next runnable fiber.
+      # @return [void]
+      # @api private
+      def yield
+        # no-op by default; subclasses override
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/scheduler_timer_adapter.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # A drop-in replacement for {TimerQueue} that delegates timer scheduling to
+    # a {DeterministicScheduler} instead of spawning a dedicated background OS thread.
+    #
+    # When a {Runtime} is backed by {DeterministicScheduler} (e.g. the +:fiber+
+    # runtime backend), {Runtime#timer_queue} returns an instance of this adapter
+    # rather than a {TimerQueue}.  This eliminates the +phronomy-timer-queue+
+    # background thread for Fiber-based runtimes.
+    #
+    # Timer callbacks are fired during {DeterministicScheduler#run_until_idle}
+    # when {DeterministicScheduler#autorun?} is +true+ (i.e. the +:fiber+ backend).
+    # They can also be fired explicitly by calling
+    # {DeterministicScheduler#fire_real_timers}.
+    #
+    # == Known Limitation (Issue #331)
+    #
+    # Timers that require an actual wall-clock sleep (e.g. a deadline of 10 s
+    # from now that will not be reached until real time elapses) will not fire
+    # automatically: +run_until_idle+ does not block waiting for future deadlines.
+    # This is an accepted limitation of the current stepping-stone implementation.
+    # Full resolution requires integrating the cooperative scheduler with the
+    # {EventLoop} tick cycle so that a single event-loop iteration checks both
+    # ready Fibers and expired wall-clock timers.
+    #
+    # Use the +:thread+ runtime backend (default) for production workloads that
+    # depend on real-time deadline enforcement.
+    #
+    # @see DeterministicScheduler#schedule_real_after
+    # @see DeterministicScheduler#fire_real_timers
+    # Bridges wall-clock timers to the cooperative {DeterministicScheduler}.
+    #
+    # Registers a recurring timer callback with the scheduler's {TimerQueue}
+    # so that Fiber-based tasks can await real time without blocking OS threads.
+    # @api private
+    class SchedulerTimerAdapter
+      # @param scheduler [DeterministicScheduler]
+      # @api private
+      def initialize(scheduler)
+        @scheduler = scheduler
+      end
+
+      # Schedules a one-shot callback to fire after +seconds+ from now.
+      # Delegates to {DeterministicScheduler#schedule_real_after}.
+      #
+      # Raises {PoolShutdownError} after {#shutdown} has been called, matching
+      # the behaviour of {TimerQueue#schedule}.
+      #
+      # @param seconds [Numeric] delay before the callback fires
+      # @yield called when the deadline is reached
+      # @return [self]
+      # @api private
+      def schedule(seconds:, &callback)
+        raise Phronomy::PoolShutdownError, "SchedulerTimerAdapter has been shut down" if @stopped
+
+        @scheduler.schedule_real_after(seconds, &callback)
+        self
+      end
+
+      # No-op: there is no background thread to stop.
+      # Present for API compatibility with {TimerQueue}.
+      # @return [self]
+      # @api private
+      def shutdown
+        @stopped = true
+        self
+      end
+
+      # Returns the number of pending (not yet fired) callbacks.
+      # @return [Integer]
+      # @api private
+      def pending_count
+        @scheduler.pending_real_timer_count
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/task_registry.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # 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.
+    # @api private
+    class TaskRegistry
+      def initialize
+        @mutex = Mutex.new
+        @tasks = []
+      end
+
+      # Adds +task+ to the registry unless it already completed synchronously.
+      # @param task [Task]
+      # @return [void]
+      # @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]
+      # @api private
+      def deregister(task)
+        @mutex.synchronize { @tasks.delete(task) }
+      end
+
+      # Waits for all registered tasks to finish (used by {Runtime#shutdown}).
+      # @return [void]
+      # @api private
+      def drain
+        tasks = @mutex.synchronize { @tasks.dup }
+        tasks.each do |t|
+          t.join
+        rescue
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/thread_scheduler.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Thread-based scheduler: spawns each task in a new OS thread.
+    #
+    # This is the default scheduler used by {Runtime} in production.
+    # It delegates directly to {Task.spawn} with the default
+    # {Task::ThreadBackend}, preserving the pre-282 behaviour exactly.
+    # @api private
+    class ThreadScheduler < Scheduler
+      # Spawns +block+ as a new {Task} backed by a Thread.
+      #
+      # @param name   [String, nil]
+      # @param parent [Task, nil]
+      # @return [Task]
+      # @api private
+      def spawn(name:, parent:, &block)
+        Task.spawn(name: name, parent: parent, &block)
+      end
+
+      # Yields the current thread's time slice to other runnable threads.
+      # @return [void]
+      # @api private
+      def yield
+        Thread.pass
+      end
+    end
+  end
+end