phronomy 0.25.0 → 0.26.0

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

@@ -3,20 +3,54 @@
 module Phronomy
   # A thread-free asynchronous completion handle.
   #
-  # Task does not execute work. Execution belongs to EventLoop/FSMSession or
-  # OffloadPool. Task represents completion, failure, cancellation, callbacks,
+  # TaskResult does not execute work. Execution belongs to EventLoop/FSMSession or
+  # OffloadPool. TaskResult represents completion, failure, cancellation, callbacks,
   # and a blocking wait for callers outside EventLoop.
   #
-  # Framework components own Task settlement. Application code should observe a
-  # Task through {#wait_result}, {#on_complete}, {#map}, and state readers rather
+  # Framework components own TaskResult settlement. Application code should observe a
+  # TaskResult through {#wait_result}, {#on_complete}, {#map}, and state readers rather
   # than calling {#complete}, {#fail}, or {#cancel!}. Operation-wide cancellation
   # is supplied through the CancellationToken accepted by the API that created
-  # the Task.
-  class Task
+  # the TaskResult.
+  class TaskResult
     STATES = %i[pending completed failed cancelled].freeze
     TERMINAL_STATES = %i[completed failed cancelled].freeze
     private_constant :TERMINAL_STATES
 
+    # A shallow immutable input-position record. Application values are retained
+    # by reference; they are neither copied nor frozen by this record.
+    # @api public
+    class Outcome < Struct.new(:index, :status, :value, :error)
+      def initialize(**fields)
+        super
+        freeze
+      end
+    end
+
+    # Observe already-created results without taking ownership of their work.
+    # Invalid inputs are rejected before any completion subscription is added.
+    # @param results [Array<TaskResult>]
+    # @return [TaskResult<Array<Outcome>>]
+    # @raise [TypeError] for a non-Array list or non-TaskResult element
+    # @api public
+    def self.all_settled(results)
+      raise TypeError, "results must be an Array" unless results.is_a?(Array)
+
+      inputs = results.dup
+      inputs.each_with_index do |result, index|
+        unless result.is_a?(Phronomy::TaskResult)
+          raise TypeError, "results[#{index}] must be a Phronomy::TaskResult"
+        end
+      end
+      combined = Phronomy::TaskResult.deferred(name: "all-settled")
+      collector = Concurrency::ResultCollector.new(inputs.length) do |_, outcomes|
+        combined.complete(outcomes)
+      end
+      inputs.each_with_index { |result, index| collector.watch(index, result) }
+      collector.finish(:completed)
+      combined
+    end
+
     # Creates an unsettled completion handle for framework-owned execution.
     # @api private
     def self.deferred(name: nil, parent: nil)
@@ -24,26 +58,26 @@ module Phronomy
     end
 
     # Public factories for already-settled values. No execution is started.
-    # Always create a base Task: there is no physical worker to supervise.
+    # Always create a base TaskResult: there is no physical worker to supervise.
     # @param value [Object] already available result
     # @param name [String, nil] optional diagnostic name
-    # @return [Phronomy::Task] a completed base Task
+    # @return [Phronomy::TaskResult] a completed base TaskResult
     # @api public
     def self.completed(value = nil, name: nil)
-      Phronomy::Task.deferred(name: name).tap { |task| task.complete(value) }
+      Phronomy::TaskResult.deferred(name: name).tap { |task| task.complete(value) }
     end
 
     # Represents an already known failure without raising the stored error.
     # Observation through wait_result raises it; on_complete receives it.
     # @param error [Exception] original failure object
     # @param name [String, nil] optional diagnostic name
-    # @return [Phronomy::Task] a failed base Task
+    # @return [Phronomy::TaskResult] a failed base TaskResult
     # @raise [ArgumentError] if error is not an Exception
     # @api public
     def self.failed(error, name: nil)
       raise ArgumentError, "error must be an Exception" unless error.is_a?(Exception)
 
-      Phronomy::Task.deferred(name: name).tap { |task| task.fail(error) }
+      Phronomy::TaskResult.deferred(name: name).tap { |task| task.fail(error) }
     end
 
     attr_reader :name, :parent
@@ -68,13 +102,13 @@ module Phronomy
       @mutex.synchronize { @status }
     end
 
