phronomy 0.25.0 → 0.27.0

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

@@ -0,0 +1,229 @@
+# 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
+
+    # 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/engine/execution_cancellation_error.rb

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

data/lib/phronomy/engine/execution_receiver.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Internal lifecycle/delivery contract for feature-owned execution state.
+  # Receivers are retained by one EventLoop, not an application callback SPI.
+  # Normal mutation and delivery run only on that loop. idle? runs with its
+  # lifecycle lock held; it must not call Runtime or acquire that lock again.
+  # shutdown runs on a failing loop, or exclusively after a clean loop joins.
+  # @api private
+  class ExecutionReceiver
+    def self.for(event_loop)
+      event_loop.__execution_receiver(key: self) ||
+        event_loop.__register_execution_receiver(key: self, receiver: new(event_loop: event_loop))
+    end
+
+    # Lookup only: neither a loop nor a receiver is created during inspection.
+    def self.existing_for(runtime)
+      runtime.__event_loop_if_initialized&.__execution_receiver(key: self)
+    end
+
+    def initialize(event_loop:)
+      @event_loop = event_loop
+    end
+
+    def __bound_to?(event_loop)
+      @event_loop.equal?(event_loop)
+    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)
+      @event_loop.__synchronize_execution_state(&block)
+    end
+
+    def admit(&block)
+      @event_loop.__admit_execution(self, &block)
+    end
+
+    def post_message(message, admission: false, completion: nil)
+      @event_loop.__post_execution(self, message, admission: admission, completion: completion)
+    end
+
+    def assert_event_loop_thread!
+      return if @event_loop.current?
+
+      raise Phronomy::Error,
+        "Phronomy-managed live execution state may only be mutated on EventLoop"
+    end
+  end
+end

data/lib/phronomy/engine/execution_timeout_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "timeout_error"
+
+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/engine/fsm_protocol.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Shared terminal-state vocabulary and domain decisions for FSM execution.
+  # This protocol does not depend on a particular runner or session instance.
+  # @api private
+  module FSMProtocol
+    FINISH = :__end__
+
+    # A domain policy permits completion, reports failure, or retires a session
+    # without settling its caller. It never carries live session authority.
+    TerminalDecision = Data.define(:action, :error)
+  end
+end

data/lib/phronomy/engine/fsm_session.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
+require_relative "concurrency/worker_input_restricted"
+
 require "securerandom"
 
 module Phronomy
   # Event-driven execution wrapper for a single FSM session.
   #
   # All public methods are called from the Runtime-owned EventLoop thread.
-  # FSMSession owns FSM execution only; it does not own external Task handles,
+  # FSMSession owns FSM execution only; it does not own external TaskResult handles,
   # activity tokens, callback correlation, or domain-specific stale-event policy.
   class FSMSession
+    include Phronomy::Concurrency::WorkerInputRestricted
+
     class IdentityReservation
       attr_reader :fsm_session_id
 
@@ -30,6 +34,8 @@ module Phronomy
     private_constant :IdentityReservation
 
     class EventSink
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       attr_reader :fsm_session_id
 
       def initialize(event_loop:)
@@ -60,8 +66,6 @@ module Phronomy
       end
     end
 
-    FINISH = WorkflowRunner::FINISH
-
     attr_reader :id, :context, :event_sink
 
     # Returns the live current Workflow phase. During an active FSM transition
@@ -95,7 +99,7 @@ module Phronomy
       context_metadata: {},
       event_sink: nil,
       identity_reservation: nil,
-      terminal_barrier: nil
+      terminal_policy: nil
     )
       @id = if identity_reservation
         unless identity_reservation.is_a?(IdentityReservation)
@@ -123,7 +127,7 @@ module Phronomy
       @resume_event = resume_event
       @resume_phase = resume_phase
       @stable_observer = stable_observer
-      @terminal_barrier = terminal_barrier
+      @terminal_policy = terminal_policy
       @terminal_lifecycle_state = :running
       @pending_terminal_type = nil
       @pending_terminal_notify_stable = false
@@ -160,14 +164,13 @@ module Phronomy
     def handle(event)
       return if @done
 
-      if event.type == :workflow_terminal_persistence_result
-        handle_terminal_persistence_result(event.payload)
+      if @terminal_policy&.handles?(event)
+        handle_terminal_event(event)
         return
       end
 
-      # Once terminal persistence begins, ordinary Workflow events no longer
-      # have result authority. Only the persistence completion for this concrete
-      # FSMSession can advance its terminal lifecycle.
+      # Once a terminal decision is pending, ordinary events cannot advance
+      # the state machine. Only the injected policy can permit terminalization.
       return unless @terminal_lifecycle_state == :running
 
       context_disposition = apply_context_event(event)
