phronomy 0.26.0 → 0.28.0

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

@@ -22,10 +22,10 @@ module Phronomy
 
       begin
         unless invocation_context.nil?
-          binding = Execution.__operation_binding(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/execution/cancellation_error.rb

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

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

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "worker_input_restricted"
+
 module Phronomy
   module Concurrency
     # Cooperative cancellation token for Agent/Tool work.
     class CancellationToken
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       # Creates a token that expires after +seconds+ measured with the monotonic clock.
       # @api public
       def self.timeout_after(seconds)
@@ -94,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

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

@@ -2,10 +2,9 @@
 
 module Phronomy
   module Concurrency
-    # Disposable registrations. add also handles synchronous notification during
-    # registration: cleanup added after close is performed immediately.
+    # Completion and explicit-cancellation subscriptions. No timer acquisition.
     # @api private
-    class Subscriptions
+    class ResultSubscriptions
       def initialize
         @mutex = Mutex.new
         @closed = false
@@ -29,27 +28,24 @@ module Phronomy
         add { result.__unsubscribe(callback) }
       end
 
-      def cancellation(token, &callback)
+      # Own the lifetime of explicit-cancellation notifications only. An elapsed
+      # deadline is not promoted to a notification here. close can race delivery:
+      # a callback already taken by cancel! may still run, as with the token API.
+      # Registration may deliver inline and close this collection before add;
+      # add then immediately disposes the completed registration.
+      # @api private
+      def explicit_cancellation(token, &callback)
         return unless token
 
         token.on_cancel(&callback)
         add { token.send(:unregister_cancel_callback, callback) }
-        remaining = token.remaining_monotonic_seconds
-        if token.cancelled?
-          callback.call
-        elsif remaining
-          after(remaining, &callback)
-        end
       end
 
-      def after(seconds, &callback)
-        if seconds <= 0
-          callback.call
-          return
-        end
-        timer = Phronomy::Runtime.instance.timer_queue
-        timer.schedule(seconds: seconds, &callback)
-        add { timer.cancel(callback) }
+      def cancellation(token, &callback)
+        return unless token
+
+        explicit_cancellation(token, &callback)
+        callback.call if token.cancelled?
       end
 
       def close

data/lib/phronomy/execution/concurrency/subscriptions.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # Services promotes deadlines into control notifications.
+    # @api private
+    class Subscriptions < ResultSubscriptions
+      def cancellation(token, &callback)
+        return unless token
+
+        super
+        remaining = token.remaining_monotonic_seconds
+        after(remaining, &callback) if !token.cancelled? && remaining
+      end
+
+      def after(seconds, &callback)
+        if seconds <= 0
+          callback.call
+          return
+        end
+        add(&Phronomy::Execution.after(seconds, &callback))
+      end
+    end
+  end
+end

data/lib/phronomy/execution/concurrency/worker_input_restricted.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # Marks framework-managed objects excluded from authorization worker value
+    # snapshots and application behavior handles. Each owning type opts in.
+    # This methodless contract does not validate arbitrary object graphs or
+    # restrict every OffloadPool command. Application-owned opaque values retain
+    # their existing contract (ADR-024/045).
+    # @api private
+    module WorkerInputRestricted
+    end
+  end
+end

data/lib/phronomy/execution/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 → execution/execution.rb}

@@ -5,6 +5,28 @@ module Phronomy
   # that JOB; its application-defined intermediate work is not discovered here.
   # @api public
   class Execution
+    # Composition installs the mechanism. Public values and settled results do
+    # not access it; only scheduling/submission requires a configured backend.
+    class << self
+      attr_writer :backend_provider
+
+      def submit(**options, &operation)
+        raise ArgumentError, "Execution.submit requires a block" unless operation
+        backend.submit(**options, &operation)
+      end
+
+      def after(seconds, &callback)
+        raise ArgumentError, "Execution.after requires a block" unless callback
+        backend.after(seconds, &callback)
+      end
+
+      private
+
+      def backend
+        @backend_provider&.call || raise(ConfigurationError, "Execution backend has not been configured")
+      end
+    end
+
     # @return [InvocationContext] this execution's explicit operation context
     # @api public
     attr_reader :invocation_context
@@ -14,32 +36,25 @@ module Phronomy
     # @param cancellation_token [Concurrency::CancellationToken, nil]
     # @param invocation_context [InvocationContext, nil] existing information/controls
     # @yield [input, execution] starts one JOB and returns its final TaskResult
