phronomy 0.27.0 → 0.29.0

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/{engine → 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,11 +69,30 @@ 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
+
+    # 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 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
     # keep their original ownership. Bind before adding this run's map/flat_map.
@@ -70,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?
@@ -96,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
@@ -111,7 +145,7 @@ module Phronomy
 
     # @api private
     def __cancellation_error
-      @cancellation_error
+      @scope.__cancellation_error
     end
 
     private
@@ -126,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
@@ -138,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
@@ -214,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/{engine → execution}/execution_cancellation_error.rb

@@ -6,9 +6,9 @@ module Phronomy
   class ExecutionCancellationError < CancellationError
     attr_reader :outcomes
 
-    def initialize(message = "Execution cancelled", outcomes:)
+    def initialize(message = "Execution cancelled", outcomes:, code: nil)
       @outcomes = outcomes
-      super(message)
+      super(message, code: code)
     end
   end
 end

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/{engine → execution}/execution_timeout_error.rb

@@ -6,9 +6,9 @@ module Phronomy
   class ExecutionTimeoutError < TimeoutError
     attr_reader :outcomes
 
-    def initialize(message = "Execution timed out", outcomes:)
+    def initialize(message = "Execution timed out", outcomes:, code: nil)
       @outcomes = outcomes
-      super(message)
+      super(message, code: code)
     end
   end
 end

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

data/lib/phronomy/execution/invocation_controls.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Owns invocation control attachment through the observed result's lifetime.
+  # Domain runners carry this operation control, not execution scope internals.
+  # @api private
+  class InvocationControls
+    attr_reader :token
+
+    def self.attach(result, invocation_context:, cancellation_token:)
+      controls = new(invocation_context: invocation_context, cancellation_token: cancellation_token)
+      controls.bind(result)
+      controls
+    rescue
+      controls&.close
+      raise
+    end
+
+    def initialize(invocation_context:, cancellation_token:)
+      if !invocation_context.nil? && !invocation_context.is_a?(InvocationContext)
+        raise TypeError, "invocation_context must be a Phronomy::InvocationContext or nil"
+      end
+      @scope = invocation_context&.__execution_scope
+      @subscriptions = Concurrency::Subscriptions.new
+      @token = invocation_context ? Concurrency::CancellationToken.new : cancellation_token
+      return unless invocation_context
+
+      [invocation_context.cancellation_token, cancellation_token].compact.uniq.each do |source|
+        @subscriptions.cancellation(source) { @token.cancel! }
+      end
+      if !@scope && invocation_context.deadline
+        @subscriptions.after(invocation_context.deadline.remaining_seconds) { @token.cancel! }
+      end
+      @token.cancel! if @scope && !@scope.__open?
+    rescue
+      close
+      raise
+    end
+
+    # Check at the receiving runner, after asynchronous delivery. An already
+    # closed scope must not acquire the domain's admission slot or start I/O.
+    def check_start!
+      if @scope && (!@scope.__open? || @token&.cancelled?)
+        raise @scope.__cancellation_error
+      end
+    end
+
+    def bind(result)
+      result.__bind_execution(@scope)
+      track(result)
+    end
+
+    def track(result)
+      @subscriptions.result(result) { close }
+      result
+    end
+
+    def close
+      @subscriptions&.close
+    end
+
+    def self.effective_timeout_token(context)
+      return context.cancellation_token if context.cancellation_token
+      return nil unless context.deadline
+
+      token = Concurrency::CancellationToken.new
+      subscriptions = Concurrency::Subscriptions.new
+      subscriptions.cancellation(token) { subscriptions.close }
+      subscriptions.after(context.deadline.remaining_seconds) { token.cancel! }
+      token
+    end
+  end
+end

data/lib/phronomy/execution/runnable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Base interface for executable graph components.
+  # Provides invoke / stream / batch.
+  module Runnable
+    # Synchronous execution. Must be overridden in subclasses.
+    def invoke(input, config: {})
+      raise NotImplementedError, "#{self.class}#invoke is not implemented"
+    end
+
+    # Streaming execution. Default yields the invoke result as a single chunk.
+    def stream(input, config: {}, &block)
+      result = invoke(input, config: config)
+      yield result if block
+      result
+    end
+
+    # Batch execution. Default calls invoke sequentially.
+    def batch(inputs, config: {})
+      inputs.map { |input| invoke(input, config: config) }
+    end
+  end
+end

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

@@ -130,7 +130,7 @@ module Phronomy
     # @raise [Exception] the error that settled the TaskResult
     # @api public
     def wait_result(timeout: nil)
-      if Phronomy::Runtime.in_event_loop_context? && !done?
+      if Phronomy::WaitPolicy.blocking_forbidden? && !done?
         raise Phronomy::EventLoopReentrancyError,
           "TaskResult#wait_result cannot block the EventLoop thread; continue via an event"
       end
@@ -160,7 +160,7 @@ module Phronomy
     # Returns self when settled, nil on timeout.
     # @api private
     def join(limit = nil)
-      if Phronomy::Runtime.in_event_loop_context? && !done?
+      if Phronomy::WaitPolicy.blocking_forbidden? && !done?
         raise Phronomy::EventLoopReentrancyError,
           "TaskResult#join cannot block the EventLoop thread; continue via an event"
       end
@@ -308,8 +308,13 @@ module Phronomy
     def deliver_completion_callback(callback, value, error)
       callback.call(value, error)
     rescue => callback_error
-      Phronomy.configuration.logger&.error do
-        "[TaskResult] on_complete callback raised #{callback_error.class}: #{callback_error.message}"
+      begin
+        Phronomy::RuntimeSettings.current.logger&.error do
+          "[TaskResult] on_complete callback raised #{callback_error.class}: #{callback_error.message}"
+        end
+      rescue
+        # Reporting must not interrupt delivery to the remaining observers.
+        nil
       end
     end
 

data/lib/phronomy/execution/wait_policy.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Neutral thread-local blocking policy. It owns no Runtime or scheduler.
+  # No invocation context is inferred from this marker.
+  # @api private
+  module WaitPolicy
+    KEY = :phronomy_control_thread_depth
+    private_constant :KEY
+
+    def self.blocking_forbidden?
+      Thread.current.thread_variable_get(KEY).to_i > 0
+    end
+
+    def self.without_blocking
+      thread = Thread.current
+      previous = thread.thread_variable_get(KEY)
+      thread.thread_variable_set(KEY, previous.to_i + 1)
+      yield
+    ensure
+      thread.thread_variable_set(KEY, previous)
+    end
+  end
+end

data/lib/phronomy/filter/{contract/filter_block_error.rb → filter_block_error.rb}

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "../../common/error"
+require_relative "../common/error"
 
 module Phronomy
   class FilterBlockError < Error
     attr_reader :filter
 
-    def initialize(message, filter: nil)
-      super(message)
+    def initialize(message, filter: nil, code: nil)
+      super(message, code: code)
       @filter = filter
     end
   end