-    # @return [Boolean] whether the Task has reached a terminal state
+    # @return [Boolean] whether the TaskResult has reached a terminal state
     # @api public
     def done?
       @mutex.synchronize { TERMINAL_STATES.include?(@status) }
     end
 
-    # @return [Boolean] whether the Task has not yet reached a terminal state
+    # @return [Boolean] whether the TaskResult has not yet reached a terminal state
     # @api public
     def alive?
       !done?
@@ -82,19 +116,19 @@ module Phronomy
 
     # Blocks the calling thread until settlement.
     #
-    # EventLoop is never allowed to wait for a Task; framework continuation must
+    # EventLoop is never allowed to wait for a TaskResult; framework continuation must
     # proceed through explicit events. The optional timeout is waiter-local: it
-    # does not settle or cancel the Task.
+    # does not settle or cancel the TaskResult.
     #
     # @param timeout [Numeric, nil] maximum seconds this caller will block
     # @return [Object] the completed value
     # @raise [Phronomy::TimeoutError] when the waiter-local timeout expires
-    # @raise [Exception] the error that settled the Task
+    # @raise [Exception] the error that settled the TaskResult
     # @api public
     def wait_result(timeout: nil)
       if Phronomy::Runtime.in_event_loop_context? && !done?
         raise Phronomy::EventLoopReentrancyError,
-          "Task#wait_result cannot block the EventLoop thread; continue via an event"
+          "TaskResult#wait_result cannot block the EventLoop thread; continue via an event"
       end
 
       deadline = timeout && monotonic_now + timeout.to_f
@@ -104,7 +138,7 @@ module Phronomy
             remaining = deadline - monotonic_now
             if remaining <= 0
               raise Phronomy::TimeoutError,
-                "timed out waiting for Task #{@name || "(unnamed)"}"
+                "timed out waiting for TaskResult #{@name || "(unnamed)"}"
             end
             @cond.wait(@mutex, remaining)
           else
@@ -118,13 +152,13 @@ module Phronomy
       value
     end
 
-    # Compatibility wait that does not re-raise the Task error.
+    # Compatibility wait that does not re-raise the TaskResult error.
     # Returns self when settled, nil on timeout.
     # @api private
     def join(limit = nil)
       if Phronomy::Runtime.in_event_loop_context? && !done?
         raise Phronomy::EventLoopReentrancyError,
-          "Task#join cannot block the EventLoop thread; continue via an event"
+          "TaskResult#join cannot block the EventLoop thread; continue via an event"
       end
 
       deadline = limit && monotonic_now + limit.to_f
@@ -148,7 +182,7 @@ module Phronomy
     # registers after settlement, an OffloadPool worker, or a framework control
     # thread. Callbacks must therefore be thread-safe and should complete quickly.
     # A callback failure is logged and does not suppress delivery to other
-    # completion callbacks or change the Task's already-settled result.
+    # completion callbacks or change the TaskResult's already-settled result.
     #
     # @yield [value, error]
     # @return [self]
@@ -168,53 +202,74 @@ module Phronomy
       self
     end
 
-    # Settles this Task successfully. Framework-owned settlement API.
+    # Settles this TaskResult successfully. Framework-owned settlement API.
     # @api private
     def complete(value = nil)
       settle!(:completed, value: value)
     end
 
-    # Settles this Task with a failure. Framework-owned settlement API.
+    # Settles this TaskResult with a failure. Framework-owned settlement API.
     # @api private
     def fail(error)
       raise ArgumentError, "error is required" unless error
       settle!(:failed, error: error)
     end
 
-    # Settles this Task as cancelled. Framework-owned settlement API.
+    # Settles this TaskResult as cancelled. Framework-owned settlement API.
     #
     # This method does not propagate backwards into a CancellationToken that may
-    # have been used to create the Task. Tokens can be shared across operations;
+    # have been used to create the TaskResult. Tokens can be shared across operations;
     # operation-wide cancellation is owned by the creating API.
     # @api private
-    def cancel!(error = Phronomy::CancellationError.new("Task cancelled"))
+    def cancel!(error = Phronomy::CancellationError.new("TaskResult cancelled"))
       changed = settle!(:cancelled, error: error)
       if changed
         children = @mutex.synchronize { @children.dup }
