phronomy 0.27.0 → 0.28.0

data/lib/phronomy/engine/concurrency/pool_registry.rb

@@ -16,6 +16,7 @@ module Phronomy
         @mutex = Mutex.new
         @pools = {}
         @default = nil
+        @closed = false
       end
 
       # Returns (or lazily creates) the unnamed default pool.
@@ -24,12 +25,22 @@ module Phronomy
       # @return [OffloadPool]
       # @api private
       def default_pool(pool_size: 10, queue_size: 100)
-        @default ||= OffloadPool.new(
-          name: :default,
-          pool_size: pool_size,
-          queue_size: queue_size,
-          timer_queue_provider: @timer_queue_provider
-        )
+        @mutex.synchronize do
+          ensure_open!
+          @default ||= OffloadPool.new(
+            name: :default,
+            pool_size: pool_size,
+            queue_size: queue_size,
+            timer_queue_provider: @timer_queue_provider
+          )
+        end
+      end
+
+      # Lookup only, including after registration has closed.
+      # @return [OffloadPool, nil]
+      # @api private
+      def default_pool_if_initialized
+        @mutex.synchronize { @default }
       end
 
       # Returns (or lazily creates) a named pool.
@@ -40,6 +51,7 @@ module Phronomy
       # @api private
       def named_pool(name, size: 10, queue_size: 100)
         @mutex.synchronize do
