phronomy 0.7.1 → 0.8.0

data/lib/phronomy/workflow_context.rb

@@ -70,6 +70,7 @@ module Phronomy
     #   :<state>           — resuming at <state> (workflow paused before its execution)
     # @return [Symbol]
     # @api public
+    # mutant:disable - @phase is always non-nil (set to :__end__ in initialize, only changed by set_graph_metadata which never sets nil), so the || :__end__ fallback branch is never reached — all mutations of the right-hand side are genuine equivalents
     def phase
       @phase || :__end__
     end
@@ -77,6 +78,7 @@ module Phronomy
     # Returns true if the workflow is paused mid-execution (not yet completed).
     # @return [Boolean]
     # @api public
+    # mutant:disable - phase != :__end__ vs !phase.eql?(:__end__) vs !phase.equal?(:__end__) are genuine equivalents for Symbol (Symbols are interned so == / eql? / equal? all behave identically)
     def halted?
       phase != :__end__
     end
@@ -85,12 +87,14 @@ module Phronomy
     # @param thread_id [String, nil]
     # @param phase [Symbol, nil]
     # @api public
+    # mutant:disable - mutations replacing return value `self` with nil or removing the last line are genuine equivalents: callers chain on the return value only in merge which immediately discards it
     def set_graph_metadata(thread_id: nil, phase: nil)
       @thread_id = thread_id unless thread_id.nil?
       @phase = phase unless phase.nil?
       self
     end
 
+    # mutant:disable - multiple genuine equivalent mutations: is_a?(Proc) vs instance_of?(Proc) (Proc has no subclasses in practice), config[]/fetch() for always-present :default key, @thread_id=nil removal (unset ivar is already nil), @phase=:__end__ → nil or removal (phase method returns :__end__ via @phase||:__end__ fallback), raise message #{.inspect} vs #{} (spec checks exception class not message text)
     def initialize(**attrs)
       unknown = attrs.keys - self.class.fields.keys
       raise ArgumentError, "Unknown WorkflowContext field(s): #{unknown.inspect}" unless unknown.empty?
@@ -114,6 +118,7 @@ module Phronomy
     # @return [self.class] new context instance
     # @raise [ArgumentError] if updates contains keys that are not declared fields
     # @api public
+    # mutant:disable - multiple genuine equivalent mutations: send/public_send/__send__ are identical (all field accessors are public), fields[]/fetch() and field_config[]/fetch() for always-present keys, updates[]/fetch() when updates.key?(name) is already true, Array() wrapping for append fields that always hold Arrays, (send||{})/send equivalence for merge fields that always hold Hashes, deep_dup_value(send) vs send are equivalent under killfork (coverage selection does not trace the deep_dup_value call site across the fork boundary), raise message inspect vs to_s (spec checks exception class only)
     def merge(updates)
       unknown = updates.keys - self.class.fields.keys
       raise ArgumentError, "Unknown WorkflowContext field(s): #{unknown.inspect}" unless unknown.empty?
@@ -145,6 +150,7 @@ module Phronomy
     # Converts user-defined fields to a Hash (excludes internal workflow metadata).
     # @return [Hash]
     # @api public
+    # mutant:disable - send/public_send/__send__ are genuine equivalents (all field accessors are public methods)
     def to_h
       self.class.fields.keys.each_with_object({}) do |name, h|
         h[name] = send(name)
@@ -158,6 +164,7 @@ module Phronomy
     # @raise [Phronomy::WorkflowContextOwnershipError] when called from a
     #   non-EventLoop thread in EventLoop mode.
     # @api private
+    # mutant:disable - multiple genuine equivalent mutations: defined?(Phronomy::EventLoop)&& removal is genuine because EventLoop is always loaded in the killfork environment; true&& is genuine (truthy guard); EventLoop.current? resolves to Phronomy::EventLoop.current? within the Phronomy module; WorkflowContextOwnershipError resolves to Phronomy::WorkflowContextOwnershipError within the module; raise without message or with nil message is genuine (spec checks exception class, not message text)
     def _assert_write_permitted!
       return unless defined?(Phronomy::EventLoop) &&
         Phronomy.configuration.event_loop