-        children.each(&:cancel!)
+        children.each { |child| child.cancel!(error) }
       end
       self
     end
 
-    # Creates a derived Task by transforming this Task's successful result.
+    # Creates a derived TaskResult by transforming this TaskResult's successful result.
     # @api public
     def map(&block)
       raise ArgumentError, "map requires a block" unless block
 
-      mapped = self.class.deferred(name: "#{@name}-mapped", parent: @parent)
-      on_complete do |value, error|
-        if error
-          mapped.fail(error)
-          next
-        end
+      Concurrency::ResultComposition.new(self, flatten: false, &block).start
+    end
 
-        begin
-          mapped.complete(block.call(value))
-        rescue => mapped_error
-          mapped.fail(mapped_error)
-        end
-      end
-      mapped
+    # Transform a successful value into the result of another asynchronous step.
+    # The block must return a TaskResult. No implicit wrapping or nested value
+    # flattening is performed by map.
+    # @return [TaskResult]
+    # @api public
+    def flat_map(&block)
+      raise ArgumentError, "flat_map requires a block" unless block
+
+      Concurrency::ResultComposition.new(self, flatten: true, &block).start
+    end
+
+    # Atomic state observation and removable framework subscriptions.
+    # @api private
+    def __snapshot
+      @mutex.synchronize { [@status, @value, @error] }
+    end
+
+    # @api private
+    def __unsubscribe(callback)
+      @mutex.synchronize { @on_complete_callbacks.delete(callback) }
+    end
+
+    # Bound at admission, before application code can attach continuations.
+    # @api private
+    def __bind_execution(execution)
+      @execution_scope = execution
+      self
+    end
+
+    # @api private
+    def __execution_scope
+      @execution_scope
     end
 
     protected
@@ -250,7 +305,7 @@ module Phronomy
       callback.call(value, error)
     rescue => callback_error
       Phronomy.configuration.logger&.error do
-        "[Task] on_complete callback raised #{callback_error.class}: #{callback_error.message}"
+        "[TaskResult] on_complete callback raised #{callback_error.class}: #{callback_error.message}"
       end
     end
 

