phronomy 0.26.0 → 0.28.0

data/lib/phronomy/execution/invocation_controls.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Owns invocation control attachment through the observed result's lifetime.
+  # Domain runners carry this operation control, not execution scope internals.
+  # @api private
+  class InvocationControls
+    attr_reader :token
+
+    def self.attach(result, invocation_context:, cancellation_token:)
+      controls = new(invocation_context: invocation_context, cancellation_token: cancellation_token)
+      controls.bind(result)
+      controls
+    rescue
+      controls&.close
+      raise
+    end
+
+    def initialize(invocation_context:, cancellation_token:)
+      if !invocation_context.nil? && !invocation_context.is_a?(InvocationContext)
+        raise TypeError, "invocation_context must be a Phronomy::InvocationContext or nil"
+      end
+      @scope = invocation_context&.__execution_scope
+      @subscriptions = Concurrency::Subscriptions.new
+      @token = invocation_context ? Concurrency::CancellationToken.new : cancellation_token
+      return unless invocation_context
+
+      [invocation_context.cancellation_token, cancellation_token].compact.uniq.each do |source|
+        @subscriptions.cancellation(source) { @token.cancel! }
+      end
+      if !@scope && invocation_context.deadline
+        @subscriptions.after(invocation_context.deadline.remaining_seconds) { @token.cancel! }
+      end
+      @token.cancel! if @scope && !@scope.__open?
+    rescue
+      close
+      raise
+    end
+
+    # Check at the receiving runner, after asynchronous delivery. An already
+    # closed scope must not acquire the domain's admission slot or start I/O.
+    def check_start!
+      if @scope && (!@scope.__open? || @token&.cancelled?)
+        raise @scope.__cancellation_error
+      end
+    end
+
+    def bind(result)
+      result.__bind_execution(@scope)
+      track(result)
+    end
+
+    def track(result)
+      @subscriptions.result(result) { close }
+      result
+    end
+
+    def close
+      @subscriptions&.close
+    end
+
+    def self.effective_timeout_token(context)
+      return context.cancellation_token if context.cancellation_token
+      return nil unless context.deadline
+
+      token = Concurrency::CancellationToken.new
+      subscriptions = Concurrency::Subscriptions.new
+      subscriptions.cancellation(token) { subscriptions.close }
+      subscriptions.after(context.deadline.remaining_seconds) { token.cancel! }
+      token
+    end
+  end
+end

data/lib/phronomy/execution/pool_shutdown_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class PoolShutdownError < Error; end
+end

data/lib/phronomy/execution/recursion_limit_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class RecursionLimitError < Error; end
+end

data/lib/phronomy/execution/runnable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Base interface for executable graph components.
+  # Provides invoke / stream / batch.
+  module Runnable
+    # Synchronous execution. Must be overridden in subclasses.
+    def invoke(input, config: {})
+      raise NotImplementedError, "#{self.class}#invoke is not implemented"
+    end
+
+    # Streaming execution. Default yields the invoke result as a single chunk.
+    def stream(input, config: {}, &block)
+      result = invoke(input, config: config)
+      yield result if block
+      result
+    end
+
+    # Batch execution. Default calls invoke sequentially.
+    def batch(inputs, config: {})
+      inputs.map { |input| invoke(input, config: config) }
+    end
+  end
+end

data/lib/phronomy/execution/runtime_shutdown_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class RuntimeShutdownError < Error; end
+end

data/lib/phronomy/execution/runtime_shutdown_reentrancy_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "runtime_shutdown_error"
+
+module Phronomy
+  class RuntimeShutdownReentrancyError < RuntimeShutdownError; end
+end

data/lib/phronomy/execution/scheduler_reentrancy_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "event_loop_reentrancy_error"
+
+module Phronomy
+  # Backward-compatible error class name for callers that still rescue the old
+  # scheduler-oriented exception. New code should use EventLoopReentrancyError.
+  class SchedulerReentrancyError < EventLoopReentrancyError; end
+end

data/lib/phronomy/{engine → execution}/task_result.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "concurrency/worker_input_restricted"
+
 module Phronomy
   # A thread-free asynchronous completion handle.
   #
@@ -13,6 +15,8 @@ module Phronomy
   # is supplied through the CancellationToken accepted by the API that created
   # the TaskResult.
   class TaskResult
