phronomy 0.26.0 → 0.27.0

data/lib/phronomy/engine/event_loop_reentrancy_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  # Raised when a synchronous API would block the EventLoop control thread.
+  class EventLoopReentrancyError < Error; end
+end

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

@@ -60,13 +60,6 @@ module Phronomy
     end
     private_class_method :__run_async
 
-    # Common admission binding for Agent and synchronous-work adapters.
-    # @api private
-    def self.__operation_binding(invocation_context:, cancellation_token:)
-      Concurrency::OperationBinding.new(invocation_context: invocation_context,
-        cancellation_token: cancellation_token)
-    end
-
     # A scoped observation copy. The source, its controls and its physical work
     # keep their original ownership. Bind before adding this run's map/flat_map.
     # @param source_result [TaskResult]

data/lib/phronomy/{execution_cancellation_error.rb → engine/execution_cancellation_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "cancellation_error"
+
 module Phronomy
   class ExecutionCancellationError < CancellationError
     attr_reader :outcomes

data/lib/phronomy/engine/execution_receiver.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Internal lifecycle/delivery contract for feature-owned execution state.
+  # Receivers are retained by one EventLoop, not an application callback SPI.
+  # Normal mutation and delivery run only on that loop. idle? runs with its
+  # lifecycle lock held; it must not call Runtime or acquire that lock again.
+  # shutdown runs on a failing loop, or exclusively after a clean loop joins.
+  # @api private
+  class ExecutionReceiver
+    def self.for(event_loop)
+      event_loop.__execution_receiver(key: self) ||
+        event_loop.__register_execution_receiver(key: self, receiver: new(event_loop: event_loop))
+    end
+
+    # Lookup only: neither a loop nor a receiver is created during inspection.
+    def self.existing_for(runtime)
+      runtime.__event_loop_if_initialized&.__execution_receiver(key: self)
+    end
+
+    def initialize(event_loop:)
+      @event_loop = event_loop
+    end
+
+    def __bound_to?(event_loop)
+      @event_loop.equal?(event_loop)
+    end
+
+    def idle?
+      raise NotImplementedError
+    end
+
+    def deliver(message)
+      raise NotImplementedError
+    end
+
+    def shutdown(error:)
+      raise NotImplementedError
+    end
+
+    def session_retired(fsm_session_id, reason:)
+    end
+
+    private
+
+    def synchronize(&block)
+      @event_loop.__synchronize_execution_state(&block)
+    end
+
+    def admit(&block)
+      @event_loop.__admit_execution(self, &block)
+    end
+
+    def post_message(message, admission: false, completion: nil)
+      @event_loop.__post_execution(self, message, admission: admission, completion: completion)
+    end
+
+    def assert_event_loop_thread!
+      return if @event_loop.current?
+
+      raise Phronomy::Error,
+        "Phronomy-managed live execution state may only be mutated on EventLoop"
+    end
+  end
+end

data/lib/phronomy/{execution_timeout_error.rb → engine/execution_timeout_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "timeout_error"
+
 module Phronomy
   class ExecutionTimeoutError < TimeoutError
     attr_reader :outcomes

data/lib/phronomy/engine/fsm_protocol.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Shared terminal-state vocabulary and domain decisions for FSM execution.
+  # This protocol does not depend on a particular runner or session instance.
+  # @api private
+  module FSMProtocol
+    FINISH = :__end__
+
+    # A domain policy permits completion, reports failure, or retires a session
+    # without settling its caller. It never carries live session authority.
+    TerminalDecision = Data.define(:action, :error)
+  end
+end

data/lib/phronomy/engine/fsm_session.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "concurrency/worker_input_restricted"
+
 require "securerandom"
 
 module Phronomy
@@ -9,6 +11,8 @@ module Phronomy
   # FSMSession owns FSM execution only; it does not own external TaskResult handles,
   # activity tokens, callback correlation, or domain-specific stale-event policy.
   class FSMSession
+    include Phronomy::Concurrency::WorkerInputRestricted
+
     class IdentityReservation
       attr_reader :fsm_session_id
 
@@ -30,6 +34,8 @@ module Phronomy
     private_constant :IdentityReservation
 
     class EventSink
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       attr_reader :fsm_session_id
 
       def initialize(event_loop:)
@@ -60,8 +66,6 @@ module Phronomy
       end
     end
 
-    FINISH = WorkflowRunner::FINISH
-
     attr_reader :id, :context, :event_sink
 
     # Returns the live current Workflow phase. During an active FSM transition
@@ -95,7 +99,7 @@ module Phronomy
       context_metadata: {},
       event_sink: nil,
       identity_reservation: nil,
-      terminal_barrier: nil
+      terminal_policy: nil
     )
       @id = if identity_reservation
         unless identity_reservation.is_a?(IdentityReservation)
@@ -123,7 +127,7 @@ module Phronomy
       @resume_event = resume_event
       @resume_phase = resume_phase
       @stable_observer = stable_observer
-      @terminal_barrier = terminal_barrier
+      @terminal_policy = terminal_policy
       @terminal_lifecycle_state = :running
       @pending_terminal_type = nil
       @pending_terminal_notify_stable = false
@@ -160,14 +164,13 @@ module Phronomy
     def handle(event)
       return if @done
 
-      if event.type == :workflow_terminal_persistence_result
-        handle_terminal_persistence_result(event.payload)
+      if @terminal_policy&.handles?(event)
+        handle_terminal_event(event)
         return
       end
 
-      # Once terminal persistence begins, ordinary Workflow events no longer
-      # have result authority. Only the persistence completion for this concrete
-      # FSMSession can advance its terminal lifecycle.
+      # Once a terminal decision is pending, ordinary events cannot advance
+      # the state machine. Only the injected policy can permit terminalization.
       return unless @terminal_lifecycle_state == :running
 
       context_disposition = apply_context_event(event)
@@ -261,7 +264,7 @@ module Phronomy
     end
 
     def advance_or_halt
-      return finish! if @current_state == FINISH
+      return finish! if @current_state == FSMProtocol::FINISH
 
       # A wait state is the logical end of this Workflow execution segment. Its
       # public stable-state notification is therefore part of terminalization
@@ -324,7 +327,7 @@ module Phronomy
     def finish!(notify_stable: false)
       request_terminal!(
         :finished,
-        phase: :__end__,
+        phase: FSMProtocol::FINISH,
         notify_stable: notify_stable
       )
     end
@@ -339,13 +342,13 @@ module Phronomy
       apply_context_metadata!(phase: phase)
       @pending_terminal_type = terminal_type
       @pending_terminal_notify_stable = notify_stable
-      unless @terminal_barrier
+      unless @terminal_policy
         complete_terminal!(terminal_type)
         return
       end
 
-      @terminal_lifecycle_state = :persisting_terminal
-      @terminal_barrier.call(
+      @terminal_lifecycle_state = :awaiting_terminal
+      @terminal_policy.start(
         terminal_type: terminal_type,
         context: @ctx,
         event_sink: @event_sink
@@ -354,31 +357,35 @@ module Phronomy
       finish_with_error(error)
     end
 
-    def handle_terminal_persistence_result(result)
-      return unless @terminal_lifecycle_state == :persisting_terminal
+    def handle_terminal_event(event)
+      return unless @terminal_lifecycle_state == :awaiting_terminal
 
-      case result.outcome
-      when :success
+      decision = @terminal_policy.decision_for(event)
+      case decision.action
+      when :complete
         complete_terminal!(@pending_terminal_type)
-      when :known_failure
-        finish_with_error(
-          result.error || Phronomy::Error.new("Workflow terminal persistence failed")
-        )
-      when :outcome_unknown
-        @done = true
-        @terminal_lifecycle_state = :recovery_required
-        post_recovery_required_event(result.error)
+      when :fail
+        finish_with_error(decision.error)
+      when :retire
+        retire_without_result!(decision.error)
       else
         raise Phronomy::Error,
-          "unknown Workflow terminal persistence outcome: #{result.outcome.inspect}"
+          "unknown FSM terminal decision: #{decision.action.inspect}"
       end
     end
 
-    def complete_terminal!(terminal_type)
+    def retire_without_result!(error)
       @done = true
+      @terminal_lifecycle_state = :retired
+      post_recovery_required_event(error)
+    end
+
+    def complete_terminal!(terminal_type)
       @terminal_lifecycle_state =
         (terminal_type == :halted) ? :halted : :completed
+      # Keep the error path open until the observer returns successfully.
       notify_stable_state! if @pending_terminal_notify_stable
+      @done = true
       post_terminal_event(terminal_type, @ctx)
     end
 

data/lib/phronomy/{invalid_async_entry_action_error.rb → engine/invalid_async_entry_action_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "invalid_async_workflow_action_error"
+
 module Phronomy
   # Raised when a synchronous FSM entry action returns Phronomy::TaskResult.
   #

data/lib/phronomy/{invalid_async_transition_action_error.rb → engine/invalid_async_transition_action_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "invalid_async_workflow_action_error"
+
 module Phronomy
   # Raised when a synchronous Workflow transition action returns Phronomy::TaskResult.
   #

data/lib/phronomy/{invalid_async_workflow_action_error.rb → engine/invalid_async_workflow_action_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../common/error"
+
 module Phronomy
   # Base error for synchronous Workflow callbacks that return Phronomy::TaskResult.
   #

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

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