-    # @return [TaskResult<Array<TaskResult::Outcome>>]
-    # @api public
-    def self.run_async(inputs, timeout: nil, cancellation_token: nil,
-      invocation_context: nil, &block)
-      __run_async(inputs, timeout: timeout, cancellation_token: cancellation_token,
-        invocation_context: invocation_context, &block)
-    end
-
     # Starts the same execution once and waits outside EventLoop.
     # @return [Array<TaskResult::Outcome>]
     # @see run_async
     # @api public
     def self.run(inputs, timeout: nil, cancellation_token: nil,
-      invocation_context: nil, &block)
-      if Runtime.in_event_loop_context?
+      invocation_context: nil, max_concurrency: nil, &block)
+      if WaitPolicy.blocking_forbidden?
         raise EventLoopReentrancyError, "Execution.run cannot run on EventLoop; use run_async"
       end
       run_async(inputs, timeout: timeout, cancellation_token: cancellation_token,
-        invocation_context: invocation_context, &block).wait_result
+        invocation_context: invocation_context, max_concurrency: max_concurrency, &block).wait_result
     end
 
-    # Existing Orchestrator concurrency policy uses the same execution engine.
-    # This is not an additional public execution entrance or scheduling mode.
-    # @api private
-    def self.__run_async(inputs, timeout: nil, cancellation_token: nil,
-      invocation_context: nil, concurrency_limit: nil, &block)
+    # Starts bounded fan-out without exposing collector or child bindings.
+    # @param max_concurrency [Integer, nil] maximum concurrently admitted JOBs
+    # @return [TaskResult<Array<TaskResult::Outcome>>]
+    # @api public
+    def self.run_async(inputs, timeout: nil, cancellation_token: nil,
+      invocation_context: nil, max_concurrency: nil, &block)
       raise TypeError, "inputs must be an Array" unless inputs.is_a?(Array)
       raise ArgumentError, "Execution.run_async requires a block" unless block
       if !cancellation_token.nil? && !cancellation_token.is_a?(Concurrency::CancellationToken)
@@ -54,17 +69,29 @@ module Phronomy
           raise ArgumentError, "timeout must be a finite real number"
         end
       end
+      if !max_concurrency.nil? && !(max_concurrency.is_a?(Integer) && max_concurrency.positive?)
+        raise ArgumentError, "max_concurrency must be a positive Integer"
+      end
       new(inputs.dup, timeout: timeout, cancellation_token: cancellation_token,
-        invocation_context: invocation_context, concurrency_limit: concurrency_limit,
+        invocation_context: invocation_context, concurrency_limit: max_concurrency,
         &block).send(:start)
     end
-    private_class_method :__run_async
 
-    # Common admission binding for Agent and synchronous-work adapters.
+    # Starts one child with this execution's controls and the child's explicit
+    # context. Subscriptions live until the child settles, including start errors.
+    # A child-specific context keeps its own controls; the supplied token adds
+    # this execution's cancellation without mutating either original token.
     # @api private
