phronomy 0.26.0 → 0.28.0

data/lib/phronomy/engine/execution_binding.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Engine implementation of the Execution mechanism protocol. Installing this
+  # binding does not acquire any resources; default Runtime is resolved on use.
+  # @api private
+  module ExecutionBinding
+    def self.submit(pool: nil, runtime: nil, pool_name: nil, size: 10,
+      queue_size: 100, **options, &operation)
+      unless pool
+        runtime ||= Runtime.instance
+        pool = pool_name ? runtime.pool(pool_name, size: size, queue_size: queue_size) : runtime.offload
+      end
+      pool.submit(**options, &operation)
+    end
+
+    def self.after(seconds, &callback)
+      timer = Runtime.instance.timer_queue
+      timer.schedule(seconds: seconds, &callback)
+      -> { timer.cancel(callback) }
+    end
+  end
+end

data/lib/phronomy/engine/execution_receiver_binding.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Concrete EventLoop transport and lifecycle registration for execution state.
+  # @api private
+  class ExecutionReceiverBinding
+    def self.receiver(receiver_class, event_loop)
+      event_loop.__execution_receiver(key: receiver_class) ||
+        event_loop.__register_execution_receiver(key: receiver_class,
+          receiver: receiver_class.new(channel: new(event_loop)))
+    end
+
+    def self.existing_receiver(receiver_class, runtime)
+      runtime.__event_loop_if_initialized&.__execution_receiver(key: receiver_class)
+    end
+
+    def initialize(event_loop)
+      @event_loop = event_loop
+    end
+
+    def bound_to?(owner) = @event_loop.equal?(owner)
+    def current? = @event_loop.current?
+
+    def synchronize(&block)
+      @event_loop.__synchronize_execution_state(&block)
+    end
+
+    def admit(receiver, &block)
+      @event_loop.__admit_execution(receiver, &block)
+    end
+
+    def post(receiver, message, admission:, completion:)
+      @event_loop.__post_execution(receiver, message, admission: admission, completion: completion)
+    end
+
+    def route(receiver, type:, payload:)
+      @event_loop.__route_execution_event(receiver) do
+        target = yield
+        target && Phronomy::Event.new(type: type, target_id: target, payload: payload)
+      end
+    end
+  end
+end

data/lib/phronomy/engine/fsm_protocol.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Internal terminal vocabulary shared only by FSM adapters and sessions.
+  # @api private
+  module FSMProtocol
+    FINISH = :__end__
+  end
+end

data/lib/phronomy/engine/fsm_session.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../execution/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
 
@@ -400,7 +407,7 @@ module Phronomy
       )
       return if accepted
 
-      Phronomy.configuration.logger&.warn(
+      Phronomy::RuntimeSettings.current.logger&.warn(
         "[Phronomy::FSMSession] EventLoop rejected recovery-required event for #{@id}"
       )
     end
@@ -415,7 +422,7 @@ module Phronomy
       )
       return if accepted
 