data/lib/phronomy/execution.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Thread-free fan-out/fan-in. Each input block returns the final TaskResult for
+  # that JOB; its application-defined intermediate work is not discovered here.
+  # @api public
+  class Execution
+    # @return [InvocationContext] this execution's explicit operation context
+    # @api public
+    attr_reader :invocation_context
+
+    # @param inputs [Array] shallowly snapshotted JOB inputs
+    # @param timeout [Numeric, nil] whole-execution deadline in seconds
+    # @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?
+        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
+    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)
+      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)
+        raise TypeError, "cancellation_token must be a Phronomy::Concurrency::CancellationToken or nil"
+      end
+      if !invocation_context.nil? && !invocation_context.is_a?(InvocationContext)
+        raise TypeError, "invocation_context must be a Phronomy::InvocationContext or nil"
+      end
+      unless timeout.nil?
+        raise TypeError, "timeout must be Numeric or nil" unless timeout.is_a?(Numeric)
+        if timeout.is_a?(Complex) || !timeout.finite? || !timeout.to_f.finite?
+          raise ArgumentError, "timeout must be a finite real number"
+        end
+      end
+      new(inputs.dup, timeout: timeout, cancellation_token: cancellation_token,
+        invocation_context: invocation_context, concurrency_limit: concurrency_limit,
+        &block).send(:start)
+    end
+    private_class_method :__run_async
+
+    # Common admission binding for Agent and synchronous-work adapters.
+    # @api private
+    def self.__operation_binding(invocation_context:, cancellation_token:)
+      Concurrency::OperationBinding.new(invocation_context: invocation_context,
+        cancellation_token: cancellation_token)
+    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.
+    # @param source_result [TaskResult]
+    # @return [TaskResult] a distinct scoped observation result
+    # @raise [TypeError] for a non-TaskResult source
+    # @api public
+    def observe(source_result)
+      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)
+      subscriptions = Concurrency::Subscriptions.new
+      subscriptions.result(observed) { subscriptions.close }
+      unless __open?
+        observed.cancel!(__cancellation_error)
+        return observed
+      end
+      subscriptions.result(source_result) do
+        status, value, error = source_result.__snapshot
+        if !__open? && status == :completed
+          observed.cancel!(__cancellation_error)
+        elsif status == :completed
+          observed.complete(value)
+        elsif status == :cancelled
+          observed.cancel!(error)
+        else
+          observed.fail(error)
+        end
+      end
+      subscriptions.cancellation(@token) { observed.cancel!(__cancellation_error) }
+      observed
+    end
+
+    # Scope/admission hooks shared with framework-owned operations.
+    # @api private
+    def __while_open(&block)
+      @collector.while_open(&block)
+    end
+
+    # @api private
+    def __open?
+      @collector.open?
+    end
+
+    # @api private
+    def __cancellation_token
+      @token
+    end
+
+    # @api private
+    def __cancellation_error
+      @cancellation_error
+    end
+
+    private
+
+    def initialize(inputs, timeout:, cancellation_token:, invocation_context:,
+      concurrency_limit:, &block)
+      @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @inputs = inputs
+      @block = block
+      @timeout = timeout
+      @parent_context = invocation_context
+      @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
+      @active = 0
+      @draining = false
+      @limit = concurrency_limit || [inputs.length, 1].max
+      @collector = Concurrency::ResultCollector.new(inputs.length) do |kind, outcomes|
+        finish(kind, outcomes)
+      end
+    end
+
+    def start
+      # All slots and control state exist before any registration can fire.
+      [@parent_token, @parent_context&.cancellation_token].compact.uniq.each do |token|
+        @subscriptions.cancellation(token) { @collector.finish(:cancelled) }
+      end
+      if @parent_context&.__execution_scope && !@parent_context.__execution_scope.__open?
+        @collector.finish(:cancelled)
+      end
+      if @parent_context&.deadline
+        @subscriptions.after(@parent_context.deadline.remaining_seconds) { @collector.finish(:cancelled) }
+      end
+      if @timeout
+        remaining = @timeout - (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at)
+        @subscriptions.after(remaining) { @collector.finish(:timeout) }
+      end
+      @collector.finish(:completed) if @inputs.empty?
+      drain
+      @result
+    end
+
+    def drain
+      claimed = @pump_mutex.synchronize do
+        next false if @draining
+        @draining = true
+      end
+      return unless claimed
+
+      loop do
+        work = @collector.while_open do
+          @pump_mutex.synchronize do
+            if @active < @limit && @next_index < @inputs.length
+              index = @next_index
+              @next_index += 1
+              @active += 1
+              [index, @inputs[index], @block]
+            else
+              @draining = false
+              nil
+            end
+          end
+        end
+        unless work
+          @pump_mutex.synchronize { @draining = false } unless __open?
+          break
+        end
+        index, input, start_block = work
+        begin
+          result = start_block.call(input, self)
+          unless result.is_a?(TaskResult)
+            raise TypeError, "JOB at inputs[#{index}] must return a Phronomy::TaskResult"
+          end
+        rescue => error
+          result = TaskResult.failed(error, name: "execution-job-#{index}")
+        end
+        @collector.watch(index, result) do
+          @pump_mutex.synchronize { @active -= 1 }
+          drain
+        end
+      end
+    end
+
+    def finish(kind, outcomes)
+      @subscriptions.close
+      # A retained scoped result needs the closed-scope gate, not all original
+      # inputs and the application start closure. A claimed start keeps its own
+      # local copy so cancellation during admission does not invalidate it.
+      @pump_mutex.synchronize do
+        @inputs = []
+        @block = nil
+      end
+      case kind
+      when :completed
+        @result.complete(outcomes)
+      when :timeout
+        @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")
+        error = ExecutionCancellationError.new(outcomes: outcomes)
+        @token.cancel!
+        @result.cancel!(error)
+      end
+    end
+  end
+end

data/lib/phronomy/execution_cancellation_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class ExecutionCancellationError < CancellationError
+    attr_reader :outcomes
+
+    def initialize(message = "Execution cancelled", outcomes:)
+      @outcomes = outcomes
+      super(message)
+    end
+  end
+end

