phronomy 0.27.0 → 0.29.0

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

data/lib/phronomy/workflow/persistence/state_repository.rb

@@ -9,37 +9,43 @@ module Phronomy
         def initialize(view) = @view = view
 
         def load(workflow_instance_id)
-          @view.atomic do |bound|
-            entry = bound.records(Phronomy::WorkflowStorageSchema::STATES).read(workflow_instance_id.to_s)
-            entry && decode(entry, workflow_instance_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.atomic do |bound|
+              entry = bound.records(Phronomy::Workflow::Persistence::StorageSchema::STATES).read(workflow_instance_id.to_s)
+              entry && decode(entry, workflow_instance_id)
+            end
           end
         end
 
         def save(workflow_instance_id, expected_revision:, snapshot:)
-          expected = expected_revision.nil? ? nil : Integer(expected_revision)
-          revision = expected.nil? ? 1 : expected + 1
-          record = Codec.encode_workflow_state(workflow_instance_id: workflow_instance_id,
-            workflow_revision: revision, snapshot: snapshot)
-          @view.atomic do |bound|
-            records = bound.records(Phronomy::WorkflowStorageSchema::STATES)
-            values = {key: workflow_instance_id.to_s, attributes: {}, record: record}
-            entry = if expected.nil?
-              records.insert(**values, revision: revision)
-            else
-              records.replace(**values, expected_revision: expected, next_revision: revision)
-            end
-            decoded = decode(entry, workflow_instance_id)
-            unless decoded.fetch(:revision) == revision
-              raise Phronomy::Storage::SerializationError, "backend returned another Workflow revision"
+          Phronomy::Persistence::StorageBoundary.call do
+            expected = expected_revision.nil? ? nil : Integer(expected_revision)
+            revision = expected.nil? ? 1 : expected + 1
+            record = Codec.encode_workflow_state(workflow_instance_id: workflow_instance_id,
+              workflow_revision: revision, snapshot: snapshot)
+            @view.atomic do |bound|
+              records = bound.records(Phronomy::Workflow::Persistence::StorageSchema::STATES)
+              values = {key: workflow_instance_id.to_s, attributes: {}, record: record}
+              entry = if expected.nil?
+                records.insert(**values, revision: revision)
+              else
+                records.replace(**values, expected_revision: expected, next_revision: revision)
+              end
+              decoded = decode(entry, workflow_instance_id)
+              unless decoded.fetch(:revision) == revision
+                raise Phronomy::Storage::SerializationError, "backend returned another Workflow revision"
+              end
+              revision
             end
-            revision
+          rescue Phronomy::Storage::NotFoundError => error
+            raise Phronomy::Storage::ConflictError, error.message
           end
-        rescue Phronomy::Storage::NotFoundError => error
-          raise Phronomy::Storage::ConflictError, error.message
         end
 
         def delete(workflow_instance_id, expected_revision:)
-          @view.records(Phronomy::WorkflowStorageSchema::STATES).delete(key: workflow_instance_id.to_s, expected_revision: Integer(expected_revision))
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.records(Phronomy::Workflow::Persistence::StorageSchema::STATES).delete(key: workflow_instance_id.to_s, expected_revision: Integer(expected_revision))
+          end
         end
 
         private

data/lib/phronomy/workflow/persistence/storage_schema.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Domain-owned Workflow metadata, loadable without the Workflow runtime.
+  # @api private
+  class Workflow
+    module Persistence
+      module StorageSchema
+        STATES = Phronomy::Storage::Resource.new(id: "workflow.states", kind: :records)
+      end
+    end
+  end
+end

data/lib/phronomy/workflow/runtime_binding/workflow_engine_environment.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Connects one compiled Workflow to its owning Runtime. Construction and
+  # transition compilation do not start workers or register execution state.
+  # @api private
+  class WorkflowEngineEnvironment < WorkflowExecutionEnvironment
+    def initialize(runtime: Phronomy::Runtime.instance)
+      @runtime = runtime
+    end
+
+    def registry
+      receiver = WorkflowExecutionRegistry.for(@runtime.event_loop)
+      @runtime.__shutdown_participant(key: WorkflowExecutionRegistry) ||
+        @runtime.__register_shutdown_participant(key: WorkflowExecutionRegistry, participant: receiver)
+      receiver
+    end
+
+    def existing_registry = WorkflowExecutionRegistry.existing_for(@runtime)
+    def executing? = @runtime.event_loop.current?
+
+    def submit(**options, &operation)
+      Phronomy::Execution.submit(runtime: @runtime, **options, &operation)
+    end
+
+    def compile_transitions(**definition)
+      WorkflowPhaseMachineBuilder.new(**definition).build
+    end
+
+    def build_session(entry_actions:, persist: nil, task_execution: nil, **options)
+      # Preserve nil/scalar results: initial entry must not re-adopt metadata
+      # unless the application actually returns a context.
+      initial_actions = entry_actions.to_h do |state_name, callbacks|
+        [state_name, callbacks.map { |callback| ->(context) { WorkflowActionRules.entry(callback, context, state_name) } }]
+      end
+      klass = task_execution ? Phronomy::WorkflowTaskSession : Phronomy::FSMSession
+      options = options.merge(task_execution: task_execution) if task_execution
+      klass.new(**options, entry_actions: initial_actions, event_loop: @runtime.event_loop,
+        terminal_policy: persist && WorkflowTerminalPolicy.new(persist: persist))
+    end
+
+    def register_session(session, completion:)
+      @runtime.event_loop.register(session, completion: completion, receiver: registry)
+    end
+
+    def subscribe_cancellation(token, &callback)
+      subscriptions = Phronomy::Concurrency::ResultSubscriptions.new
+      subscriptions.cancellation(token, &callback)
+      remaining = token.remaining_monotonic_seconds
+      if remaining && !token.cancelled?
+        timer = @runtime.timer_queue
+        timer.schedule(seconds: remaining, &callback)
+        subscriptions.add { timer.cancel(callback) }
+      end
+      subscriptions
+    rescue
+      subscriptions&.close
+      raise
+    end
+  end
+end

data/lib/phronomy/workflow/runtime_binding/workflow_phase_machine_builder.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "state_machines"
+require_relative "../execution/workflow_action_rules"
+
+module Phronomy
+  # Builds the anonymous state-machine Class used by WorkflowRunner.
+  #
+  # This class compiles Workflow topology into state_machines declarations.
+  # It intentionally does not await Tasks, register completion callbacks,
+  # cancel external work, or interpret application event payloads.
+  #
+  # @api private
+  class WorkflowPhaseMachineBuilder
+    def initialize(
+      entry_point:,
+      declared_states:,
+      wait_state_names:,
+      external_events:,
+      entry_actions:,
+      auto_transitions:,
+      exit_actions:
+    )
+      @entry_point = entry_point
+      @declared_states = declared_states
+      @wait_state_names = wait_state_names
+      @external_events = external_events.transform_values { |items| items.map { |transition| convert_transition(transition) } }
+      @entry_actions = entry_actions
+      @auto_transitions = auto_transitions.map { |transition| convert_transition(transition) }
+      @exit_actions = exit_actions
+    end
+
+    def build
+      entry = @entry_point
+      all_states = (@declared_states + @wait_state_names + [FSMProtocol::FINISH]).uniq
+      auto_transitions = @auto_transitions
+      external_events = @external_events
+      entry_actions = @entry_actions
+      exit_actions = @exit_actions
+      condition_builder = method(:build_transition_condition)
+      entry_callback_builder = method(:build_entry_callback)
+      exit_callback_builder = method(:build_exit_callback)
+      transition_callback = build_transition_action_callback
+
+      Class.new do
+        attr_accessor(
+          :context,
+          :current_event,
+          :selected_transition_action,
+          :selected_transition_metadata,
+          :workflow_task_execution
+        )
+
+        state_machine :phase, initial: entry do
+          all_states.each { |state_name| state state_name }
+
+          event :state_completed do
+            auto_transitions.each do |transition_definition|
+              transition(
+                transition_definition[:from] => transition_definition[:to],
+                :if => condition_builder.call(transition_definition)
+              )
+            end
+          end
+
+          external_events.each do |event_name, transitions|
+            event event_name do
+              transitions.each do |transition_definition|
+                transition(
+                  transition_definition[:from] => transition_definition[:to],
+                  :if => condition_builder.call(transition_definition)
+                )
+              end
+            end
+          end
+
+          entry_actions.each do |state_name, callables|
+            callables.each do |callable|
+              after_transition(
+                to: state_name,
+                &entry_callback_builder.call(callable, state_name)
+              )
+            end
+          end
+
+          # Both source exit callbacks and the transition action are
+          # before_transition callbacks. Register exits first to preserve the
+          # required exit -> transition action -> entry ordering.
+          before_transition { |machine| machine.workflow_task_execution&.leave }
+          exit_actions.each do |state_name, callables|
+            callables.each do |callable|
+              before_transition(
+                from: state_name,
+                &exit_callback_builder.call(callable, state_name)
+              )
+            end
+          end
+
+          before_transition(&transition_callback)
+        end
+      end
+    rescue => error
+      raise ArgumentError, "Failed to build phase machine: #{error.message}"
+    end
+
+    private
+
+    def convert_transition(transition)
+      destination = transition[:to]
+      destination = FSMProtocol::FINISH if destination == Workflow::Completion::FINISH
+      transition.merge(to: destination)
+    end
+
+    def build_transition_condition(transition_definition)
+      guard = transition_definition[:guard]
+      action = transition_definition[:action]
+      metadata = {
+        from: transition_definition[:from],
+        event: transition_definition[:event],
+        to: public_destination(transition_definition[:to])
+      }.freeze
+
+      ->(machine) {
+        matched = WorkflowActionRules.allowed?(guard, machine.context, machine.current_event)
+        if matched
+          machine.selected_transition_action = action
+          machine.selected_transition_metadata = metadata
+        end
+        matched
+      }
+    end
+
+    def build_transition_action_callback
+      ->(machine) {
+        machine.context = WorkflowActionRules.transition(
+          machine.selected_transition_action, machine.context, machine.current_event,
+          metadata: machine.selected_transition_metadata || {}
+        )
+      }
+    end
+
+    def build_entry_callback(callable, state_name)
+      ->(machine) {
+        machine.context = WorkflowActionRules.apply_entry(callable, machine.context, state_name)
+      }
+    end
+
+    def build_exit_callback(callable, state_name)
+      ->(machine) { WorkflowActionRules.exit(callable, machine.context, state_name) }
+    end
+
+    def public_destination(destination)
+      return Workflow::Completion::FINISH if destination == FSMProtocol::FINISH
+
+      destination
+    end
+  end
+end

data/lib/phronomy/workflow/runtime_binding/workflow_task_session.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # I07 translates C02 task-state decisions to generic FSM progression. Engine
+  # does not learn TaskResult ownership, cancellation or stale-result policy.
+  # @api private
+  class WorkflowTaskSession < FSMSession
+    def initialize(task_execution:, **options)
+      super(**options)
+      @task_execution = task_execution
+      @task_execution.bind(self)
+    end
+
+    def start
+      @task_execution.activate
+      super unless @done
+    rescue => error
+      finish_with_error(error)
+    end
+
+    def apply_task_context(context)
+      return unless @terminal_lifecycle_state == :running
+
+      @ctx = @context = context
+      apply_context_metadata!
+      @tracker.context = context
+      advance_or_halt
+    rescue => error
+      finish_with_error(error)
+    end
+
+    def fail_task_execution(error)
+      finish_with_error(error) if @terminal_lifecycle_state == :running
+    end
+
+    def handle(event)
+      return if event.type == :state_completed && !@task_execution.permits_completion?(event.payload)
+
+      super
+    end
+
+    private
+
+    def post_session_event(type, payload = nil)
+      payload = @task_execution.completion_key if type == :state_completed
+      super
+    end
+
+    def advance_or_halt
+      if @task_execution.enter(@current_state, @ctx)
+        notify_stable_state!
+      else
+        super
+      end
+    end
+
+    def build_tracker(from_state)
+      super.tap { |tracker| tracker.workflow_task_execution = @task_execution }
+    end
+
+    def request_terminal!(...)
+      @task_execution.close
+      super
+    end
+
+    def finish_with_error(error)
+      @task_execution.close
+      super
+    end
+
+    def retire_without_result!(error)
+      @task_execution.retire(error)
+      super
+    end
+  end
+end

data/lib/phronomy/workflow/{execution → runtime_binding}/workflow_terminal_policy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Interprets durable Workflow results for the shared FSM terminal gate.
+  # Translates classified Workflow outcomes into shared FSM terminal decisions.
   # The session owns pending state; Runner owns persistence and reconciliation.
   # @api private
   class WorkflowTerminalPolicy
@@ -23,14 +23,14 @@ module Phronomy
       result = event.payload
       case result.outcome
       when :success
-        FSMProtocol::TerminalDecision.new(action: :complete, error: nil)
+        Phronomy::TerminalDecision.new(action: :complete, error: nil)
       when :known_failure
-        FSMProtocol::TerminalDecision.new(
+        Phronomy::TerminalDecision.new(
           action: :fail,
           error: result.error || Phronomy::Error.new("Workflow terminal persistence failed")
         )
       when :outcome_unknown
-        FSMProtocol::TerminalDecision.new(action: :retire, error: result.error)
+        Phronomy::TerminalDecision.new(action: :retire, error: result.error)
       else
         raise Phronomy::Error,
           "unknown Workflow terminal persistence outcome: #{result.outcome.inspect}"