@@ -174,6 +181,7 @@ module Phronomy
     # Immutable values (nil, Symbol, Integer, Float, true/false, frozen String) are returned as-is.
     # Other objects are dup'd (best-effort shallow copy for custom types).
     # Objects that cannot be dup'd (e.g. Proc, Method) are returned as-is.
+    # mutant:disable - multiple genuine equivalent mutations: each class in the when clause (NilClass/Symbol/Integer/Float/TrueClass/FalseClass) can be removed or replaced with nil because all those types are frozen so the else-branch val.frozen? guard returns the same result; return val vs val is also equivalent; if val.frozen? vs if self.frozen? is equivalent since self is never frozen in this context
     def deep_dup_value(val)
       case val
       when Array

data/lib/phronomy/workflow_runner.rb

@@ -56,7 +56,16 @@ module Phronomy
       @wait_state_names = wait_state_names
       @state_store = state_store
       @action_timeouts = action_timeouts   # { state_name => seconds }
-      @phase_machine_class = build_phase_machine_class(auto_transitions, exit_actions)
+      @phase_machine_class = Agent::Lifecycle::PhaseMachineBuilder.new(
+        entry_point: @entry_point,
+        declared_states: @declared_states,
+        wait_state_names: @wait_state_names,
+        external_events: @external_events,
+        entry_actions: @entry_actions,
+        action_timeouts: @action_timeouts,
+        auto_transitions: auto_transitions,
+        exit_actions: exit_actions
+      ).build
     end
 
     # Executes the workflow from the initial state.
@@ -160,7 +169,7 @@ module Phronomy
 
     # Builds an FSMSession for the given context. Used in EventLoop mode.
     def build_session_for(context:, recursion_limit:, resume_event: nil, resume_phase: nil)
