phronomy 0.28.0 → 0.29.0

data/lib/phronomy/tracing/open_telemetry_tracer.rb

@@ -53,38 +53,13 @@ module Phronomy
         span.finish
       end
 
-      # Overrides Base#trace to use OTel +in_span+, which pushes the span onto
-      # the OTel Context stack while the block runs.  Nested +trace+ calls
-      # automatically inherit the current span as their parent, establishing the
-      # correct parent/child hierarchy in the trace tree.
-      #
-      # @param name [String] span name
-      # @param input [Object, nil] input to record as a span attribute
-      # @param meta [Hash] additional metadata (e.g. task_id, user_id)
-      # @yield [span] the active OTel span
-      # @return [Object] the block's return value
+      # Preserve the backend context while sharing C15's exactly-once finish
+      # and primary-error protection. Context affinity remains backend-owned.
       # @api private
       def trace(name, input: nil, **meta)
-        attrs = {}
-        attrs["phronomy.input"] = input.to_s if input
-        meta.each { |k, v| attrs["phronomy.#{k}"] = v.to_s unless v.nil? }
-
-        result = nil
-        @otel_tracer.in_span(name, attributes: attrs) do |span|
-          result, usage = yield span
-          span.set_attribute("phronomy.output", result.to_s) if result
-          if usage
-            span.set_attribute("llm.usage.input_tokens", usage.input)
-            span.set_attribute("llm.usage.output_tokens", usage.output)
-            total = (usage.input || 0) + (usage.output || 0)
-            span.set_attribute("llm.usage.total_tokens", total)
-          end
-        rescue => e
-          span.record_exception(e)
-          span.status = OpenTelemetry::Trace::Status.error(e.message)
-          raise
+        Base.trace_with(self, name, attributes: {input: input, **meta.compact}) do |span|
+          OpenTelemetry::Trace.with_span(span) { yield span }
         end
-        result
       end
     end
   end

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.28.0"
+  VERSION = "0.29.0"
 end

data/lib/phronomy/workflow/execution/workflow.rb

@@ -85,6 +85,7 @@ module Phronomy
         @exit_actions = {}
         @transitions = []
         @wait_state_names = []
+        @task_states = {}
       end
 
       def initial(state_name) # rubocop:disable Style/TrivialAccessors
@@ -94,9 +95,10 @@ module Phronomy
       # Declares a Workflow state.
       #
       # Entry actions are synchronous Run-to-Completion callbacks. To start
-      # asynchronous work, register its listener/callback inside the action and
-      # return the context or nil. Returning Phronomy::TaskResult is an error.
+      # asynchronous work owned by this state, use task_state. Ordinary actions
+      # return the context or nil; returning Phronomy::TaskResult is an error.
       def state(name, action: nil)
+        reject_task_state_overlap!(name)
         @declared_states << name
         entry(name, action) if action
       end
@@ -110,9 +112,30 @@ module Phronomy
       end
 
       def wait_state(name)
+        reject_task_state_overlap!(name)
         @wait_state_names << name
       end
 
+      # Starts one asynchronous operation on state entry and advances only
+      # after its successful result has been applied on the execution owner.
+      # Task completion is correlated to this state entry, not a durable ID.
+      # @param name [Symbol] state name
+      # @param start [#call] short callback accepting a context snapshot and returning TaskResult
+      # @param apply [#call] short callback accepting current context and value; returns context or nil
+      # @return [void]
+      # @api public
+      def task_state(name, start:, apply:)
+        unless name.is_a?(Symbol) && start.respond_to?(:call) && apply.respond_to?(:call)
+          raise ArgumentError, "task_state requires a Symbol name and callable start/apply"
+        end
+        if @declared_states.include?(name) || @wait_state_names.include?(name)
+          raise ArgumentError, "Workflow state #{name.inspect} is already declared"
+        end
+        @declared_states << name
+        @task_states[name] = {start: start, apply: apply}.freeze
+        nil
+      end
+
       # Declares a transition.
       #
       # Guards and actions may accept either (context) or (context, event).
@@ -167,6 +190,7 @@ module Phronomy
           external_events: external_events,
           entry_point: @initial || @declared_states.first,
           wait_state_names: @wait_state_names.dup,
+          task_states: @task_states.dup.freeze,
           persistence: @persistence
         )
         Workflow.new(runner)
@@ -174,6 +198,10 @@ module Phronomy
 
       private
 