+    include Phronomy::Concurrency::WorkerInputRestricted
+
     STATES = %i[pending completed failed cancelled].freeze
     TERMINAL_STATES = %i[completed failed cancelled].freeze
     private_constant :TERMINAL_STATES
@@ -126,7 +130,7 @@ module Phronomy
     # @raise [Exception] the error that settled the TaskResult
     # @api public
     def wait_result(timeout: nil)
-      if Phronomy::Runtime.in_event_loop_context? && !done?
+      if Phronomy::WaitPolicy.blocking_forbidden? && !done?
         raise Phronomy::EventLoopReentrancyError,
           "TaskResult#wait_result cannot block the EventLoop thread; continue via an event"
       end
@@ -156,7 +160,7 @@ module Phronomy
     # Returns self when settled, nil on timeout.
     # @api private
     def join(limit = nil)
-      if Phronomy::Runtime.in_event_loop_context? && !done?
+      if Phronomy::WaitPolicy.blocking_forbidden? && !done?
         raise Phronomy::EventLoopReentrancyError,
           "TaskResult#join cannot block the EventLoop thread; continue via an event"
       end
@@ -304,7 +308,7 @@ module Phronomy
     def deliver_completion_callback(callback, value, error)
       callback.call(value, error)
     rescue => callback_error
-      Phronomy.configuration.logger&.error do
+      Phronomy::RuntimeSettings.current.logger&.error do
         "[TaskResult] on_complete callback raised #{callback_error.class}: #{callback_error.message}"
       end
     end

data/lib/phronomy/execution/timeout_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class TimeoutError < Error; end
+end

data/lib/phronomy/execution/wait_policy.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Neutral thread-local blocking policy. It owns no Runtime or scheduler.
+  # No invocation context is inferred from this marker.
+  # @api private
+  module WaitPolicy
+    KEY = :phronomy_control_thread_depth
+    private_constant :KEY
+
+    def self.blocking_forbidden?
+      Thread.current.thread_variable_get(KEY).to_i > 0
+    end
+
+    def self.without_blocking
+      thread = Thread.current
+      previous = thread.thread_variable_get(KEY)
+      thread.thread_variable_set(KEY, previous.to_i + 1)
+      yield
+    ensure
+      thread.thread_variable_set(KEY, previous)
+    end
+  end
+end