+          ensure_open!
           @pools[name.to_sym] ||= OffloadPool.new(
             name: name,
             pool_size: size,
@@ -49,13 +61,36 @@ module Phronomy
         end
       end
 
-      # Shuts down the default pool and all named pools.
-      # @return [void]
+      # Closes registration and every pool before waiting, outside the registry
+      # lock. All pools share one absolute monotonic deadline. Attempt every
+      # cleanup even if one fails; report physical completion separately.
+      # @return [Boolean] whether every owned worker has stopped
       # @api private
-      def shutdown
-        @default&.shutdown
-        pools = @mutex.synchronize { @pools.values.dup }
-        pools.each(&:shutdown)
+      def shutdown(deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + 30)
+        pools = @mutex.synchronize do
+          @closed = true
+          [@default, *@pools.values].compact
+        end
+        error = nil
+        pools.each do |pool|
+          pool.begin_shutdown
+        rescue => caught
+          error ||= caught
+        end
+        pools.each do |pool|
+          pool.shutdown(deadline: deadline)
+        rescue => caught
+          error ||= caught
+        end
+        raise error if error
+
+        pools.all?(&:terminated?)
+      end
+
+      private
+
+      def ensure_open!
+        raise Phronomy::PoolShutdownError, "pool registry has been shut down" if @closed
       end
     end
   end

data/lib/phronomy/engine/diagnostics.rb

@@ -24,7 +24,7 @@ module Phronomy
     end
 
     def self.assert_not_in_event_loop!
-      return unless Phronomy::Runtime.in_event_loop_context?
+      return unless Phronomy::WaitPolicy.blocking_forbidden?
 
       raise Phronomy::EventLoopReentrancyError,
         "Blocking invoke called from inside an EventLoop action. Use invoke_async instead."

data/lib/phronomy/engine/event_loop.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "concurrency/worker_input_restricted"
+require_relative "../execution/concurrency/worker_input_restricted"
 
 module Phronomy
   # Runtime-owned FIFO event loop for FSMSession instances.
@@ -53,7 +53,7 @@ module Phronomy
       @dispatch_count = 0
       @total_lag_ns = 0
 
-      @thread = Thread.new { run_loop }
+      @thread = Thread.new { Phronomy::WaitPolicy.without_blocking { run_loop } }
       @thread.name = "phronomy-event-loop"
     end
 
@@ -632,7 +632,7 @@ module Phronomy
     end
 
     def warn_queue_backlog(message)
-      logger = Phronomy.configuration.logger
+      logger = Phronomy::RuntimeSettings.current.logger
       logger ? logger.warn(message) : Kernel.warn(message)
     rescue
       nil
@@ -648,11 +648,11 @@ module Phronomy
     end
 
     def check_starvation_lag(lag_ns, event)
-      threshold = Phronomy.configuration.event_loop_starvation_threshold_seconds
+      threshold = Phronomy::RuntimeSettings.current.event_loop_starvation_threshold_seconds
       return unless threshold
       return unless lag_ns > (threshold * 1_000_000_000)
 
-      Phronomy.configuration.logger&.warn do
+      Phronomy::RuntimeSettings.current.logger&.warn do
         "[Phronomy::EventLoop] Starvation detected: event #{event.type.inspect} " \
           "for target #{event.target_id.inspect} waited " \
           "#{format("%.3f", lag_ns / 1_000_000_000.0)}s in queue " \
@@ -661,13 +661,13 @@ module Phronomy
     end
 
     def check_dispatch_time(dispatch_start_ns, event)
-      threshold = Phronomy.configuration.event_loop_dispatch_threshold_seconds
+      threshold = Phronomy::RuntimeSettings.current.event_loop_dispatch_threshold_seconds
       return unless threshold
 
       elapsed_ns = monotonic_nanoseconds - dispatch_start_ns
       return unless elapsed_ns > (threshold * 1_000_000_000)
 
-      Phronomy.configuration.logger&.warn do
+      Phronomy::RuntimeSettings.current.logger&.warn do
         "[Phronomy::EventLoop] Long dispatch: event #{event.type.inspect} " \
           "for target #{event.target_id.inspect} took " \
           "#{format("%.3f", elapsed_ns / 1_000_000_000.0)}s on the EventLoop thread " \

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

@@ -1,14 +1,9 @@
 # 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.
+  # Internal terminal vocabulary shared only by FSM adapters and sessions.
   # @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,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "concurrency/worker_input_restricted"
+require_relative "../execution/concurrency/worker_input_restricted"
 
 require "securerandom"
 
@@ -407,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
@@ -422,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

@@ -2,24 +2,26 @@
 
 module Phronomy
   # Runtime observability snapshot for the two concurrency boundaries:
-  # EventLoop and OffloadPool.
+  # 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.instance
-      pool = runtime.offload
-      event_loop = runtime.event_loop
+      runtime = Runtime.__default_if_initialized
+      pool = runtime&.__offload_if_initialized
+      event_loop = runtime&.__event_loop_if_initialized
 
       {
-        offload_pool_active: pool.active_count,
-        offload_pool_queue_length: pool.queue_depth,
-        offload_pool_abandoned_active: pool.abandoned_active_count,
-        offload_pool_abandoned_total: pool.abandoned_count,
-        offload_pool_size: pool.pool_size,
-        event_loop_queue_depth: event_loop.queue_depth,
-        event_loop_queue_max_depth: event_loop.max_queue_depth,
-        event_loop_lag_last_ms: (event_loop.last_lag_seconds * 1000).round(3),
-        event_loop_lag_max_ms: (event_loop.max_lag_seconds * 1000).round(3),
-        event_loop_lag_average_ms: (event_loop.average_lag_seconds * 1000).round(3)
+        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

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,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "concurrency/worker_input_restricted"
+require_relative "../execution/concurrency/worker_input_restricted"
 
 require_relative "runtime/timer_queue"
 require_relative "runtime/shutdown_result"
@@ -17,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
@@ -33,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
 
@@ -50,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
@@ -81,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)
@@ -93,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
@@ -177,7 +188,7 @@ module Phronomy
     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?
@@ -212,13 +223,14 @@ module Phronomy
           :not_started
         end
 
-        subsystem_error = shutdown_pools_and_timer
+        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
@@ -294,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
@@ -307,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/{engine → execution}/blocking.rb

@@ -22,10 +22,10 @@ module Phronomy
 
       begin
         unless invocation_context.nil?
-          binding = Concurrency::OperationBinding.new(invocation_context: invocation_context,
+          binding = InvocationControls.new(invocation_context: invocation_context,
             cancellation_token: cancellation_token)
         end
-        result = Phronomy::Runtime.instance.offload.submit(
+        result = Phronomy::Execution.submit(
           on_full: :raise,
           timeout: timeout,
           cancellation_token: binding ? binding.token : cancellation_token,

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

@@ -98,7 +98,7 @@ module Phronomy
       def deliver_cancel_callback(callback)
         callback.call
       rescue => error
-        Phronomy.configuration.logger&.error do
+        Phronomy::RuntimeSettings.current.logger&.error do
           "[CancellationToken] on_cancel callback raised #{error.class}: #{error.message}"
         end
       end

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

@@ -42,23 +42,6 @@ module Phronomy
         remaining = @monotonic_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)
         [remaining, 0.0].max
       end
-
-      # Attaches this deadline to a {CancellationToken} by cancelling the token
-      # when the deadline expires. The Runtime timer queue is driven by EventLoop;
-      # no timer-specific OS thread is created.
-      #
-      # @param token [CancellationToken]
-      # @param timer_queue [Runtime::TimerQueue, nil] queue to register with;
-      #   defaults to +Phronomy::Runtime.instance.timer_queue+
-      # @return [self]
-      # @api private
-      def attach_to(token, timer_queue: Phronomy::Runtime.instance.timer_queue)
-        seconds = remaining_seconds
-        return self if seconds <= 0
-
-        timer_queue.schedule(seconds: seconds) { token.cancel! }
-        self
-      end
     end
   end
 end

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

@@ -68,7 +68,7 @@ module Phronomy
       def deliver_physical_callback(callback)
         callback.call
       rescue => error
-        Phronomy.configuration.logger&.error do
+        Phronomy::RuntimeSettings.current.logger&.error do
           "[PhysicalCompletionTask] callback raised #{error.class}: #{error.message}"
         end
       end

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

@@ -12,7 +12,7 @@ module Phronomy
         @remaining = size
         @closed = false
         @sources = {}.compare_by_identity
-        @subscriptions = Subscriptions.new
+        @subscriptions = ResultSubscriptions.new
         @finished = finished
       end
 

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

@@ -6,21 +6,26 @@ module Phronomy
     # boundary. Observing a result never mutates that result or its cancellation.
     # @api private
     class ResultComposition
-      def initialize(source, flatten:, &block)
+      def initialize(source, flatten:, name: nil, completion_only: false, recover: nil, &block)
         @source = source
-        @scope = source.__execution_scope
+        # Framework decorators also accept callback-only handles. They observe
+        # the source without inheriting application Execution controls or parents.
+        @completion_only = completion_only
+        @scope = completion_only ? nil : source.__execution_scope
         @flatten = flatten
         @block = block
-        physical = flatten || source.respond_to?(:on_physical_complete)
+        @recover = recover
+        physical = completion_only || flatten || source.respond_to?(:on_physical_complete)
         klass = physical ? PhysicalCompletionTask : TaskResult
-        @result = klass.deferred(name: "#{source.name}-#{flatten ? "flat-mapped" : "mapped"}",
-          parent: source.parent).__bind_execution(@scope)
+        result_name = name || "#{source.name}-#{flatten ? "flat-mapped" : "mapped"}"
+        @result = klass.deferred(name: result_name,
+          parent: completion_only ? nil : source.parent).__bind_execution(@scope)
         @mutex = Mutex.new
         @phase = :waiting
         @source_physical = !source.respond_to?(:on_physical_complete)
         @work_done = false
         @inner_physical = true
-        @subscriptions = Subscriptions.new
+        @subscriptions = ResultSubscriptions.new
       end
 
       def start
@@ -30,7 +35,18 @@ module Phronomy
             finish_physical
           end
         end
-        @subscriptions.result(@source) { receive_source }
+        if @completion_only
+          @source.on_complete do |value, error|
+            status = if error
+              (@source.respond_to?(:status) && @source.status == :cancelled) ? :cancelled : :failed
+            else
+              :completed
+            end
+            receive_source(status, value, error)
+          end
+        else
+          @subscriptions.result(@source) { receive_source(*@source.__snapshot) }
+        end
         if @scope
           @subscriptions.cancellation(@scope.__cancellation_token) { suppress }
           suppress unless @scope.__open?
@@ -40,9 +56,9 @@ module Phronomy
 
       private
 
-      def receive_source
-        status, value, error = @source.__snapshot
-        if status != :completed
+      def receive_source(status, value, error)
+        recovering = status != :completed
+        if recovering && !@recover
           started = @mutex.synchronize do
             next false unless @phase == :waiting
             @phase = :finished
@@ -66,12 +82,17 @@ module Phronomy
         end
         allowed = @scope ? @scope.__while_open(&claim) : claim.call
         unless allowed
-          suppress
+          suppress if @scope
           return
         end
 
         begin
-          transformed = @block.call(value)
+          transformed = begin
+            recovering ? @recover.call(error) : @block.call(value)
+          rescue => transformation_error
+            raise if recovering || !@recover
+            @recover.call(transformation_error)
+          end
           if @flatten && !transformed.is_a?(TaskResult)
             raise TypeError, "flat_map block must return a Phronomy::TaskResult"
           end