@@ -195,9 +198,9 @@ module Phronomy
     end
 
     def apply_synchronous_action_result!(result, state_name)
-      if result.is_a?(Phronomy::Task)
+      if result.is_a?(Phronomy::TaskResult)
         raise Phronomy::InvalidAsyncEntryActionError,
-          "Entry action for state #{state_name.inspect} returned Phronomy::Task. " \
+          "Entry action for state #{state_name.inspect} returned Phronomy::TaskResult. " \
           "Start the asynchronous operation, register its callback/listener, " \
           "and return the WorkflowContext or nil."
       end
@@ -261,7 +264,7 @@ module Phronomy
     end
 
     def advance_or_halt
-      return finish! if @current_state == FINISH
+      return finish! if @current_state == FSMProtocol::FINISH
 
       # A wait state is the logical end of this Workflow execution segment. Its
       # public stable-state notification is therefore part of terminalization
@@ -324,7 +327,7 @@ module Phronomy
     def finish!(notify_stable: false)
       request_terminal!(
         :finished,
-        phase: :__end__,
+        phase: FSMProtocol::FINISH,
         notify_stable: notify_stable
       )
     end
@@ -339,13 +342,13 @@ module Phronomy
       apply_context_metadata!(phase: phase)
       @pending_terminal_type = terminal_type
       @pending_terminal_notify_stable = notify_stable
-      unless @terminal_barrier
+      unless @terminal_policy
         complete_terminal!(terminal_type)
         return
       end
 
-      @terminal_lifecycle_state = :persisting_terminal
-      @terminal_barrier.call(
+      @terminal_lifecycle_state = :awaiting_terminal
+      @terminal_policy.start(
         terminal_type: terminal_type,
         context: @ctx,
         event_sink: @event_sink
@@ -354,31 +357,35 @@ module Phronomy
       finish_with_error(error)
     end
 
-    def handle_terminal_persistence_result(result)
-      return unless @terminal_lifecycle_state == :persisting_terminal
+    def handle_terminal_event(event)
+      return unless @terminal_lifecycle_state == :awaiting_terminal
 
-      case result.outcome
-      when :success
+      decision = @terminal_policy.decision_for(event)
+      case decision.action
+      when :complete
         complete_terminal!(@pending_terminal_type)
-      when :known_failure
-        finish_with_error(
-          result.error || Phronomy::Error.new("Workflow terminal persistence failed")
-        )
-      when :outcome_unknown
-        @done = true
-        @terminal_lifecycle_state = :recovery_required
-        post_recovery_required_event(result.error)
+      when :fail
+        finish_with_error(decision.error)
+      when :retire
+        retire_without_result!(decision.error)
       else
         raise Phronomy::Error,
-          "unknown Workflow terminal persistence outcome: #{result.outcome.inspect}"
+          "unknown FSM terminal decision: #{decision.action.inspect}"
       end
     end
 
-    def complete_terminal!(terminal_type)
+    def retire_without_result!(error)
       @done = true
+      @terminal_lifecycle_state = :retired
+      post_recovery_required_event(error)
+    end
+
+    def complete_terminal!(terminal_type)
       @terminal_lifecycle_state =
         (terminal_type == :halted) ? :halted : :completed
+      # Keep the error path open until the observer returns successfully.
       notify_stable_state! if @pending_terminal_notify_stable
+      @done = true
       post_terminal_event(terminal_type, @ctx)
     end
 

data/lib/phronomy/{invalid_async_entry_action_error.rb → engine/invalid_async_entry_action_error.rb}

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "invalid_async_workflow_action_error"
+
 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 → engine/invalid_async_transition_action_error.rb}

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "invalid_async_workflow_action_error"
+
 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 → engine/invalid_async_workflow_action_error.rb}

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "../common/error"
+
 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 → engine/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/engine/pool_shutdown_error.rb

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

data/lib/phronomy/engine/recursion_limit_error.rb

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

data/lib/phronomy/engine/runtime/timer_queue.rb

@@ -44,6 +44,17 @@ module Phronomy
         end
       end
 
+      # Remove this registration without changing another user's timers. A
+      # callback already taken by fire_due may still run; owners arbitrate once.
+      # @api private
+      def cancel(callback)
+        @mutex.synchronize do
+          before = @heap.length
+          @heap.delete_if { |(_, registered)| registered == callback }
+          before != @heap.length
+        end
+      end
+
       # Executes all callbacks whose deadline is due. Must be called by EventLoop.
       def fire_due
         callbacks = @mutex.synchronize do