phronomy 0.7.0 → 0.8.0

data/lib/phronomy/runtime.rb

@@ -0,0 +1,389 @@
+# frozen_string_literal: true
+
+require_relative "runtime/scheduler"
+require_relative "runtime/thread_scheduler"
+require_relative "runtime/fake_scheduler"
+require_relative "runtime/deterministic_scheduler"
+require_relative "runtime/timer_queue"
+require_relative "runtime/scheduler_timer_adapter"
+require_relative "runtime/task_registry"
+require_relative "runtime/runtime_metrics"
+require_relative "runtime/timer_service"
+
+module Phronomy
+  # Central authority for concurrent primitives.
+  #
+  # +Runtime+ is the single place that creates {Task}s, {TaskGroup}s, and
+  # manages the lifecycle of all concurrency in Phronomy.  It owns:
+  #
+  # * a pluggable {Scheduler} (default: {ThreadScheduler})
+  # * a task registry for graceful shutdown
+  # * the shared {BlockingAdapterPool}
+  #
+  # In production, use the process-wide singleton via {.instance}.
+  # In tests, construct a Runtime with a {FakeScheduler} to run tasks
+  # synchronously without spawning additional threads:
+  #
+  # @example Production usage
+  #   group = Phronomy::Runtime.instance.task_group(limit: 4)
+  #   tools.each { |t| group.spawn { t.call } }
+  #   results = group.await_all
+  #
+  # @example Test usage — no extra threads
+  #   runtime = Phronomy::Runtime.new(scheduler: Phronomy::Runtime::FakeScheduler.new)
+  #   task = runtime.spawn { 42 }
+  #   expect(task.await).to eq(42)
+  class Runtime
+    # Returns the process-wide default Runtime.
+    #
+    # Auto-creates an instance using the scheduler backend specified by
+    # +Phronomy.configuration.runtime_backend+:
+    # - +:thread+ (default) — {ThreadScheduler} (one OS thread per task)
+    # - +:immediate+ — {FakeScheduler} (synchronous, no extra threads)
+    # - +:fiber+ — {DeterministicScheduler} in autorun mode (EXPERIMENTAL;
+    #   Fiber-based synchronous execution; not yet suitable for production
+    #   because it uses virtual time rather than real wall-clock timers)
+    # - +:cooperative+ — deprecated alias for +:immediate+
+    #
+    # @return [Runtime]
+    # @api private
+    def self.instance
+      @instance ||= begin
+        scheduler = case Phronomy.configuration.runtime_backend
+        when :cooperative
+          Phronomy.configuration.logger&.warn(
+            "[phronomy] runtime_backend: :cooperative is a deprecated alias for :immediate. " \
+            "Use :immediate for synchronous/test execution. " \
+            ":cooperative will be reassigned when a real cooperative Fiber-based scheduler is available."
+          )
+          FakeScheduler.new
+        when :immediate
+          FakeScheduler.new
+        when :fiber
+          Phronomy.configuration.logger&.warn(
+            "[phronomy] runtime_backend: :fiber uses DeterministicScheduler in autorun mode. " \
+            "This is an EXPERIMENTAL Fiber-based cooperative scheduler. " \
+            "Wall-clock timer integration is available via SchedulerTimerAdapter (Issues #331, #337). " \
+            "Not recommended for production use."
+          )
+          DeterministicScheduler.new(autorun: true)
+        else
+          ThreadScheduler.new
+        end
+        new(scheduler: scheduler)
+      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.
+    #
+    # Use this to detect potential scheduler-blocking calls:
+    #   if Phronomy::Runtime.in_scheduler_context?
+    #     Phronomy.configuration.logger&.warn("blocking call inside scheduler task")
+    #   end
+    #
+    # @return [Boolean]
+    # @api private
+    def self.in_scheduler_context?
+      !Task.current.nil?
+    end
+
+    # Executes +block+ and returns +[result, elapsed_ms]+ where +elapsed_ms+
+    # is the wall-clock duration in milliseconds (Integer, rounded).
+    #
+    # Isolates all direct references to +Process.clock_gettime+ /
+    # +Process::CLOCK_MONOTONIC+ in one place so that callers stay at the
+    # framework abstraction level.
+    #
+    # @yield block to time
+    # @return [Array(Object, Integer)] +[block_return_value, elapsed_ms]+
+    # @api private
+    def self.measure_ms
+      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = yield
+      elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round
+      [result, elapsed_ms]
+    end
+
+    # The scheduler backing this runtime instance.
+    # @return [Scheduler]
+    attr_reader :scheduler
+
+    # @param scheduler [Scheduler] execution backend (default: {ThreadScheduler})
+    # @api private
+    def initialize(scheduler: ThreadScheduler.new)
+      @scheduler = scheduler
+      @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, :rag, :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)
+    end
+
+    # Cooperative yield point.
+    #
+    # Signals the scheduler that the current task is willing to give up CPU time
+    # so that other ready tasks can run.  On the default {ThreadScheduler} this
+    # calls +Thread.pass+.  On a future fiber-based scheduler this would switch
+    # to the next runnable fiber.
+    #
+    # When +blocking_detect_threshold_ms+ is configured, checks whether the
+    # current task has exceeded that threshold without yielding; if so, emits a
+    # warning via the configured logger and increments
+    # +non_yield_threshold_violation_count+.
+    #
+    # Call this inside tight loops or CPU-intensive sections of tool +execute+
+    # methods and Workflow actions to keep the scheduler responsive.
+    #
+    # @return [void]
+    # @api private
+    def yield
+      if (threshold = Phronomy.configuration.blocking_detect_threshold_ms)
+        slice_start = Task.current_cpu_slice_start_ms
+        if slice_start
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - slice_start
+          if elapsed > threshold
+            name = Task.current&.name || "unknown"
+            Phronomy.configuration.logger&.warn(
+              "[Phronomy] CPU-bound task detected: '#{name}' ran #{elapsed.round}ms " \
+              "without yielding (threshold: #{threshold}ms)"
+            )
+            @metrics.increment_starvation
+          end
+        end
+      end
+      Task.record_yield!
+      @scheduler.yield
+    end
+
+    # Number of times a task has exceeded the CPU-bound detection threshold
+    # (i.e. ran longer than +blocking_detect_threshold_ms+ without yielding).
+    # Resets to 0 when the Runtime is recreated.
+    # @return [Integer]
+    # @api private
+    def non_yield_threshold_violation_count
+      @metrics.starvation_count
+    end
+
+    # Cooperative yield point with a call-count gate.
+    #
+    # Increments a per-thread counter and calls {#yield} when the counter
+    # reaches a multiple of +every+.  The counter is thread-local so concurrent
+    # tasks each maintain their own independent loop counter without requiring
+    # a mutex.
+    #
+    # @example
+    #   data.each_with_index do |row, i|
+    #     process(row)
+    #     Phronomy::Runtime.instance.yield_if_needed(every: 500)
+    #   end
+    #
+    # @param every [Integer] yield once every N calls (default: 1000)
+    # @return [void]
+    # @api private
+    def yield_if_needed(every: 1000)
+      # Delegate Thread.current access to Task so that runtime.rb stays outside
+      # the Thread.current allowlist (Issue #302).
+      self.yield if (Task.increment_yield_counter! % every).zero?
+    end
+
+    # Creates a new {TaskGroup} with an optional concurrency cap.
+    #
+    # @param limit          [Integer, Float::INFINITY] max simultaneous tasks
+    # @param failure_policy [Symbol] one of :fail_fast, :collect_all, :skip_failed (default :fail_fast)
+    # @return [TaskGroup]
+    # @api private
+    def task_group(limit: Float::INFINITY, failure_policy: :fail_fast)
+      TaskGroup.new(limit: limit, failure_policy: failure_policy, runtime: self)
+    end
+
+    # Spawns a single {Task} using the runtime's scheduler.
+    #
+    # The spawned task is registered in the task registry so {#shutdown}
+    # can wait for it to complete.  The task is automatically deregistered
+    # from the registry when it finishes (success, failure, or cancellation)
+    # so long-lived runtimes do not accumulate stale references.
+    #
+    # Task names beginning with a recognised type prefix are counted in the
+    # task-centric metrics returned by {#task_snapshot}.  Recognised prefixes:
+    # +agent-+, +tool-+, +workflow-+, +rag-+, +llm-+, +vector-+.
+    #
+    # @param name [String, nil] optional label for debugging
+    # @yield block to execute (concurrently or synchronously, depending on
+    #   the configured scheduler)
+    # @return [Task]
+    # @api private
+    def spawn(name: nil, &block)
+      type = _task_type(name)
+      spawn_at = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+      @metrics.record_start(type)
+
+      task = @scheduler.spawn(name: name, parent: Task.current) do
+        run_start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+        @metrics.record_wait(run_start - spawn_at)
+        begin
+          result = block.call
+          @metrics.record_end(type, :completed, run_start)
+          result
+        rescue CancellationError
+          @metrics.record_end(type, :cancelled, run_start)
+          raise
+        rescue => e
+          @metrics.record_end(type, :failed, run_start)
+          raise e
+        ensure
+          current = Task.current
+          @task_registry.deregister(current) if current
+        end
+      end
+      @task_registry.register(task)
+      task
+    end
+
+    # Returns a snapshot of task-centric metrics for the current Runtime.
+    #
+    # | Key | Description |
+    # |-----|-------------|
+    # | `active_agent_tasks`      | currently running agent spawns |
+    # | `active_tool_tasks`       | currently running tool spawns |
+    # | `active_workflow_tasks`   | currently running workflow spawns |
+    # | `active_rag_tasks`        | currently running RAG fetches |
+    # | `active_llm_tasks`        | currently running LLM calls |
+    # | `task_wait_time_p50_ms`   | p50 spawn-to-start latency (ms) |
+    # | `task_wait_time_p95_ms`   | p95 spawn-to-start latency (ms) |
+    # | `task_run_time_p50_ms`    | p50 execution duration (ms) |
+    # | `task_run_time_p95_ms`    | p95 execution duration (ms) |
+    # | `cancelled_tasks`         | total cancelled task count |
+    # | `failed_tasks`            | total failed task count |
+    # | `non_yield_threshold_violation_count` | cumulative count of tasks that ran past `blocking_detect_threshold_ms` without yielding |
+    #
+    # @return [Hash{Symbol => Numeric}]
+    # @api private
+    def task_snapshot
+      @metrics.snapshot
+    end
+
+    # Returns the shared {BlockingAdapterPool} for this Runtime.
+    # All blocking I/O (LLM HTTP, MCP, ActiveRecord, Redis) should be
+    # submitted through this pool.
+    #
+    # Pool settings default to 10 workers / 100-deep queue.  Override by
+    # 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)
+    # @return [BlockingAdapterPool]
+    # @api private
+    def blocking_io(pool_size: 10, queue_size: 100)
+      @pool_registry.default_pool(pool_size: pool_size, queue_size: queue_size)
+    end
+
+    # Returns (or lazily creates) a named {BlockingAdapterPool}.
+    #
+    # Named pools allow per-subsystem thread-budget control and observability.
+    # Recommended pool names: +:llm+, +:mcp+, +:db+, +:redis+, +:tool+.
+    # Each pool gets its own dedicated worker threads labelled with the pool name.
+    #
+    # @example
+    #   runtime.pool(:llm)            # default size (10 workers)
+    #   runtime.pool(:db, size: 20)   # custom size
+    #
+    # @param name      [Symbol, String] pool identifier
+    # @param size      [Integer] worker thread count (default: 10)
+    # @param queue_size [Integer] max pending operations (default: 100)
+    # @return [BlockingAdapterPool]
+    # @api private
+    def pool(name, size: 10, queue_size: 100)
+      @pool_registry.named_pool(name, size: size, queue_size: queue_size)
+    end
+
+    # Returns the shared timer queue for this Runtime.
+    #
+    # When the scheduler is a {DeterministicScheduler} (e.g. the +:fiber+
+    # runtime backend), returns a {SchedulerTimerAdapter} that integrates with
+    # the scheduler's tick cycle instead of spawning a background OS thread.
+    # This is the first concrete step of the TimerQueue scheduler-tick integration
+    # described in ADR-010 (Issue #331).
+    #
+    # For all other schedulers, returns a {TimerQueue} backed by a single
+    # background thread.
+    #
+    # All deadline-based cancellation should be registered here instead of
+    # spawning one-off sleep threads.  Lazily created on first access.
+    #
+    # @return [TimerQueue, SchedulerTimerAdapter]
+    # @api private
+    def timer_queue
+      @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]
+    # @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.
+      if Phronomy.configuration.event_loop
+        Phronomy::EventLoop.instance.stop(drain: true)
+      end
+      @pool_registry.shutdown
+      @timer_service.shutdown
+    end
+
+    private
+
+    TASK_TYPE_PREFIXES = %w[agent tool workflow rag llm vector].freeze
+    private_constant :TASK_TYPE_PREFIXES
+
+    def _task_type(name)
+      return :other if name.nil?
+
+      prefix = TASK_TYPE_PREFIXES.find { |p| name.to_s.start_with?("#{p}-") }
+      prefix ? prefix.to_sym : :other
+    end
+  end
+end