data/lib/phronomy/filter/filter_block_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class FilterBlockError < Error
+    attr_reader :filter
+
+    def initialize(message, filter: nil)
+      super(message)
+      @filter = filter
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/agent_operation.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    # Connects one reused Agent incarnation through its public operation and
+    # notification contracts. Terminal results belong to each returned TaskResult;
+    # only approval suspension needs the incarnation listener while that Task is
+    # still pending. Generation owns the request-to-Workflow correlation.
+    # @api private
+    class AgentOperation
+      def initialize(agent_class)
+        @mutex = Mutex.new
+        @pending = []
+        @agent = agent_class.new(on_event: method(:receive_event))
+      end
+
+      def start(input, listener:)
+        request = Object.new
+        # Workflow entry calls are serial. Keep submitted requests until their
+        # own result settles: Agent admission itself may run after an earlier
+        # request completes, so a pending submission is not necessarily busy.
+        @mutex.synchronize { @pending << [request, listener] }
+        task = @agent.invoke_async(input)
+        task.on_complete do |result, error|
+          release(request)
+          # Handoff was not a generation completion in the event-based path.
+          next if !error && result.is_a?(Hash) && result[:handoff_request]
+
+          event = if error
+            type = if error.is_a?(Phronomy::TimeoutError)
+              :timeout
+            elsif error.is_a?(Phronomy::CancellationError)
+              :cancelled
+            else
+              :error
+            end
+            Phronomy::Agent::StreamEvent.new(type: type, payload: {error: error})
+          else
+            Phronomy::Agent::StreamEvent.new(type: :done, payload: result)
+          end
+          listener.call(event)
+        end
+        task
+      rescue
+        release(request)
+        raise
+      end
+
+      private
+
+      def receive_event(event)
+        return unless event.type == :approval_required
+
+        listener = @mutex.synchronize { @pending.first&.last }
+        listener&.call(event)
+      end
+
+      def release(request)
+        @mutex.synchronize do
+          @pending.delete_if { |entry| entry.first.equal?(request) }
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/agent_result_receiver.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    # Converts Agent events to correlated Workflow events. PipelineState owns
+    # stale-result rejection and all Workflow state mutation.
+    class AgentResultReceiver
+      def initialize(draft_result_parser:, review_result_parser:)
+        @draft_result_parser = draft_result_parser
+        @review_result_parser = review_result_parser
+      end
+
+      def draft_listener(workflow:, workflow_instance_id:, request_id:)
+        agent_listener(:draft, workflow, workflow_instance_id, request_id) do |output|
+          draft_payload(output)
+        end
+      end
+
+      def review_listener(workflow:, workflow_instance_id:, request_id:)
+        agent_listener(:review, workflow, workflow_instance_id, request_id) do |output|
+          review_payload(output)
+        end
+      end
+
+      private
+
+      def draft_payload(output)
+        parsed = @draft_result_parser.call(output)
+        {
+          draft: parsed[:answer].to_s,
+          self_score: clamp(parsed[:confidence]),
+          citations: normalize_citations(parsed[:citations])
+        }
+      end
+
+      def review_payload(output)
+        parsed = @review_result_parser.call(output)
+        {
+          review_score: clamp(parsed[:score]),
+          approved: parsed[:approved] == true,
+          feedback: parsed[:feedback].to_s
+        }
+      end
+
+      def agent_listener(phase, workflow, workflow_instance_id, request_id, &completion)
+        ->(agent_event) {
+          case agent_event.type
+          when :done
+            begin
+              payload = completion.call(agent_event.payload[:output])
+              workflow.signal(
+                workflow_instance_id: workflow_instance_id,
+                event: :"#{phase}_completed",
+                payload: {request_id: request_id, **payload}
+              )
+            rescue => error
+              signal_failure(workflow, workflow_instance_id, request_id, phase, error)
+            end
+          when :error, :timeout, :cancelled
+            error = agent_event.payload[:error] ||
+              Phronomy::Error.new("#{phase.to_s.capitalize} Agent ended with #{agent_event.type}")
+            signal_failure(workflow, workflow_instance_id, request_id, phase, error)
+          when :approval_required
+            error = Phronomy::Error.new("GeneratorVerifier #{phase} Agent suspended for approval")
+            signal_failure(workflow, workflow_instance_id, request_id, phase, error)
+          end
+        }
+      end
+
+      def signal_failure(workflow, workflow_instance_id, request_id, phase, error)
+        workflow.signal(
+          workflow_instance_id: workflow_instance_id,
+          event: :"#{phase}_failed",
+          payload: {request_id: request_id, error: error}
+        )
+      end
+
+      def clamp(value)
+        value.to_f.clamp(0.0, 1.0)
+      end
+
+      def normalize_citations(raw)
+        Array(raw).filter_map do |citation|
+          citation.is_a?(Hash) ? citation.transform_keys(&:to_sym) : nil
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/default_parser.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    # Boot supplies the default concrete parser. The generation algorithm owns
+    # its output interpretation and fallback, not the concrete parser selection.
+    # @api private
+    module DefaultParser
+      FACTORIES = {}
+      private_constant :FACTORIES
+
+      # Private one-time composition binding; not an application registry.
+      # @api private
+      def self.install_factory(factory)
+        raise ArgumentError, "factory must respond to call" unless factory.respond_to?(:call)
+
+        FACTORIES.replace(parser: factory).freeze
+        nil
+      end
+
+      # @api private
+      def self.build
+        FACTORIES.fetch(:parser).call
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/pipeline_state.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    class PipelineState
+      include Phronomy::WorkflowContext
+
+      field :input, type: :replace, default: -> { "" }
+      field :draft, type: :replace, default: -> { {} }
+      field :self_score, type: :replace, default: -> { 0.0 }
+      field :review_score, type: :replace, default: -> { 0.0 }
+      field :citations, type: :replace, default: -> { [] }
+      field :review_notes, type: :append, default: -> { [] }
+      field :iteration, type: :replace, default: -> { 0 }
+      field :approved, type: :replace, default: -> { false }
+      field :output, type: :replace, default: -> { {} }
+      field :draft_request_id, type: :replace, default: nil
+      field :review_request_id, type: :replace, default: nil
+      field :pipeline_error, type: :replace, default: nil
+
+      # Application-level event interpretation. Correlation IDs belong to this
+      # Pipeline rather than to the generic FSMSession.
+      def handle_fsm_event(event)
+        case event.type
+        when :draft_completed
+          return :consume unless event.payload[:request_id] == draft_request_id
+
+          self.draft = event.payload[:draft]
+          self.self_score = event.payload[:self_score]
+          self.citations = event.payload[:citations]
+          self.iteration = iteration + 1
+          self.draft_request_id = nil
+          self.pipeline_error = nil
+        when :review_completed
+          return :consume unless event.payload[:request_id] == review_request_id
+
+          self.review_score = event.payload[:review_score]
+          self.approved = event.payload[:approved]
+          self.review_notes = review_notes + [event.payload[:feedback]]
+          self.review_request_id = nil
+          self.pipeline_error = nil
+        when :draft_failed
+          return :consume unless event.payload[:request_id] == draft_request_id
+
+          self.pipeline_error = event.payload[:error]
+          self.draft_request_id = nil
+        when :review_failed
+          return :consume unless event.payload[:request_id] == review_request_id
+
+          self.pipeline_error = event.payload[:error]
+          self.review_request_id = nil
+        end
+        false
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/workflow_builder.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Phronomy
+  class GeneratorVerifier
+    # Builds the generation/review loop; result reception does not mutate state.
+    class WorkflowBuilder
+      def initialize(
+        draft_agent:, review_agent:,
+        draft_prompt_builder:, review_prompt_builder:,
+        draft_result_parser:, review_result_parser:,
+        threshold:, max_iterations:
+      )
+        @draft_agent = draft_agent
+        @review_agent = review_agent
+        @draft_prompt_builder = draft_prompt_builder
+        @review_prompt_builder = review_prompt_builder
+        @threshold = threshold
+        @max_iterations = max_iterations
+        @result_receiver = AgentResultReceiver.new(
+          draft_result_parser: draft_result_parser,
+          review_result_parser: review_result_parser
+        )
+      end
+
+      def build
+        # The entry closures see the Workflow assigned after definition.
+        workflow = nil
+        draft_entry = ->(state) { start_draft(state, workflow) }
+        review_entry = ->(state) { start_review(state, workflow) }
+        finalize_entry = method(:finalize)
+        failed_entry = method(:fail_pipeline)
+        ready_to_finalize = method(:ready_to_finalize?)
+
+        workflow = Phronomy::Workflow.define(PipelineState) do
+          initial :draft
+
+          state :draft
+          state :review
+          state :finalize
+          state :failed
+
+          entry :draft, draft_entry
+          entry :review, review_entry
+          entry :finalize, finalize_entry
+          entry :failed, failed_entry
+
+          transition from: :draft, on: :draft_completed, to: :review
+          transition from: :draft, on: :draft_failed, to: :failed
+          transition from: :review,
+            on: :review_completed,
+            guard: ready_to_finalize,
+            to: :finalize
+          transition from: :review, on: :review_completed, to: :draft
+          transition from: :review, on: :review_failed, to: :failed
+
+          transition from: :finalize, to: :__finish__
+        end
+      end
+
+      private
+
+      def start_draft(state, workflow)
+        request_id = SecureRandom.uuid
+        next_state = state.merge(draft_request_id: request_id)
+        feedback = next_state.review_notes.last
+        prompt = @draft_prompt_builder.call(next_state.input, feedback)
+        listener = @result_receiver.draft_listener(
+          workflow: workflow,
+          workflow_instance_id: next_state.workflow_instance_id,
+          request_id: request_id
+        )
+        @draft_agent.start(prompt, listener: listener)
+        next_state
+      end
+
+      def start_review(state, workflow)
+        request_id = SecureRandom.uuid
+        next_state = state.merge(review_request_id: request_id)
+        prompt = @review_prompt_builder.call(
+          next_state.input, next_state.draft, next_state.citations
+        )
+        listener = @result_receiver.review_listener(
+          workflow: workflow,
+          workflow_instance_id: next_state.workflow_instance_id,
+          request_id: request_id
+        )
+        @review_agent.start(prompt, listener: listener)
+        next_state
+      end
+
+      def ready_to_finalize?(state)
+        confidence = [state.self_score || 0.0, state.review_score || 0.0].min
+        (confidence >= @threshold && state.approved) ||
+          state.iteration >= @max_iterations
+      end
+
+      def finalize(state)
+        state.output = state.draft
+        state
+      end
+
+      def fail_pipeline(state)
+        raise(
+          state.pipeline_error ||
+          Phronomy::Error.new("GeneratorVerifier Agent operation failed")
+        )
+      end
+    end
+  end
+end