+      def reject_task_state_overlap!(name)
+        raise ArgumentError, "Workflow task_state #{name.inspect} is already declared" if @task_states.key?(name)
+      end
+
       def validate_graph!
         all_states = (@declared_states + @wait_state_names).uniq
         entry_point = @initial || @declared_states.first

data/lib/phronomy/workflow/execution/workflow_execution_environment.rb

@@ -23,5 +23,6 @@ module Phronomy
     def compile_transitions(**definition) = raise(NotImplementedError)
     def build_session(**options) = raise(NotImplementedError)
     def register_session(session, completion:) = raise(NotImplementedError)
+    def subscribe_cancellation(token, &callback) = raise(NotImplementedError)
   end
 end

data/lib/phronomy/workflow/execution/workflow_execution_registry.rb

@@ -12,10 +12,14 @@ module Phronomy
       :workflow_instance_id, :owner_token, :fsm_session_id, :state
     )
     private_constant :WorkflowAdmission
+    StopTaskExecutions = Data.define(:error)
+    private_constant :StopTaskExecutions
 
     def initialize(channel:)
       super
       @workflow_admissions = {}
+      @task_executions = {}
+      @draining = false
     end
 
     def post(command, admission: false, completion: nil)
@@ -24,7 +28,18 @@ module Phronomy
 
     def deliver(command)
       assert_event_loop_thread!
-      command.runner.deliver_on_event_loop(command)
+      case command
+      when WorkflowTaskReception::Notification
+        task_execution_for(command.reception)&.receive(command)
+      when WorkflowTaskReception::DeliveryFailure
+        task_execution_for(command.reception)&.delivery_failed(command.reception, command.error)
+      when WorkflowTaskReception::Cancellation
+        task_execution_for(command.reception)&.receive_cancellation(command.reception)
+      when StopTaskExecutions
+        synchronize { @task_executions.values.dup }.each { |execution| execution.stop(command.error) }
+      else
+        command.runner.deliver_on_event_loop(command)
+      end
     end
 
     def idle?
@@ -37,7 +52,49 @@ module Phronomy
     end
 
     def shutdown(error:)
-      synchronize { @workflow_admissions.clear }
+      executions = synchronize do
+        @workflow_admissions.clear
+        values = @task_executions.values
+        @task_executions.clear
+        values
+      end
+      failure = error || Phronomy::RuntimeShutdownError.new("Runtime stopped Workflow task execution")
+      executions.each { |execution| execution.retire(failure) }
+    end
+
+    # Called under Runtime's lifecycle lock. Only queue owner-side decisions;
+    # do not call application code or acquire Runtime again from here.
+    def begin_draining
+      first = synchronize do
+        next false if @draining
+        @draining = true
+      end
+      post(StopTaskExecutions.new(error: Phronomy::RuntimeShutdownError.new("Runtime stopped Workflow task execution"))) if first
+    end
+
+    def wait_until_idle(_deadline)
+      # EventLoop's existing admission/delivery accounting owns the drain wait.
+      true
+    end
+
+    def draining?
+      synchronize { @draining }
+    end
+
+    def bind_task_execution(execution)
+      assert_event_loop_thread!
+      synchronize { @task_executions[execution.owner_token] = execution }
+    end
+
+    def task_delivery_failed(reception, error)
+      return unless reception.active? && task_execution_for(reception)
+
+      failure = WorkflowTaskReception::DeliveryFailure.new(reception: reception, error: error)
+      return if post(failure)
+
+      fail_task_observer(reception, error)
+    rescue => delivery_error
+      fail_task_observer(reception, error || delivery_error)
     end
 
     # Reserves one logical Workflow execution segment before durable load or
@@ -121,13 +178,17 @@ module Phronomy
     def release_workflow(workflow_instance_id, owner_token:)
       assert_event_loop_thread!
       key = workflow_instance_id.to_s
-      synchronize do
+      execution = nil
+      released = synchronize do
         current = @workflow_admissions[key]
         next false unless current&.owner_token&.equal?(owner_token)
 
         @workflow_admissions.delete(key)
+        execution = @task_executions.delete(owner_token)
         true
       end
+      execution&.close
+      released
     end
 
     # Read-only diagnostics used by internal tests and routing assertions.
@@ -160,6 +221,16 @@ module Phronomy
 
     private
 
+    def task_execution_for(reception)
+      synchronize { @task_executions[reception.owner_token] }
+    end
+
+    def fail_task_observer(reception, error)
+      # A fully unavailable owner cannot safely release admission or claim a
+      # durable terminal result. Settle observation only; shutdown owns cleanup.
+      task_execution_for(reception)&.result_task&.fail(error) if reception.active?
+    end
+
     def mark_workflow_recovery_required_for_session(fsm_session_id)
       synchronize do
         key, admission = @workflow_admissions.find do |_workflow_instance_id, candidate|