data/lib/phronomy/execution_timeout_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class ExecutionTimeoutError < TimeoutError
+    attr_reader :outcomes
+
+    def initialize(message = "Execution timed out", outcomes:)
+      @outcomes = outcomes
+      super(message)
+    end
+  end
+end

data/lib/phronomy/invalid_async_entry_action_error.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Raised when a synchronous FSM entry action returns Phronomy::Task.
+  # Raised when a synchronous FSM entry action returns Phronomy::TaskResult.
   #
   # Entry actions are Run-to-Completion callbacks. They may start asynchronous
   # work, but completion must return through a later explicit event.

data/lib/phronomy/invalid_async_transition_action_error.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Raised when a synchronous Workflow transition action returns Phronomy::Task.
+  # Raised when a synchronous Workflow transition action returns Phronomy::TaskResult.
   #
   # Transition actions are Run-to-Completion callbacks. They may start
   # asynchronous work, but completion must return through a later explicit event.

data/lib/phronomy/invalid_async_workflow_action_error.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Base error for synchronous Workflow callbacks that return Phronomy::Task.
+  # Base error for synchronous Workflow callbacks that return Phronomy::TaskResult.
   #
   # Workflow callbacks may start asynchronous work, but they must return
   # synchronously and deliver completion through a later explicit event.

data/lib/phronomy/invocation_context.rb

@@ -56,7 +56,19 @@ module Phronomy
         redaction_policy: overrides.fetch(:redaction_policy, @redaction_policy),
         task_id: overrides.fetch(:task_id, @task_id),
         parent_task_id: overrides.fetch(:parent_task_id, @parent_task_id)
-      )
+      ).__bind_execution(@execution_scope)
+    end
+
+    # Framework-owned metadata; not inferred from the executing Ruby thread.
+    # @api private
+    def __bind_execution(execution)
+      @execution_scope = execution
+      self
+    end
+
+    # @api private
+    def __execution_scope
+      @execution_scope
     end
 
     # @api private

data/lib/phronomy/llm_adapter/base.rb

@@ -52,7 +52,7 @@ module Phronomy
       # Transport timeout and retry remain the responsibility of the adapter or
       # provider client; Phronomy does not attach an additional operation timeout.
       #
-      # @return [Phronomy::Task] caller-facing completion handle
+      # @return [Phronomy::TaskResult] caller-facing completion handle
       # @api private
       def complete_async(chat, message, config: {}, pool: default_pool)
         token = config[:cancellation_token]
@@ -68,7 +68,7 @@ module Phronomy
       # application callbacks must never be passed directly to this method.
       #
       # @yield [chunk] streaming chunk on the worker thread
-      # @return [Phronomy::Task] caller-facing completion handle
+      # @return [Phronomy::TaskResult] caller-facing completion handle
       # @api private
       def stream_async(chat, message, config: {}, pool: default_pool, &block)
         raise ArgumentError, "stream_async requires a block" unless block

data/lib/phronomy/multi_agent/durable_subagent_coordinator.rb

@@ -4,7 +4,7 @@ require "securerandom"
 
 module Phronomy
   module MultiAgent
-    # Agent-owned transactions reserve child work; Task callbacks only wake observers.
+    # Agent-owned transactions reserve child work; TaskResult callbacks only wake observers.
     # @api private
     class DurableSubagentCoordinator
       KEY = "multi_agent_coordination_ref"
@@ -47,7 +47,7 @@ module Phronomy
 
       def self.start(parent:, tool_invocation_id:, parent_execution_id:, config:)
         runtime = Phronomy::Runtime.instance
-        completion = Phronomy::Task.deferred(name: "durable-subagent:#{tool_invocation_id}")
+        completion = Phronomy::TaskResult.deferred(name: "durable-subagent:#{tool_invocation_id}")
         preparation = runtime.offload.submit(on_full: :raise) do
           current = parent.persistence.executions.load(parent_execution_id)
           raise Phronomy::Persistence::ConflictError, "Parent owner mismatch" unless current.agent_id == parent.agent_id
@@ -125,7 +125,7 @@ module Phronomy
         end
         completion
       rescue => error
-        completion ||= Phronomy::Task.deferred(name: "durable-subagent")
+        completion ||= Phronomy::TaskResult.deferred(name: "durable-subagent")
         completion.fail(error)
         completion
       end