phronomy 0.27.0 → 0.29.0

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "worker_input_restricted"
+require_relative "../../execution/concurrency/worker_input_restricted"
 
 module Phronomy
   module Concurrency
@@ -81,14 +81,12 @@ module Phronomy
           @submitted_at = submitted_at ||
             Process.clock_gettime(Process::CLOCK_MONOTONIC)
           @mutex = Mutex.new
-          @timer_subscriptions = Subscriptions.new
+          @timer_subscriptions = ResultSubscriptions.new
+          @cancellation_subscriptions = ResultSubscriptions.new
 
           # Explicit submit cancellation is operation-wide. Deadline-only tokens are
           # promoted to cancel! by OffloadPool#submit using the Runtime timer queue.
-          @cancellation_callback = if @cancellation_token
-            -> { fire_cancellation! }
-          end
-          @cancellation_token&.on_cancel(&@cancellation_callback)
+          @cancellation_subscriptions.explicit_cancellation(@cancellation_token) { fire_cancellation! }
         end
 
         # @return [Boolean] true when caller-facing settlement has been claimed
@@ -260,7 +258,7 @@ module Phronomy
         def notify_abandoned
           @on_abandoned&.call(self)
         rescue => error
-          Phronomy.configuration.logger&.error do
+          Phronomy::RuntimeSettings.current.logger&.error do
             "OffloadPool abandoned callback failed: #{error.class}: #{error.message}"
           end
         end
@@ -293,13 +291,7 @@ module Phronomy
 
         def detach_submit_cancellation
           @timer_subscriptions.close
-          return unless @cancellation_token && @cancellation_callback
-
-          @cancellation_token.send(
-            :unregister_cancel_callback,
-            @cancellation_callback
-          )
-          @cancellation_callback = nil
+          @cancellation_subscriptions.close
         end
       end
       private_constant :Operation
@@ -384,7 +376,7 @@ module Phronomy
         full_timeout: nil,
         &block
       )
-        if Phronomy::Runtime.in_event_loop_context? && on_full != :raise
+        if Phronomy::WaitPolicy.blocking_forbidden? && on_full != :raise
           raise Phronomy::EventLoopReentrancyError,
             "OffloadPool admission cannot wait on EventLoop; use on_full: :raise"
         end
@@ -491,19 +483,42 @@ module Phronomy
         task
       end
 
-      # Gracefully drains the pool and terminates all worker threads.
-      # Waits up to +drain_timeout+ seconds for in-flight operations to finish.
+      # Close admission without waiting for worker termination. Already queued
+      # operations drain normally; running workers are never interrupted.
+      # @api private
+      def begin_shutdown
+        @shutdown = true
+        @queue.close
+        self
+      end
+
+      # Whether shutdown has closed admission and all workers have exited.
+      # Logical TaskResult settlement alone does not establish this fact.
+      # @api private
+      def terminated?
+        @shutdown && @workers.none?(&:alive?)
+      end
+
+      # Gracefully drains the pool and waits for worker threads to terminate.
+      # All workers share +drain_timeout+ or the supplied monotonic +deadline+.
+      # A deadline expiry leaves workers running; callers inspect terminated?.
       #
       # Closing the underlying SizedQueue signals workers to exit after draining
       # remaining items, without blocking on a full-queue push.
       #
       # @param drain_timeout [Numeric] seconds to wait for workers to finish
+      # @param deadline [Numeric, nil] absolute monotonic shutdown deadline
       # @return [self]
       # @api private
-      def shutdown(drain_timeout: 30)
-        @shutdown = true
-        @queue.close
-        @workers.each { |thread| thread.join(drain_timeout) }
+      def shutdown(drain_timeout: 30, deadline: nil)
+        deadline ||= Process.clock_gettime(Process::CLOCK_MONOTONIC) + drain_timeout
+        begin_shutdown
+        @workers.each do |thread|
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break if remaining <= 0
+
+          thread.join(remaining)
+        end
         self
       end
 

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