data/lib/phronomy/workflow/execution/workflow_runner.rb

@@ -29,8 +29,13 @@ module Phronomy
       :recursion_limit,
       :repository,
       :persist,
-      :expected_revision
-    )
+      :expected_revision,
+      :cancellation_token
+    ) do
+      def initialize(cancellation_token: nil, **fields)
+        super(**fields, cancellation_token: cancellation_token)
+      end
+    end
 
     # API/callback -> EventLoop control messages.
     StartCommand = Data.define(
@@ -79,6 +84,7 @@ module Phronomy
       entry_point:,
       exit_actions: {},
       wait_state_names: [],
+      task_states: {},
       persistence: nil
     )
       @state_class = state_class
@@ -90,6 +96,7 @@ module Phronomy
       @external_events = external_events
       @entry_point = entry_point
       @wait_state_names = wait_state_names
+      @task_states = task_states
       @persistence = persistence
       @environment = WorkflowExecutionEnvironment.current
       @phase_machine_class = @environment.compile_transitions(
@@ -126,6 +133,7 @@ module Phronomy
     def send_event(state:, event:, input: nil)
       ensure_blocking_call_allowed!(:send_event, :signal)
       current_phase = state.phase.to_sym
+      reject_task_resume!(current_phase)
       event_name = resolve_resume_event(current_phase, event)
       workflow_instance_id = state.workflow_instance_id
       unless workflow_instance_id
@@ -300,7 +308,8 @@ module Phronomy
           repository: repository,
           persist: false,
           loaded_snapshot: nil,
-          expected_revision: nil
+          expected_revision: nil,
+          cancellation_token: request.config[:cancellation_token]
         )
         register_execution(
           execution,
@@ -344,7 +353,8 @@ module Phronomy
           recursion_limit: Phronomy::WorkflowSettings.current.recursion_limit,
           repository: nil,
           persist: false,
-          expected_revision: nil
+          expected_revision: nil,
+          cancellation_token: nil
         )
         register_execution(
           execution,
@@ -416,7 +426,8 @@ module Phronomy
         repository: ready.result.repository,
         persist: true,
         loaded_snapshot: ready.result.snapshot,
-        expected_revision: ready.result.revision
+        expected_revision: ready.result.revision,
+        cancellation_token: request.config[:cancellation_token]
       )
       register_execution(
         execution,
@@ -447,7 +458,8 @@ module Phronomy
         recursion_limit: Phronomy::WorkflowSettings.current.recursion_limit,
         repository: ready.result.repository,
         persist: true,
-        expected_revision: expected_revision
+        expected_revision: expected_revision,
+        cancellation_token: nil
       )
       register_execution(
         execution,
@@ -467,8 +479,11 @@ module Phronomy
       repository:,
       persist:,
       loaded_snapshot:,
-      expected_revision:
+      expected_revision:,
+      cancellation_token: nil
     )
+      stored_phase = loaded_snapshot && (loaded_snapshot[:phase] || loaded_snapshot["phase"])
+      reject_task_resume!(stored_phase&.to_sym)
       stored_fields = loaded_snapshot &&
         (loaded_snapshot[:fields] || loaded_snapshot["fields"])
       initial_fields = if stored_fields
@@ -489,7 +504,8 @@ module Phronomy
         recursion_limit: recursion_limit,
         repository: repository,
         persist: persist,
-        expected_revision: expected_revision
+        expected_revision: expected_revision,
+        cancellation_token: cancellation_token
       )
     end
 
@@ -563,12 +579,19 @@ module Phronomy
       stable_observer: nil
     )
       assert_execution_owner!
+      task_execution = unless @task_states.empty?
+        WorkflowTaskExecution.new(definitions: @task_states, registry: @environment.registry,
+          environment: @environment, owner_token: execution.owner_token, result_task: result_task,
+          cancellation_token: execution.cancellation_token)
+      end
       session = build_session_for(
         execution: execution,
         resume_event: resume_event,
         resume_phase: resume_phase,
-        stable_observer: stable_observer
+        stable_observer: stable_observer,
+        task_execution: task_execution
       )