data/lib/phronomy/splitter.rb

@@ -4,9 +4,9 @@ module Phronomy
   # Text splitter implementations for chunking documents before embedding.
   #
   # Sub-classes are auto-loaded by Zeitwerk:
-  #   Phronomy::Splitter::Base
-  #   Phronomy::Splitter::FixedSizeSplitter
-  #   Phronomy::Splitter::RecursiveSplitter
+  #   Phronomy::Agent::Context::Knowledge::Splitter::Base
+  #   Phronomy::Agent::Context::Knowledge::Splitter::FixedSizeSplitter
+  #   Phronomy::Agent::Context::Knowledge::Splitter::RecursiveSplitter
   module Splitter
   end
 end

data/lib/phronomy/task/backend.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Task
+    # Abstract base class for Task execution backends.
+    #
+    # A backend encapsulates the execution primitive (Thread, Fiber, etc.) and
+    # the lifecycle transitions it drives.  Concrete backends must implement all
+    # abstract methods.  The default concrete implementation is {ThreadBackend}.
+    #
+    # Backends receive a reference to the owning {Task} so they can call
+    # {Task#transition!} at the appropriate lifecycle points.
+    class Backend
+      # @param task  [Task] the owning Task (used for status callbacks)
+      # @param block [Proc] the work to execute
+      # @api private
+      def initialize(task:, &block)
+        @task = task
+        @block = block
+      end
+
+      # Blocks until the task completes and returns its value.
+      # Re-raises errors from the block.
+      # @return [Object]
+      # @raise [Exception]
+      # @api private
+      def await
+        raise NotImplementedError, "#{self.class}#await not implemented"
+      end
+
+      # Returns +true+ while execution is still ongoing.
+      # @return [Boolean]
+      # @api private
+      def alive?
+        raise NotImplementedError, "#{self.class}#alive? not implemented"
+      end
+
+      # Requests cancellation.
+      # Thread-based backends may use +Thread#raise+; cooperative backends
+      # should mark the task cancelled and rely on {Task.checkpoint!}.
+      # @return [self]
+      # @api private
+      def cancel!
+        raise NotImplementedError, "#{self.class}#cancel! not implemented"
+      end
+
+      # Joins the execution context with an optional timeout.
+      # Returns +nil+ when a non-nil +limit+ expires before completion,
+      # matching +Thread#join+ semantics.
+      # @param limit [Numeric, nil]
+      # @return [Object, nil]
+      # @api private
+      def join(limit = nil)
+        raise NotImplementedError, "#{self.class}#join not implemented"
+      end
+
+      # Returns the task's result value once it has reached a terminal state.
+      # Only valid to call after the task is done.
+      # Subclasses should override if they store the result.
+      # @return [Object, nil]
+      # @api private
+      def completed_value
+        nil
+      end
+
+      # Returns the exception raised by the task, or +nil+ on success/cancellation.
+      # Only valid to call after the task is done.
+      # Subclasses should override if they store errors.
+      # @return [Exception, nil]
+      # @api private
+      def completed_error
+        nil
+      end
+
+      private
+
+      attr_reader :task, :block
+    end
+  end
+end

