phronomy 0.25.0 → 0.27.0

data/lib/phronomy/engine/runtime.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "concurrency/worker_input_restricted"
+
 require_relative "runtime/timer_queue"
 require_relative "runtime/shutdown_result"
 require_relative "runtime/timer_service"
-require_relative "runtime/agent_ownership_registry"
-require_relative "runtime/team_ownership_registry"
 
 module Phronomy
   class Runtime
+    include Phronomy::Concurrency::WorkerInputRestricted
+
     @instance_mutex = Mutex.new
 
     class << self
@@ -64,9 +66,8 @@ module Phronomy
       @pool_registry = Phronomy::Concurrency::PoolRegistry.new(
         timer_queue_provider: -> { timer_queue }
       )
-      @multi_agent_admissions = Phronomy::MultiAgent::AdmissionRegistry.new
-      @agent_ownership_registry = AgentOwnershipRegistry.new(runtime: self)
-      @team_ownership_registry = TeamOwnershipRegistry.new
+      @shutdown_participants = {}
+      @shutdown_participant_error = nil
       @lifecycle_mutex = Mutex.new
       @shutdown_mutex = Mutex.new
       @state = :running
@@ -103,83 +104,40 @@ module Phronomy
       @timer_service.timer_queue
     end
 
-    # Returns only an immutable process-local routing/ownership view. Mutable
-    # execution state remains inside EventLoop and is never exposed to callers.
-    # @api private
-    def __agent_execution_owner(execution_id)
-      loop_instance = @lifecycle_mutex.synchronize { @event_loop }
-      loop_instance&.agent_execution_owner(execution_id)
-    end
-
-    # @api private
-    def __team_owner(id, klass:, create:, persistence:, &block)
-      @team_ownership_registry.fetch(id, klass: klass, create: create, persistence: persistence, &block)
-    end
-
-    # @api private
-    def __get_team(id, klass:)
-      @team_ownership_registry.get(id.to_s, klass: klass)
-    end
-
-    # @api private
-    def __create_agent(agent_id, expected_class:, &block)
-      @agent_ownership_registry.create(agent_id, expected_class: expected_class, &block)
-    end
-
-    # @api private
-    def __load_agent(agent_id, expected_class:, &block)
-      @agent_ownership_registry.load(agent_id, expected_class: expected_class, &block)
-    end
-
-    # @api private
-    def __get_agent(agent_id, expected_class:)
-      @agent_ownership_registry.get(agent_id, expected_class: expected_class)
-    end
-
-    # @api private
-    def __agent_owned?(agent)
-      @agent_ownership_registry.owned?(agent)
-    end
-
-    # @api private
-    def __begin_agent_purge(agent)
-      @agent_ownership_registry.begin_purge(agent)
-    end
-
-    # @api private
-    def __complete_agent_purge(agent, token)
-      @agent_ownership_registry.complete_purge(agent, token)
-    end
-
-    # @api private
-    def __abort_agent_purge(agent, token)
-      @agent_ownership_registry.abort_purge(agent, token)
-    end
-
+    # Lookup only; inspection must not create an EventLoop during shutdown.
     # @api private
-    def __leave_agent_purge_uncertain(agent, token)
-      @agent_ownership_registry.leave_purge_uncertain(agent, token)
+    def __event_loop_if_initialized
+      @lifecycle_mutex.synchronize { @event_loop }
     end
 
+    # Shares one internal participant per key for this Runtime's lifetime.
+    # begin_draining must be idempotent, nonblocking and must not call Runtime:
+    # admission closes under the same lifecycle lock as registration.
+    # wait_until_idle receives an absolute monotonic deadline and returns a Boolean.
+    # Optional after_runtime_shutdown runs outside the lifecycle lock only after
+    # all waits succeed, EventLoop stops, and pools/timer finish shutdown. It must
+    # be idempotent, short, and perform no I/O. Exceptions mark cleanup incomplete.
+    # This is a shutdown contract, not an application extension point.
     # @api private