+      @environment.registry.bind_task_execution(task_execution) if task_execution
       @environment.registry.bind_workflow_session(
         execution.workflow_instance_id,
         owner_token: execution.owner_token,
@@ -581,7 +604,8 @@ module Phronomy
           execution: execution,
           result_task: result_task,
           result: result,
-          error: error
+          error: error,
+          task_execution: task_execution
         )
       end
       @environment.register_session(session, completion: source_task)
@@ -598,13 +622,17 @@ module Phronomy
 
     # Called from source_task completion on EventLoop, after the FSMSession has
     # accepted the durable terminal result (when a durable barrier is required).
-    def finalize_execution(execution:, result_task:, result:, error:)
+    def finalize_execution(execution:, result_task:, result:, error:, task_execution: nil)
       assert_execution_owner!
       @environment.registry.release_workflow(
         execution.workflow_instance_id,
         owner_token: execution.owner_token
       )
-      error ? fail_task(result_task, error) : complete_task(result_task, result)
+      if error && task_execution&.cancelled_error&.equal?(error)
+        result_task.cancel!(error)
+      else
+        error ? fail_task(result_task, error) : complete_task(result_task, result)
+      end
     end
 
     def begin_terminal_persistence_on_event_loop(
@@ -741,7 +769,8 @@ module Phronomy
       execution:,
       resume_event: nil,
       resume_phase: nil,
-      stable_observer: nil
+      stable_observer: nil,
+      task_execution: nil
     )
       @environment.build_session(
         context: execution.context,
@@ -759,7 +788,8 @@ module Phronomy
         resume_event: resume_event,
         resume_phase: resume_phase,
         stable_observer: stable_observer,
-        persist: terminal_persistence_callback(execution)
+        persist: terminal_persistence_callback(execution),
+        task_execution: task_execution
       )
     end
 
@@ -798,6 +828,10 @@ module Phronomy
         "No external event registered for state #{current_phase.inspect}"
     end
 
+    def reject_task_resume!(phase)
+      raise Phronomy::WorkflowTaskResumeError if phase && @task_states.key?(phase)
+    end
+
     def post_control(command)
       admission = command.is_a?(StartCommand) || command.is_a?(ResumeCommand)
       completion = admission ? command.result_task : command.request.result_task

data/lib/phronomy/workflow/execution/workflow_task_execution.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # C02 owns which state admission may consume a TaskResult. The injected
+  # connection applies context/terminal decisions to the concrete state machine.
+  # @api private
+  class WorkflowTaskExecution
+    attr_reader :result_task, :owner_token, :cancelled_error
+
+    def initialize(definitions:, registry:, environment:, owner_token:, result_task:, cancellation_token: nil)
+      unless cancellation_token.nil? || cancellation_token.is_a?(Phronomy::Concurrency::CancellationToken)
+        raise TypeError, "cancellation_token must be a Phronomy::Concurrency::CancellationToken or nil"
+      end
+      @definitions = definitions
+      @registry = registry
+      @environment = environment
+      @owner_token = owner_token
+      @result_task = result_task
+      @cancellation_token = cancellation_token
+      @connection = nil
+      @reception = nil
+      @state_name = nil
+      @applied = false
+      @closed = false
+    end
+
+    def bind(connection)
+      @connection = connection
+    end
+
+    def activate
+      if @registry.draining?
+        stop(Phronomy::RuntimeShutdownError.new("Runtime is stopping Workflow task execution"))
+      elsif @cancellation_token&.cancelled?
+        cancel
+      elsif @cancellation_token
+        @cancel_reception = WorkflowTaskReception.new(registry: @registry, owner_token: @owner_token)
+        @cancel_subscription = @environment.subscribe_cancellation(
+          @cancellation_token, &@cancel_reception.method(:cancelled)
+        )
+      end
+    end
+
+    # Called after synchronous entry. true suppresses automatic completion.
+    def enter(state_name, context)
+      if @state_name != state_name
+        leave
+        @state_name = state_name
+        @entry_key = Object.new.freeze
+      end
+      return false unless @definitions.key?(state_name)
+      return !@applied if @reception || @applied
+
+      @reception = WorkflowTaskReception.new(registry: @registry, owner_token: @owner_token)
+      snapshot = context.merge({})
+      snapshot.set_graph_metadata(phase: state_name)
+      source = @definitions.fetch(state_name).fetch(:start).call(snapshot)
+      unless source.is_a?(Phronomy::TaskResult)
+        raise TypeError, "task_state #{state_name.inspect} start must return Phronomy::TaskResult"
+      end
+      @reception.watch(source)
+      true
+    end
+
+    # Queued automatic progression must belong to the same entry as the
+    # applied result, even if an external transition wins before dispatch.
+    def completion_key
+      return if @closed || (@definitions.key?(@state_name) && !@applied)
+
+      @entry_key
+    end
+
+    def permits_completion?(key)
+      key&.equal?(completion_key)
+    end
+
+    def receive(notification)
+      return unless current?(notification.reception)
+
+      definition = @definitions.fetch(@state_name)
+      @reception.close
+      @reception = nil
+      case notification.status
+      when :completed
+        context = @connection.context
+        updated = definition.fetch(:apply).call(context, notification.value)
+        unless updated.nil? || updated.is_a?(context.class)
+          raise TypeError, "task_state #{@state_name.inspect} apply must return its WorkflowContext or nil"
+        end
+        @applied = true
+        @connection.apply_task_context(updated || context)
+      when :cancelled
+        cancel(notification.error)
+      when :failed
+        stop(notification.error)
+      else
+        raise TypeError, "task_state received nonterminal TaskResult status #{notification.status.inspect}"
+      end
+    rescue => error
+      stop(error)
+    end
+
+    def delivery_failed(reception, error)
+      stop(error) if current?(reception) || (!@closed && reception.equal?(@cancel_reception))
+    end
+
+    def receive_cancellation(reception)
+      cancel if !@closed && reception.equal?(@cancel_reception)
+    end
+
+    def cancel(error = nil)
+      return if @closed
+
+      @cancelled_error = error || Phronomy::CancellationError.new("Workflow task execution cancelled")
+      stop(@cancelled_error)
+    end
+
+    def stop(error)
+      @connection&.fail_task_execution(error) unless @closed
+    end
+
+    def leave
+      @reception&.close
+      @reception = nil
+      @state_name = nil
+      @entry_key = nil
+      @applied = false
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      leave
+      @cancel_reception&.close
+      @cancel_subscription&.close
+      @cancel_reception = @cancel_subscription = @cancellation_token = nil
+      @connection = nil
+    end
+
+    # Unknown durable outcomes retain admission, but are still observable.
+    def retire(error)
+      close
+      @result_task.fail(error)
+    end
+
+    private
+
+    def current?(reception)
+      !@closed && reception.equal?(@reception) && @connection.current_state == @state_name
+    end
+  end
+end