-      Phronomy::FSMSession.new(
+      Phronomy::Agent::Lifecycle::FSMSession.new(
         id: context.thread_id,
         context: context,
         entry_point: @entry_point,
@@ -310,135 +319,6 @@ module Phronomy
     #   before_transition from — exit callbacks (invoked when leaving a state)
     #
     # Guard lambdas bridge the PhaseTracker and WorkflowContext via +m.context+.
-    def build_phase_machine_class(auto_transitions, exit_actions)
-      entry = @entry_point
-      all_states = (@declared_states + @wait_state_names + [:__end__]).uniq
-      auto_trans = auto_transitions  # Array of { from:, to:, guard: }
-      ext_events = @external_events
-      entry_acts = @entry_actions
-      exit_acts = exit_actions
-      act_timeouts = @action_timeouts  # { state_name => seconds }
-
-      Class.new do
-        # Holds the current WorkflowContext so guards and callbacks can read it.
-        attr_accessor :context
-
-        # Set to true by an entry action that returned an awaitable Task.
-        # When true, FSMSession skips the automatic advance_or_halt step and
-        # waits for the async worker thread to post a state_completed event back.
-        attr_accessor :async_pending
-
-        state_machine :phase, initial: entry do
-          all_states.each { |s| state s }
-
-          # Auto-fire transitions: all auto transitions unified under :state_completed.
-          # Includes unguarded (unconditional) and guarded (conditional) transitions.
-          # Declaration order is preserved; guards are evaluated before unguarded fallbacks.
-          event :state_completed do
-            auto_trans.each do |t|
-              if t[:guard]
-                guard_proc = t[:guard]
-                transition t[:from] => t[:to], :if => ->(m) { guard_proc.call(m.context) }
-              else
-                transition t[:from] => t[:to]
-              end
-            end
-          end
-
-          # External events: human-in-the-loop triggers from wait states.
-          ext_events.each do |ev_name, transitions|
-            event ev_name do
-              transitions.each do |t|
-                if t[:guard]
-                  guard_proc = t[:guard]
-                  transition t[:from] => t[:to], :if => ->(m) { guard_proc.call(m.context) }
-                else
-                  transition t[:from] => t[:to]
-                end
-              end
-            end
-          end
-
-          # Entry callbacks: fire after_transition into each state.
-          #    Each callable is registered as a separate callback; state_machines
-          #    accumulates them and fires in declaration order.
-          #    If the callable returns a WorkflowContext (e.g. via s.merge(...)),
-          #    the returned context replaces the current one on the tracker.
-          entry_acts.each do |state_name, callables|
-            callables.each do |callable|
-              timeout_secs = act_timeouts[state_name]
-              after_transition to: state_name do |machine|
-                result = callable.call(machine.context)
-                if result.is_a?(Phronomy::Task)
-                  if Phronomy.configuration.event_loop
-                    # EventLoop mode: await in a background task so the EventLoop
-                    # thread is not blocked. Signal async_pending so FSMSession
-                    # skips the automatic advance_or_halt step.
-                    machine.async_pending = true
-                    ctx_ref = machine.context
-                    thread_id = ctx_ref.thread_id
-                    Phronomy::Runtime.instance.spawn(name: "wf-await-#{thread_id}") do
-                      if timeout_secs
-                        if result.join(timeout_secs).nil?
-                          result.cancel!
-                          raise Phronomy::ActionTimeoutError,
-                            "Action in state #{state_name.inspect} timed out after #{timeout_secs}s"
-                        end
-                      end
-                      task_result = result.await
-                      if task_result.is_a?(Phronomy::WorkflowContext)
-                        Phronomy::EventLoop.instance.post(
-                          Phronomy::Event.new(
-                            type: :action_completed,
-                            target_id: thread_id,
-                            payload: task_result
-                          )
-                        )
-                      else
-                        Phronomy::EventLoop.instance.post(
-                          Phronomy::Event.new(type: :state_completed, target_id: thread_id, payload: nil)
-                        )
-                      end
-                    rescue => e
-                      Phronomy::EventLoop.instance.post(
-                        Phronomy::Event.new(type: :error, target_id: thread_id, payload: e)
-                      )
-                    end
-                  else
-                    # Non-EventLoop mode: block synchronously on the task result.
-                    if timeout_secs
-                      if result.join(timeout_secs).nil?
-                        result.cancel!
-                        raise Phronomy::ActionTimeoutError,
-                          "Action in state #{state_name.inspect} timed out after #{timeout_secs}s"
-                      end
-                    end
-                    task_result = result.await
-                    machine.context = task_result if task_result.is_a?(Phronomy::WorkflowContext)
-                  end
-                elsif result.is_a?(Phronomy::WorkflowContext)
-                  machine.context = result
-                end
-              end
-            end
-          end
-
-          # Exit callbacks: fire before_transition out of each state.
-          #    Each callable is registered as a separate callback; state_machines
-          #    accumulates them and fires in declaration order.
-          exit_acts.each do |state_name, callables|
-            callables.each do |callable|
-              before_transition from: state_name do |machine|
-                callable.call(machine.context)
-              end
-            end
-          end
-        end
-      end
-    rescue => e
-      raise ArgumentError, "Failed to build phase machine: #{e.message}"
-    end
-
     # Creates a PhaseTracker instance initialized to +from_state+.
     def new_phase_machine(from_state)
       machine = @phase_machine_class.new

data/lib/phronomy.rb

@@ -8,6 +8,7 @@ loader = Zeitwerk::Loader.for_gem
 # Teach Zeitwerk that "llm" maps to "LLM" so that file names such as
 # ruby_llm_embeddings.rb resolve to RubyLLMEmbeddings (not RubyLlmEmbeddings).
 loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
+loader.inflector.inflect("rag_knowledge" => "RAGKnowledge")
 # FSMSession: Zeitwerk would infer "FsmSession" — override to "FSMSession".
 loader.inflector.inflect("fsm_session" => "FSMSession")
 # AgentFSM: Zeitwerk would infer "Fsm" — override to "FSM".

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-26 00:00:00.000000000 Z
+date: 2026-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -109,34 +109,49 @@ files:
 - lib/phronomy/agent/concerns/guardrailable.rb
 - lib/phronomy/agent/concerns/retryable.rb
 - lib/phronomy/agent/concerns/suspendable.rb
+- lib/phronomy/agent/context/conversation/compaction_context.rb
+- lib/phronomy/agent/context/conversation/trigger_context.rb
+- lib/phronomy/agent/context/conversation/trim_context.rb
+- lib/phronomy/agent/context/instruction/prompt_template.rb
+- lib/phronomy/agent/context/knowledge/embeddings/base.rb
+- lib/phronomy/agent/context/knowledge/embeddings/ruby_llm_embeddings.rb
+- lib/phronomy/agent/context/knowledge/loader/base.rb
+- lib/phronomy/agent/context/knowledge/loader/csv_loader.rb
+- lib/phronomy/agent/context/knowledge/loader/markdown_loader.rb
+- lib/phronomy/agent/context/knowledge/loader/plain_text_loader.rb
+- lib/phronomy/agent/context/knowledge/source/base.rb
+- lib/phronomy/agent/context/knowledge/source/entity_knowledge.rb
+- lib/phronomy/agent/context/knowledge/source/rag_knowledge.rb
+- lib/phronomy/agent/context/knowledge/source/static_knowledge.rb
+- lib/phronomy/agent/context/knowledge/splitter/base.rb
+- lib/phronomy/agent/context/knowledge/splitter/fixed_size_splitter.rb
+- lib/phronomy/agent/context/knowledge/splitter/recursive_splitter.rb
+- lib/phronomy/agent/context/knowledge/vector_store/async_backend.rb
+- lib/phronomy/agent/context/knowledge/vector_store/base.rb
+- lib/phronomy/agent/context/knowledge/vector_store/in_memory.rb
+- lib/phronomy/agent/context/knowledge/vector_store/pgvector.rb
+- lib/phronomy/agent/context/knowledge/vector_store/redis_search.rb
 - lib/phronomy/agent/fsm.rb
-- lib/phronomy/agent/handoff.rb
-- lib/phronomy/agent/orchestrator.rb
-- lib/phronomy/agent/parallel_tool_chat.rb
+- lib/phronomy/agent/invocation_pipeline.rb
+- lib/phronomy/agent/lifecycle/fsm_session.rb
+- lib/phronomy/agent/lifecycle/phase_machine_builder.rb
 - lib/phronomy/agent/react_agent.rb
 - lib/phronomy/agent/runner.rb
 - lib/phronomy/agent/shared_state.rb
 - lib/phronomy/agent/suspend_signal.rb
-- lib/phronomy/agent/team_coordinator.rb
-- lib/phronomy/async_queue.rb
-- lib/phronomy/blocking_adapter_pool.rb
-- lib/phronomy/cancellation_scope.rb
-- lib/phronomy/cancellation_token.rb
-- lib/phronomy/concurrency_gate.rb
+- lib/phronomy/agent/tool_executor.rb
+- lib/phronomy/concurrency/async_queue.rb
+- lib/phronomy/concurrency/blocking_adapter_pool.rb
+- lib/phronomy/concurrency/cancellation_scope.rb
+- lib/phronomy/concurrency/cancellation_token.rb
+- lib/phronomy/concurrency/concurrency_gate.rb
+- lib/phronomy/concurrency/deadline.rb
+- lib/phronomy/concurrency/gate_registry.rb
+- lib/phronomy/concurrency/pool_registry.rb
 - lib/phronomy/configuration.rb
 - lib/phronomy/context.rb
-- lib/phronomy/context/assembler.rb
-- lib/phronomy/context/compaction_context.rb
-- lib/phronomy/context/context_version_cache.rb
-- lib/phronomy/context/token_budget.rb
-- lib/phronomy/context/token_estimator.rb
-- lib/phronomy/context/trigger_context.rb
-- lib/phronomy/context/trim_context.rb
-- lib/phronomy/deadline.rb
 - lib/phronomy/diagnostics.rb
 - lib/phronomy/embeddings.rb
-- lib/phronomy/embeddings/base.rb
-- lib/phronomy/embeddings/ruby_llm_embeddings.rb
 - lib/phronomy/eval.rb
 - lib/phronomy/eval/comparison.rb
 - lib/phronomy/eval/dataset.rb
@@ -151,7 +166,6 @@ files:
 - lib/phronomy/eval/scorer/llm_judge.rb
 - lib/phronomy/event.rb
 - lib/phronomy/event_loop.rb
-- lib/phronomy/fsm_session.rb
 - lib/phronomy/generator_verifier.rb
 - lib/phronomy/guardrail.rb
 - lib/phronomy/guardrail/base.rb
@@ -160,31 +174,28 @@ files:
 - lib/phronomy/guardrail/prompt_injection_guardrail.rb
 - lib/phronomy/invocation_context.rb
 - lib/phronomy/knowledge_source.rb
-- lib/phronomy/knowledge_source/base.rb
-- lib/phronomy/knowledge_source/entity_knowledge.rb
-- lib/phronomy/knowledge_source/rag_knowledge.rb
-- lib/phronomy/knowledge_source/static_knowledge.rb
 - lib/phronomy/llm_adapter.rb
 - lib/phronomy/llm_adapter/base.rb
 - lib/phronomy/llm_adapter/ruby_llm.rb
+- lib/phronomy/llm_context_window/assembler.rb
+- lib/phronomy/llm_context_window/context_version_cache.rb
+- lib/phronomy/llm_context_window/token_budget.rb
+- lib/phronomy/llm_context_window/token_estimator.rb
 - lib/phronomy/loader.rb
-- lib/phronomy/loader/base.rb
-- lib/phronomy/loader/csv_loader.rb
-- lib/phronomy/loader/markdown_loader.rb
-- lib/phronomy/loader/plain_text_loader.rb
 - lib/phronomy/metrics.rb
+- lib/phronomy/multi_agent/handoff.rb
+- lib/phronomy/multi_agent/orchestrator.rb
+- lib/phronomy/multi_agent/parallel_tool_chat.rb
+- lib/phronomy/multi_agent/team_coordinator.rb
 - lib/phronomy/output_parser.rb
 - lib/phronomy/output_parser/base.rb
 - lib/phronomy/output_parser/json_parser.rb
 - lib/phronomy/output_parser/structured_parser.rb
-- lib/phronomy/prompt_template.rb
 - lib/phronomy/ruby_llm_patches.rb
 - lib/phronomy/runnable.rb
 - lib/phronomy/runtime.rb
 - lib/phronomy/runtime/deterministic_scheduler.rb
 - lib/phronomy/runtime/fake_scheduler.rb
-- lib/phronomy/runtime/gate_registry.rb
-- lib/phronomy/runtime/pool_registry.rb
 - lib/phronomy/runtime/runtime_metrics.rb
 - lib/phronomy/runtime/scheduler.rb
 - lib/phronomy/runtime/scheduler_timer_adapter.rb
@@ -193,9 +204,6 @@ files:
 - lib/phronomy/runtime/timer_queue.rb
 - lib/phronomy/runtime/timer_service.rb
 - lib/phronomy/splitter.rb
-- lib/phronomy/splitter/base.rb
-- lib/phronomy/splitter/fixed_size_splitter.rb
-- lib/phronomy/splitter/recursive_splitter.rb
 - lib/phronomy/state_store/base.rb
 - lib/phronomy/state_store/in_memory.rb
 - lib/phronomy/task.rb
@@ -214,18 +222,12 @@ files:
 - lib/phronomy/tool/base.rb
 - lib/phronomy/tool/mcp_tool.rb
 - lib/phronomy/tool/scope_policy.rb
-- lib/phronomy/tool_executor.rb
 - lib/phronomy/tracing.rb
 - lib/phronomy/tracing/base.rb
 - lib/phronomy/tracing/langfuse_tracer.rb
 - lib/phronomy/tracing/null_tracer.rb
 - lib/phronomy/tracing/open_telemetry_tracer.rb
 - lib/phronomy/vector_store.rb
-- lib/phronomy/vector_store/async_backend.rb
-- lib/phronomy/vector_store/base.rb
-- lib/phronomy/vector_store/in_memory.rb
-- lib/phronomy/vector_store/pgvector.rb
-- lib/phronomy/vector_store/redis_search.rb
 - lib/phronomy/version.rb
 - lib/phronomy/workflow.rb
 - lib/phronomy/workflow_context.rb

data/lib/phronomy/async_queue.rb

@@ -1,155 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # A thread-safe FIFO queue for passing values between concurrent tasks.
-  #
-  # 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::AsyncQueue.new
-  #   Runtime.instance.spawn { queue.push(expensive_io()) }
-  #   value = queue.pop   # blocks until the producer pushes
-  # @api private
-  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
-    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
-      end
-      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
-    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
-
-    private
-
-    # Cooperative pop for DeterministicScheduler context.
-    # Suspends the current Fiber via the scheduler's signal mechanism rather than
-    # blocking the OS thread.  Because cooperative mode is single-threaded, the
-    # empty?/pop pair is race-free (no other Fiber can run between the two calls).
-    # After dequeuing, notifies any push-waiter so that a backpressure-suspended
-    # producer can be unblocked.
-    # @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
-        scheduler.wait_for_signal(@coop_signal)
-        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