-    def __agent_execution_admitted?(agent_id)
-      loop_instance = @lifecycle_mutex.synchronize { @event_loop }
-      loop_instance&.agent_execution_admitted?(agent_id) || false
-    end
+    def __register_shutdown_participant(key:, participant:)
+      unless participant.respond_to?(:begin_draining) && participant.respond_to?(:wait_until_idle)
+        raise ArgumentError, "shutdown participant must implement begin_draining and wait_until_idle"
+      end
 
-    # @api private
-    def __admit_multi_agent(coordinator)
-      current_state = @lifecycle_mutex.synchronize { @state }
-      unless current_state == :running
-        raise Phronomy::RuntimeShutdownError,
-          "Runtime is #{current_state}; new Multi-Agent turns are not accepted"
+      @lifecycle_mutex.synchronize do
+        unless @state == :running
+          raise Phronomy::RuntimeShutdownError,
+            "Runtime is #{@state}; shutdown participants cannot be registered"
+        end
+        @shutdown_participants[key] ||= participant
       end
-      @multi_agent_admissions.admit!(coordinator)
     end
 
+    # Lookup only: never registers a participant or reopens its admission gate.
+    # Retained participants remain available during and after shutdown.
     # @api private
-    def __release_multi_agent(coordinator)
-      @multi_agent_admissions.release!(coordinator)
+    def __shutdown_participant(key:)
+      @lifecycle_mutex.synchronize { @shutdown_participants[key] }
     end
 
     def event_loop
@@ -214,6 +172,7 @@ module Phronomy
 
         @failure ||= error
         @state = :failed
+        begin_draining_participants
       end
     end
 
@@ -232,17 +191,14 @@ module Phronomy
         return @shutdown_result if @shutdown_result
 
         drain_deadline = monotonic_now + timeout
-        loop_instance = @lifecycle_mutex.synchronize do
+        loop_instance, participants = @lifecycle_mutex.synchronize do
           @state = :draining unless @state == :failed
-          @event_loop
+          begin_draining_participants
+          [@event_loop, @shutdown_participants.values]
         end
         loop_instance&.begin_draining
-        @agent_ownership_registry.begin_draining
-        @team_ownership_registry.begin_draining
 
-        admission_idle = @multi_agent_admissions.wait_until_idle(drain_deadline)
-        agent_ownership_stable = @agent_ownership_registry.wait_until_stable(drain_deadline)
-        team_ownership_stable = @team_ownership_registry.wait_until_stable(drain_deadline)
+        participants_idle = wait_for_participants(participants, drain_deadline)
         loop_idle = !loop_instance || loop_instance.wait_until_idle(drain_deadline)
 
         @lifecycle_mutex.synchronize do
@@ -257,11 +213,15 @@ module Phronomy
         end
 
         subsystem_error = shutdown_pools_and_timer
-        cleanup_complete = admission_idle && agent_ownership_stable && team_ownership_stable && loop_idle &&
+        participant_error = @lifecycle_mutex.synchronize { @shutdown_participant_error }
+        cleanup_complete = participants_idle && participant_error.nil? &&
+          loop_idle &&
           (!loop_instance || !loop_instance.thread_alive?) &&
           event_loop_status != :cancel_timeout &&
+          (!loop_instance || loop_instance.__receiver_cleanup_complete?) &&
           subsystem_error.nil?
 
+        cleanup_complete = finalize_participants(participants) if cleanup_complete
         failure = @lifecycle_mutex.synchronize { @failure } || subsystem_error
         runtime_outcome = if failure || event_loop_status == :failed
           :failed
@@ -269,9 +229,6 @@ module Phronomy
           :terminated
         end
 