data/lib/phronomy/workflow/execution/workflow_task_reception.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # A revocable, process-local completion address. The callback retains only
+  # this address; closing it drops its source and receiver, not the source work.
+  # @api private
+  class WorkflowTaskReception
+    Notification = Data.define(:reception, :status, :value, :error)
+    DeliveryFailure = Data.define(:reception, :error)
+    Cancellation = Data.define(:reception)
+
+    attr_reader :owner_token
+
+    def initialize(registry:, owner_token:)
+      @registry = registry
+      @owner_token = owner_token
+      @mutex = Mutex.new
+      @source = nil
+      @notified = false
+    end
+
+    def watch(source)
+      @mutex.synchronize { @source = source if @registry }
+      source.on_complete(&method(:completed))
+    end
+
+    def completed(value, error)
+      registry, source = claim
+      return unless registry
+
+      deliver(registry, Notification.new(reception: self,
+        status: source.status, value: value, error: error))
+    end
+
+    def cancelled
+      registry, = claim
+      deliver(registry, Cancellation.new(reception: self)) if registry
+    end
+
+    def close
+      @mutex.synchronize do
+        @registry = nil
+        @source = nil
+      end
+      nil
+    end
+
+    def active?
+      @mutex.synchronize { !@registry.nil? }
+    end
+
+    private
+
+    def claim
+      @mutex.synchronize do
+        return [nil, nil] if @notified || !@registry
+
+        @notified = true
+        [@registry, @source]
+      end
+    end
+
+    def deliver(registry, command)
+      return if registry.post(command)
+
+      registry.task_delivery_failed(self,
+        Phronomy::RuntimeShutdownError.new("Runtime rejected Workflow task completion"))
+    rescue => error
+      registry.task_delivery_failed(self, error)
+    end
+  end
+end

data/lib/phronomy/workflow/execution/workflow_task_resume_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "../../common/error"
+
+module Phronomy
+  # A live task wait cannot be reconstructed from a Workflow state snapshot.
+  # @api public
+  class WorkflowTaskResumeError < Error
+    # @api public
+    def initialize(message = "Cannot resume a pending Workflow task_state; explicit reconciliation is required", code: "workflow.task_resume_unsupported")
+      super
+    end
+  end
+end