data/lib/phronomy/task/fiber_backend.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Task
+    # Cooperative task backend using Ruby Fibers.
+    #
+    # Unlike {ImmediateBackend} (which runs the block to completion on the
+    # calling thread) or {ThreadBackend} (which runs the block on a new OS
+    # thread), +FiberBackend+ wraps the block in a +Fiber+ that is NOT started
+    # immediately.  The owning scheduler calls {#step} to advance execution one
+    # cooperative step at a time.
+    #
+    # This backend is used exclusively by {Runtime::DeterministicScheduler} to
+    # enable deterministic, wall-clock-free testing of concurrent logic.
+    #
+    # Thread-local key under which the currently active {DeterministicScheduler}
+    # is stored so that {#await} can suspend cooperatively.
+    SCHEDULER_KEY = :phronomy_deterministic_scheduler
+
+    # @api private
+    class FiberBackend < Backend
+      def initialize(task:, &block)
+        super
+        @value = nil
+        @error = nil
+        @cancel_error = nil
+        @cancel_requested = false
+        @started = false
+        @cooperative_suspend = false
+
+        # Capture `self` (the FiberBackend instance) in the closure so that
+        # instance-variable writes from inside the Fiber update this object.
+        @fiber = Fiber.new do
+          task.transition!(:running)
+          begin
+            # If cancel! was called before the first step, raise immediately.
+            raise @cancel_error if @cancel_error
+
+            @value = block.call
+            task.transition!(:completed, value: @value)
+          rescue CancellationError => e
+            task.transition!(:cancelled, error: e)
+            @error = e
+          rescue => e
+            task.transition!(:failed, error: e)
+            @error = e
+          ensure
+            task.transition!(:cancelled) unless task.done?
+          end
+        end
+      end
+
+      # Advances execution by one scheduler step.
+      # Resumes the Fiber until it yields (via +Fiber.yield+) or finishes.
+      # Cooperative cancellation is checked at the start of each step: if
+      # +cancel!+ has been called, +CancellationError+ is raised inside the
+      # Fiber at this controlled checkpoint rather than injected at an
+      # arbitrary suspension point via +Fiber#raise+.
+      # @return [self]
+      # @api private
+      def step
+        return self unless @fiber.alive?
+
+        @started = true
+        # Deliver pending cancellation at this scheduler checkpoint rather than
+        # injecting it mid-Fiber via Fiber#raise (which would be preemptive).
+        if @cancel_requested && @cancel_error
+          begin
+            @fiber.raise(@cancel_error)
+          rescue FiberError
+            nil  # Fiber completed between the check and raise — safe to ignore.
+          end
+          @cancel_requested = false
+          return self
+        end
+        yield_value = @fiber.resume
+        # A yield value of :cooperative_suspend signals that the Fiber deliberately
+        # suspended itself (e.g. inside CoopSignal#wait) and must NOT be
+        # re-enqueued by step_callable — it will be resumed by an explicit signal.
+        @cooperative_suspend = (yield_value == :cooperative_suspend)
+        self
+      end
+
+      # Returns +true+ if the Fiber yielded cooperatively (via a signal wait)
+      # and should not be automatically re-enqueued by the scheduler.
+      # @return [Boolean]
+      # @api private
+      def cooperative_suspend?
+        @cooperative_suspend
+      end
+
+      # Blocks until the task completes.
+      #
+      # When called from within a {DeterministicScheduler}-managed Fiber,
+      # suspends the current Fiber cooperatively and schedules it to resume
+      # when this task completes.  When called from outside a managed Fiber
+      # (e.g. the main fiber or a regular thread), drives execution by calling
+      # {#step} in a loop.
+      #
+      # @return [Object]
+      # @raise [Exception]
+      # @api private
+      def await
+        unless @fiber.alive?
+          raise @error if @error
+          return @value
+        end
+
+        scheduler = Thread.current.thread_variable_get(SCHEDULER_KEY)
+        # Fiber.main was added in Ruby 3.2.4+; fall back to true (assume we are
+        # inside a managed Fiber whenever a scheduler is active).
+        in_managed_fiber = !Fiber.respond_to?(:main) || Fiber.current != Fiber.main
+        if scheduler && in_managed_fiber
+          # Cooperative context: suspend current Fiber until task is done.
+          waiting_fiber = Fiber.current
+          @task.on_complete { scheduler.enqueue_fiber(-> { waiting_fiber.resume }) }
+          Fiber.yield(:cooperative_suspend)
+        else
+          # Non-cooperative context: drive the fiber to completion.
+          step while @fiber.alive?
+        end
+
+        raise @error if @error
+        @value
+      end
+
+      # @return [Boolean] +true+ while the Fiber has not yet finished
+      # @api private
+      def alive?
+        @fiber.alive?
+      end
+
+      # Requests cancellation using a cooperative checkpoint mechanism.
+      # Sets a cancellation flag; the error is raised inside the Fiber at the
+      # next +step+ call (i.e. when the scheduler next dispatches this task),
+      # not injected at an arbitrary suspension point via +Fiber#raise+.
+      # If the Fiber has not yet started, the error is recorded so it is raised
+      # on the first {#step}.
+      # @return [self]
+      # @api private
+      def cancel!
+        @cancel_error = CancellationError.new("Task cancelled")
+        @cancel_requested = true
+        self
+      end
+
+      # Joins execution by stepping until the Fiber is no longer alive.
+      # @param limit [Numeric, nil] ignored
+      # @return [self]
+      # @api private
+      def join(_limit = nil)
+        step while @fiber.alive?
+        self
+      end
+    end
+  end
+end