-    def self.__operation_binding(invocation_context:, cancellation_token:)
-      Concurrency::OperationBinding.new(invocation_context: invocation_context,
+    def start_child(invocation_context: nil, cancellation_token: nil, parent_task_id: nil)
+      controls = InvocationControls.new(invocation_context: @invocation_context,
         cancellation_token: cancellation_token)
+      controls.check_start!
+      child_context = invocation_context || @invocation_context.merge(parent_task_id: parent_task_id)
+      result = yield child_context, controls.token
+      controls.track(result)
+    rescue
+      controls&.close
+      raise
     end
 
     # A scoped observation copy. The source, its controls and its physical work
@@ -77,7 +104,7 @@ module Phronomy
       unless source_result.is_a?(TaskResult)
         raise TypeError, "source_result must be a Phronomy::TaskResult"
       end
-      observed = TaskResult.deferred(name: "execution-observation").__bind_execution(self)
+      observed = TaskResult.deferred(name: "execution-observation").__bind_execution(@scope)
       subscriptions = Concurrency::Subscriptions.new
       subscriptions.result(observed) { subscriptions.close }
       unless __open?
@@ -103,12 +130,12 @@ module Phronomy
     # Scope/admission hooks shared with framework-owned operations.
     # @api private
     def __while_open(&block)
-      @collector.while_open(&block)
+      @scope.__while_open(&block)
     end
 
     # @api private
     def __open?
-      @collector.open?
+      @scope.__open?
     end
 
     # @api private
@@ -118,7 +145,7 @@ module Phronomy
 
     # @api private
     def __cancellation_error
-      @cancellation_error
+      @scope.__cancellation_error
     end
 
     private
@@ -133,9 +160,6 @@ module Phronomy
       @parent_token = cancellation_token
       @token = Concurrency::CancellationToken.new
       @subscriptions = Concurrency::Subscriptions.new
-      @cancellation_error = CancellationError.new("Execution scope is closed")
-      @invocation_context = (invocation_context || InvocationContext.new)
-        .merge(cancellation_token: @token).__bind_execution(self)
       @result = TaskResult.deferred(name: "execution")
       @pump_mutex = Mutex.new
       @next_index = 0
@@ -145,6 +169,9 @@ module Phronomy
       @collector = Concurrency::ResultCollector.new(inputs.length) do |kind, outcomes|
         finish(kind, outcomes)
       end
+      @scope = ExecutionScopeState.new(collector: @collector, token: @token)
+      @invocation_context = (invocation_context || InvocationContext.new)
+        .merge(cancellation_token: @token).__bind_execution(@scope)
     end
 
     def start
@@ -221,12 +248,12 @@ module Phronomy
       when :completed
         @result.complete(outcomes)
       when :timeout
-        @cancellation_error = CancellationError.new("Execution deadline exceeded")
+        @scope.__set_cancellation_error(CancellationError.new("Execution deadline exceeded"))
         error = ExecutionTimeoutError.new(outcomes: outcomes)
         @token.cancel!
         @result.fail(error)
       when :cancelled
-        @cancellation_error = CancellationError.new("Execution cancelled")
+        @scope.__set_cancellation_error(CancellationError.new("Execution cancelled"))
         error = ExecutionCancellationError.new(outcomes: outcomes)
         @token.cancel!
         @result.cancel!(error)

data/lib/phronomy/{execution_cancellation_error.rb → execution/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/execution/execution_receiver.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Internal lifecycle/delivery contract for feature-owned execution state.
+  # A receiver has one serial owner supplied by composition, not an application
+  # callback SPI. Normal mutation and delivery run only on that owner. idle?
+  # runs under its lifecycle lock and must not acquire that lock again.
+  # shutdown runs on the failing owner or exclusively after it joins.
+  # @api private
+  class ExecutionReceiver
+    def self.install_binding(provider)
+      raise ArgumentError, "Execution receiver provider must be callable" unless provider.respond_to?(:call)
+      @binding_provider = provider
+    end
+
+    def self.for(owner)
+      ExecutionReceiver.binding.receiver(self, owner)
+    end
+
+    def self.existing_for(owner)
+      ExecutionReceiver.binding.existing_receiver(self, owner)
+    end
+
+    def self.binding
+      @binding_provider&.call || raise(ConfigurationError, "Execution receiver binding has not been configured")
+    end
+
+    def initialize(channel:)
+      @channel = channel
+    end
+
+    def __bound_to?(owner)
+      @channel.bound_to?(owner)
+    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)
+      @channel.synchronize(&block)
+    end
+
+    def admit(&block)
+      @channel.admit(self, &block)
+    end
+
+    def post_message(message, admission: false, completion: nil)
+      @channel.post(self, message, admission: admission, completion: completion)
+    end
+
+    # Resolve a live routing target atomically with delivery. The channel owns
+    # the transport envelope; domain receivers return only a target identity.
+    def route_event(type:, payload: nil, &block)
+      @channel.route(self, type: type, payload: payload, &block)
+    end
+
+    def assert_event_loop_thread!
+      return if @channel.current?
+
+      raise Phronomy::Error,
+        "Phronomy-managed live execution state may only be mutated on EventLoop"
+    end
+  end
+end

data/lib/phronomy/execution/execution_scope_state.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # A scope gate shared by observations and framework operations. The same
+  # collector lock arbitrates admission and completion; no Execution is held.
+  # @api private
+  class ExecutionScopeState
+    def initialize(collector:, token:)
+      @collector = collector
+      @token = token
+      @error_mutex = Mutex.new
+      @error = CancellationError.new("Execution scope is closed")
+    end
+
+    def __while_open(&block)
+      @collector.while_open(&block)
+    end
+
+    def __open?
+      @collector.open?
+    end
+
+    def __cancellation_token
+      @token
+    end
+
+    def __cancellation_error
+      @error_mutex.synchronize { @error }
+    end
+
+    def __set_cancellation_error(error)
+      @error_mutex.synchronize { @error = error }
+    end
+  end
+end

data/lib/phronomy/{execution_timeout_error.rb → execution/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/{invalid_async_entry_action_error.rb → execution/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 → execution/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 → execution/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/{invocation_context.rb → execution/invocation_context.rb}

@@ -70,20 +70,5 @@ module Phronomy
     def __execution_scope
       @execution_scope
     end
-
-    # @api private
-    def effective_cancellation_token
-      @cancellation_token || Phronomy::Concurrency::CancellationToken.new
-    end
-
-    # @api private
-    def effective_timeout_token
-      return @cancellation_token if @cancellation_token
-      return nil if @deadline.nil?
-
-      token = Phronomy::Concurrency::CancellationToken.new
-      @deadline.attach_to(token)
-      token
-    end
   end
 end