phronomy 0.27.0 → 0.28.0

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/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}/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,7 +308,7 @@ module Phronomy
     def deliver_completion_callback(callback, value, error)
       callback.call(value, error)
     rescue => callback_error
-      Phronomy.configuration.logger&.error do
+      Phronomy::RuntimeSettings.current.logger&.error do
         "[TaskResult] on_complete callback raised #{callback_error.class}: #{callback_error.message}"
       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,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../common/error"
+require_relative "../common/error"
 
 module Phronomy
   class FilterBlockError < Error

data/lib/phronomy/generation/generator_verifier/agent_operation.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    # Connects one reused Agent incarnation through its public operation and
+    # notification contracts. Terminal results belong to each returned TaskResult;
+    # only approval suspension needs the incarnation listener while that Task is
+    # still pending. Generation owns the request-to-Workflow correlation.
+    # @api private
+    class AgentOperation
+      def initialize(agent_class)
+        @mutex = Mutex.new
+        @pending = []
+        @agent = agent_class.new(on_event: method(:receive_event))
+      end
+
+      def start(input, listener:)
+        request = Object.new
+        # Workflow entry calls are serial. Keep submitted requests until their
+        # own result settles: Agent admission itself may run after an earlier
+        # request completes, so a pending submission is not necessarily busy.
+        @mutex.synchronize { @pending << [request, listener] }
+        task = @agent.invoke_async(input)
+        task.on_complete do |result, error|
+          release(request)
+          # Handoff was not a generation completion in the event-based path.
+          next if !error && result.is_a?(Hash) && result[:handoff_request]
+
+          event = if error
+            type = if error.is_a?(Phronomy::TimeoutError)
+              :timeout
+            elsif error.is_a?(Phronomy::CancellationError)
+              :cancelled
+            else
+              :error
+            end
+            Phronomy::Agent::StreamEvent.new(type: type, payload: {error: error})
+          else
+            Phronomy::Agent::StreamEvent.new(type: :done, payload: result)
+          end
+          listener.call(event)
+        end
+        task
+      rescue
+        release(request)
+        raise
+      end
+
+      private
+
+      def receive_event(event)
+        return unless event.type == :approval_required
+
+        listener = @mutex.synchronize { @pending.first&.last }
+        listener&.call(event)
+      end
+
+      def release(request)
+        @mutex.synchronize do
+          @pending.delete_if { |entry| entry.first.equal?(request) }
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/default_parser.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    # Boot supplies the default concrete parser. The generation algorithm owns
+    # its output interpretation and fallback, not the concrete parser selection.
+    # @api private
+    module DefaultParser
+      FACTORIES = {}
+      private_constant :FACTORIES
+
+      # Private one-time composition binding; not an application registry.
+      # @api private
+      def self.install_factory(factory)
+        raise ArgumentError, "factory must respond to call" unless factory.respond_to?(:call)
+
+        FACTORIES.replace(parser: factory).freeze
+        nil
+      end
+
+      # @api private
+      def self.build
+        FACTORIES.fetch(:parser).call
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/workflow_builder.rb

@@ -71,7 +71,7 @@ module Phronomy
           workflow_instance_id: next_state.workflow_instance_id,
           request_id: request_id
         )
-        @draft_agent.send(:__invoke_async_with_event_sink, prompt, on_event: listener)
+        @draft_agent.start(prompt, listener: listener)
         next_state
       end
 
@@ -86,7 +86,7 @@ module Phronomy
           workflow_instance_id: next_state.workflow_instance_id,
           request_id: request_id
         )
-        @review_agent.send(:__invoke_async_with_event_sink, prompt, on_event: listener)
+        @review_agent.start(prompt, listener: listener)
         next_state
       end