-        @agent_ownership_registry.shutdown! if cleanup_complete
-        @team_ownership_registry.shutdown! if cleanup_complete
-
         result = ShutdownResult.new(
           runtime_outcome: runtime_outcome,
           cleanup_status: cleanup_complete ? :complete : :incomplete,
@@ -290,6 +247,45 @@ module Phronomy
 
     private
 
+    # Called with the lifecycle lock held; participants only close their gates.
+    def begin_draining_participants
+      @shutdown_participants.each_value do |participant|
+        participant.begin_draining
+      rescue => error
+        record_participant_failure(error)
+      end
+    end
+
+    # All gates are already closed. Wait without holding the lifecycle lock and
+    # give every participant the same deadline, even if an earlier wait fails.
+    def wait_for_participants(participants, deadline)
+      participants.map do |participant|
+        participant.wait_until_idle(deadline) == true
+      rescue => error
+        @lifecycle_mutex.synchronize { record_participant_failure(error) }
+        false
+      end.all?
+    end
+
+    # Finalize every participant even if one fails. Earlier releases are not
+    # rolled back, and a failure prevents replacement of the default Runtime.
+    def finalize_participants(participants)
+      participants.map do |participant|
+        participant.after_runtime_shutdown if participant.respond_to?(:after_runtime_shutdown)
+        true
+      rescue => error
+        @lifecycle_mutex.synchronize { record_participant_failure(error) }
+        false
+      end.all?
+    end
+
+    # Called with the lifecycle lock held. Failed hooks make cleanup uncertain.
+    def record_participant_failure(error)
+      @shutdown_participant_error ||= error
+      @failure ||= error
+      @state = :failed
+    end
+
     def ensure_accepting_work!
       current_state = @lifecycle_mutex.synchronize { @state }
       return if %i[running draining].include?(current_state)

data/lib/phronomy/engine/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/engine/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/engine/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/{task.rb → task_result.rb}

@@ -1,22 +1,60 @@
 # frozen_string_literal: true
 
+require_relative "concurrency/worker_input_restricted"
+
 module Phronomy
   # A thread-free asynchronous completion handle.
   #
-  # Task does not execute work. Execution belongs to EventLoop/FSMSession or
-  # OffloadPool. Task represents completion, failure, cancellation, callbacks,
+  # TaskResult does not execute work. Execution belongs to EventLoop/FSMSession or
+  # OffloadPool. TaskResult represents completion, failure, cancellation, callbacks,
   # and a blocking wait for callers outside EventLoop.
   #
-  # Framework components own Task settlement. Application code should observe a
-  # Task through {#wait_result}, {#on_complete}, {#map}, and state readers rather
+  # Framework components own TaskResult settlement. Application code should observe a
+  # TaskResult through {#wait_result}, {#on_complete}, {#map}, and state readers rather
   # than calling {#complete}, {#fail}, or {#cancel!}. Operation-wide cancellation
   # is supplied through the CancellationToken accepted by the API that created
-  # the Task.
-  class Task
+  # 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
 
+    # A shallow immutable input-position record. Application values are retained
+    # by reference; they are neither copied nor frozen by this record.
+    # @api public
+    class Outcome < Struct.new(:index, :status, :value, :error)
+      def initialize(**fields)
+        super
+        freeze
+      end
+    end
+
+    # Observe already-created results without taking ownership of their work.
+    # Invalid inputs are rejected before any completion subscription is added.
+    # @param results [Array<TaskResult>]
+    # @return [TaskResult<Array<Outcome>>]
+    # @raise [TypeError] for a non-Array list or non-TaskResult element
+    # @api public
+    def self.all_settled(results)
+      raise TypeError, "results must be an Array" unless results.is_a?(Array)
+
+      inputs = results.dup
+      inputs.each_with_index do |result, index|
+        unless result.is_a?(Phronomy::TaskResult)
+          raise TypeError, "results[#{index}] must be a Phronomy::TaskResult"
+        end
+      end
+      combined = Phronomy::TaskResult.deferred(name: "all-settled")
+      collector = Concurrency::ResultCollector.new(inputs.length) do |_, outcomes|
+        combined.complete(outcomes)
+      end
+      inputs.each_with_index { |result, index| collector.watch(index, result) }
+      collector.finish(:completed)
+      combined
+    end
+
     # Creates an unsettled completion handle for framework-owned execution.
     # @api private
     def self.deferred(name: nil, parent: nil)
@@ -24,26 +62,26 @@ module Phronomy
     end
 
     # Public factories for already-settled values. No execution is started.
-    # Always create a base Task: there is no physical worker to supervise.
+    # Always create a base TaskResult: there is no physical worker to supervise.
     # @param value [Object] already available result
     # @param name [String, nil] optional diagnostic name
-    # @return [Phronomy::Task] a completed base Task
+    # @return [Phronomy::TaskResult] a completed base TaskResult
     # @api public
     def self.completed(value = nil, name: nil)
-      Phronomy::Task.deferred(name: name).tap { |task| task.complete(value) }
+      Phronomy::TaskResult.deferred(name: name).tap { |task| task.complete(value) }
     end
 
     # Represents an already known failure without raising the stored error.
     # Observation through wait_result raises it; on_complete receives it.
     # @param error [Exception] original failure object
     # @param name [String, nil] optional diagnostic name
-    # @return [Phronomy::Task] a failed base Task
+    # @return [Phronomy::TaskResult] a failed base TaskResult
     # @raise [ArgumentError] if error is not an Exception
     # @api public
     def self.failed(error, name: nil)
       raise ArgumentError, "error must be an Exception" unless error.is_a?(Exception)
 
-      Phronomy::Task.deferred(name: name).tap { |task| task.fail(error) }
+      Phronomy::TaskResult.deferred(name: name).tap { |task| task.fail(error) }
     end
 
     attr_reader :name, :parent
@@ -68,13 +106,13 @@ module Phronomy
       @mutex.synchronize { @status }
     end
 
-    # @return [Boolean] whether the Task has reached a terminal state
+    # @return [Boolean] whether the TaskResult has reached a terminal state
     # @api public
     def done?
       @mutex.synchronize { TERMINAL_STATES.include?(@status) }
     end
 
-    # @return [Boolean] whether the Task has not yet reached a terminal state
+    # @return [Boolean] whether the TaskResult has not yet reached a terminal state
     # @api public
     def alive?
       !done?
@@ -82,19 +120,19 @@ module Phronomy
 
     # Blocks the calling thread until settlement.
     #
-    # EventLoop is never allowed to wait for a Task; framework continuation must
+    # EventLoop is never allowed to wait for a TaskResult; framework continuation must
     # proceed through explicit events. The optional timeout is waiter-local: it
-    # does not settle or cancel the Task.
+    # does not settle or cancel the TaskResult.
     #
     # @param timeout [Numeric, nil] maximum seconds this caller will block
     # @return [Object] the completed value
     # @raise [Phronomy::TimeoutError] when the waiter-local timeout expires
-    # @raise [Exception] the error that settled the Task
+    # @raise [Exception] the error that settled the TaskResult
     # @api public
     def wait_result(timeout: nil)
       if Phronomy::Runtime.in_event_loop_context? && !done?
         raise Phronomy::EventLoopReentrancyError,
-          "Task#wait_result cannot block the EventLoop thread; continue via an event"
+          "TaskResult#wait_result cannot block the EventLoop thread; continue via an event"
       end
 
       deadline = timeout && monotonic_now + timeout.to_f
@@ -104,7 +142,7 @@ module Phronomy
             remaining = deadline - monotonic_now
             if remaining <= 0
               raise Phronomy::TimeoutError,
-                "timed out waiting for Task #{@name || "(unnamed)"}"
+                "timed out waiting for TaskResult #{@name || "(unnamed)"}"
             end
             @cond.wait(@mutex, remaining)
           else
@@ -118,13 +156,13 @@ module Phronomy
       value
     end
 
-    # Compatibility wait that does not re-raise the Task error.
+    # Compatibility wait that does not re-raise the TaskResult error.
     # Returns self when settled, nil on timeout.
     # @api private
     def join(limit = nil)
       if Phronomy::Runtime.in_event_loop_context? && !done?
         raise Phronomy::EventLoopReentrancyError,
-          "Task#join cannot block the EventLoop thread; continue via an event"
+          "TaskResult#join cannot block the EventLoop thread; continue via an event"
       end
 
       deadline = limit && monotonic_now + limit.to_f
@@ -148,7 +186,7 @@ module Phronomy
     # registers after settlement, an OffloadPool worker, or a framework control
     # thread. Callbacks must therefore be thread-safe and should complete quickly.
     # A callback failure is logged and does not suppress delivery to other
-    # completion callbacks or change the Task's already-settled result.
+    # completion callbacks or change the TaskResult's already-settled result.
     #
     # @yield [value, error]
     # @return [self]
@@ -168,53 +206,74 @@ module Phronomy
       self
     end
 
-    # Settles this Task successfully. Framework-owned settlement API.
+    # Settles this TaskResult successfully. Framework-owned settlement API.
     # @api private
     def complete(value = nil)
       settle!(:completed, value: value)
     end
 
-    # Settles this Task with a failure. Framework-owned settlement API.
+    # Settles this TaskResult with a failure. Framework-owned settlement API.
     # @api private
     def fail(error)
       raise ArgumentError, "error is required" unless error
       settle!(:failed, error: error)
     end
 
-    # Settles this Task as cancelled. Framework-owned settlement API.
+    # Settles this TaskResult as cancelled. Framework-owned settlement API.
     #
     # This method does not propagate backwards into a CancellationToken that may
-    # have been used to create the Task. Tokens can be shared across operations;
+    # have been used to create the TaskResult. Tokens can be shared across operations;
     # operation-wide cancellation is owned by the creating API.
     # @api private
-    def cancel!(error = Phronomy::CancellationError.new("Task cancelled"))
+    def cancel!(error = Phronomy::CancellationError.new("TaskResult cancelled"))
       changed = settle!(:cancelled, error: error)
       if changed
         children = @mutex.synchronize { @children.dup }
-        children.each(&:cancel!)
+        children.each { |child| child.cancel!(error) }
       end
       self
     end
 
-    # Creates a derived Task by transforming this Task's successful result.
+    # Creates a derived TaskResult by transforming this TaskResult's successful result.
     # @api public
     def map(&block)
       raise ArgumentError, "map requires a block" unless block
 
-      mapped = self.class.deferred(name: "#{@name}-mapped", parent: @parent)
-      on_complete do |value, error|
-        if error
-          mapped.fail(error)
-          next
-        end
+      Concurrency::ResultComposition.new(self, flatten: false, &block).start
+    end
 
-        begin
-          mapped.complete(block.call(value))
-        rescue => mapped_error
-          mapped.fail(mapped_error)
-        end
-      end
-      mapped
+    # Transform a successful value into the result of another asynchronous step.
+    # The block must return a TaskResult. No implicit wrapping or nested value
+    # flattening is performed by map.
+    # @return [TaskResult]
+    # @api public
+    def flat_map(&block)
+      raise ArgumentError, "flat_map requires a block" unless block
+
+      Concurrency::ResultComposition.new(self, flatten: true, &block).start
+    end
+
+    # Atomic state observation and removable framework subscriptions.
+    # @api private
+    def __snapshot
+      @mutex.synchronize { [@status, @value, @error] }
+    end
+
+    # @api private
+    def __unsubscribe(callback)
+      @mutex.synchronize { @on_complete_callbacks.delete(callback) }
+    end
+
+    # Bound at admission, before application code can attach continuations.
+    # @api private
+    def __bind_execution(execution)
+      @execution_scope = execution
+      self
+    end
+
+    # @api private
+    def __execution_scope
+      @execution_scope
     end
 
     protected
@@ -250,7 +309,7 @@ module Phronomy
       callback.call(value, error)
     rescue => callback_error
       Phronomy.configuration.logger&.error do
-        "[Task] on_complete callback raised #{callback_error.class}: #{callback_error.message}"
+        "[TaskResult] on_complete callback raised #{callback_error.class}: #{callback_error.message}"
       end
     end
 

data/lib/phronomy/engine/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/filter/contract/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_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