-      Phronomy.configuration.logger&.warn(
+      Phronomy::RuntimeSettings.current.logger&.warn(
         "[Phronomy::FSMSession] EventLoop rejected terminal event " \
           "#{type.inspect} for #{@id}"
       )

data/lib/phronomy/engine/metrics.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Runtime observability snapshot for the two concurrency boundaries:
+  # EventLoop and the default OffloadPool. Observation never creates resources;
+  # missing resources contribute zero values. Individual counters are sampled
+  # independently, not as an atomic view of concurrent execution.
+  module Metrics
+    def self.snapshot
+      runtime = Runtime.__default_if_initialized
+      pool = runtime&.__offload_if_initialized
+      event_loop = runtime&.__event_loop_if_initialized
+
+      {
+        offload_pool_active: pool&.active_count || 0,
+        offload_pool_queue_length: pool&.queue_depth || 0,
+        offload_pool_abandoned_active: pool&.abandoned_active_count || 0,
+        offload_pool_abandoned_total: pool&.abandoned_count || 0,
+        offload_pool_size: pool&.pool_size || 0,
+        event_loop_queue_depth: event_loop&.queue_depth || 0,
+        event_loop_queue_max_depth: event_loop&.max_queue_depth || 0,
+        event_loop_lag_last_ms: ((event_loop&.last_lag_seconds || 0.0) * 1000).round(3),
+        event_loop_lag_max_ms: ((event_loop&.max_lag_seconds || 0.0) * 1000).round(3),
+        event_loop_lag_average_ms: ((event_loop&.average_lag_seconds || 0.0) * 1000).round(3)
+      }
+    end
+  end
+end

data/lib/phronomy/engine/runtime/timer_queue.rb

@@ -68,7 +68,7 @@ module Phronomy
         callbacks.each do |callback|
           callback.call
         rescue => error
-          Phronomy.configuration.logger&.error do
+          Phronomy::RuntimeSettings.current.logger&.error do
             "[TimerQueue] callback raised #{error.class}: #{error.message}"
           end
         end

data/lib/phronomy/engine/runtime.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "../execution/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
@@ -15,10 +17,16 @@ module Phronomy
         instance_mutex.synchronize { @instance ||= new }
       end
 
-      def default_if_initialized_for_test
+      # Lookup only: diagnostics must not initialize the default Runtime.
+      # @api private
+      def __default_if_initialized
         instance_mutex.synchronize { @instance }
       end
 
+      def default_if_initialized_for_test
+        __default_if_initialized
+      end
+
       def replace_default_for_test(runtime)
         instance_mutex.synchronize do
           previous = @instance
@@ -31,7 +39,7 @@ module Phronomy
         instance_mutex.synchronize { @instance = runtime }
       end
 
-      def reset_default!(timeout: Phronomy.configuration.event_loop_stop_grace_seconds)
+      def reset_default!(timeout: Phronomy::RuntimeSettings.current.event_loop_stop_grace_seconds)
         runtime = instance_mutex.synchronize { @instance }
         return ShutdownResult.not_started unless runtime
 
@@ -48,8 +56,7 @@ module Phronomy
       end
 
       def in_event_loop_context?
-        runtime = instance_mutex.synchronize { @instance }
-        runtime&.event_loop_current? || false
+        Phronomy::WaitPolicy.blocking_forbidden?
       end
 
       private
@@ -64,9 +71,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
@@ -80,8 +86,8 @@ module Phronomy
     end
 
     def offload(
-      pool_size: Phronomy.configuration.offload_pool_size,
-      queue_size: Phronomy.configuration.offload_queue_size
+      pool_size: Phronomy::RuntimeSettings.current.offload_pool_size,
+      queue_size: Phronomy::RuntimeSettings.current.offload_queue_size
     )
       ensure_accepting_work!
       @pool_registry.default_pool(pool_size: pool_size, queue_size: queue_size)
@@ -92,6 +98,12 @@ module Phronomy
       @pool_registry.named_pool(name, size: size, queue_size: queue_size)
     end
 
+    # Lookup only; retained pools remain observable during and after shutdown.
+    # @api private
+    def __offload_if_initialized
+      @pool_registry.default_pool_if_initialized
+    end
+
     def timer_queue
       ensure_accepting_work!
       timer = @timer_service.timer_queue
@@ -103,83 +115,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
-
+    # Lookup only; inspection must not create an EventLoop during shutdown.
     # @api private
-    def __abort_agent_purge(agent, token)
-      @agent_ownership_registry.abort_purge(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 __leave_agent_purge_uncertain(agent, token)
-      @agent_ownership_registry.leave_purge_uncertain(agent, token)
-    end
-
-    # @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,11 +183,12 @@ module Phronomy
 
         @failure ||= error
         @state = :failed
+        begin_draining_participants
       end
     end
 
     def shutdown(
-      timeout: Phronomy.configuration.event_loop_stop_grace_seconds,
+      timeout: Phronomy::RuntimeSettings.current.event_loop_stop_grace_seconds,
       cancel_grace: timeout
     )
       if event_loop_current?
@@ -232,17 +202,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
@@ -256,12 +223,17 @@ module Phronomy
           :not_started
         end
 
-        subsystem_error = shutdown_pools_and_timer
-        cleanup_complete = admission_idle && agent_ownership_stable && team_ownership_stable && loop_idle &&
+        pools_stopped, subsystem_error = shutdown_pools_and_timer(deadline: stop_deadline)
+        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?) &&
+          pools_stopped &&
           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 +241,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 +259,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)
@@ -298,10 +306,11 @@ module Phronomy
         "Runtime is #{current_state}; new work is not accepted"
     end
 
-    def shutdown_pools_and_timer
+    def shutdown_pools_and_timer(deadline:)
       error = nil
+      pools_stopped = false
       begin
-        @pool_registry.shutdown
+        pools_stopped = @pool_registry.shutdown(deadline: deadline)
       rescue => caught
         error ||= caught
       ensure
@@ -311,7 +320,7 @@ module Phronomy
           error ||= caught
         end
       end
-      error
+      [pools_stopped, error]
     end
 
     def validate_timeout!(value, name)

data/lib/phronomy/engine/terminal_decision.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Mechanism-neutral completion/failure/retirement decision.
+  # @api private
+  TerminalDecision = Data.define(:action, :error)
+end

data/lib/phronomy/execution/async_operation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Completion adaptation for framework operations. Owns start-error capture,
+  # once-only propagation, error-to-value policy and physical completion tracking.
+  # Callers supply domain transformations, never completion setters or callbacks.
+  # @api private
+  module AsyncOperation
+    def self.map(source, name:, on_error: nil, &transform)
+      raise ArgumentError, "async mapping requires a block" unless transform
+      unless source.respond_to?(:on_complete)
+        raise TypeError, "asynchronous operation must return a completion handle"
+      end
+      Concurrency::ResultComposition.new(source, flatten: false, name: name,
+        completion_only: true, recover: on_error, &transform).start
+    end
+
+    # Capture synchronous preparation/start errors under the same domain policy.
+    def self.call(name:, on_error: nil, transform: ->(value) { value })
+      source = begin
+        yield
+      rescue => error
+        TaskResult.failed(error, name: name)
+      end
+      map(source, name: name, on_error: on_error, &transform)
+    end
+
+    # Short synchronous fallback/validation only; never offloads or awaits work.
+    def self.capture(name:, on_error: nil)
+      value = yield
+      TaskResult.completed(value, name: name)
+    rescue => error
+      begin
+        raise error unless on_error
+        TaskResult.completed(on_error.call(error), name: name)
+      rescue => failure
+        TaskResult.failed(failure, name: name)
+      end
+    end
+  end
+end

data/lib/phronomy/execution/backpressure_error.rb

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