phronomy 0.26.0 → 0.28.0

data/lib/phronomy/{workflow_runner.rb → workflow/execution/workflow_runner.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../execution/concurrency/worker_input_restricted"
+
 require "securerandom"
 
 module Phronomy
@@ -12,13 +14,13 @@ module Phronomy
   # - Runtime admission uses a separate opaque owner token.
   #
   # Workflow persistence is synchronous at the repository contract but is always
-  # invoked through Runtime's OffloadPool. Durable terminal save results return
+  # invoked through its owning execution environment. Durable terminal save results return
   # to the same FSMSession before that session becomes halted/completed.
   # @api private
   class WorkflowRunner
-    include Phronomy::Runnable
+    include Phronomy::Concurrency::WorkerInputRestricted
 
-    FINISH = :__end__
+    include Phronomy::Runnable
 
     Execution = Data.define(
       :context,
@@ -89,7 +91,8 @@ module Phronomy
       @entry_point = entry_point
       @wait_state_names = wait_state_names
       @persistence = persistence
-      @phase_machine_class = Workflow::PhaseMachineBuilder.new(
+      @environment = WorkflowExecutionEnvironment.current
+      @phase_machine_class = @environment.compile_transitions(
         entry_point: @entry_point,
         declared_states: @declared_states,
         wait_state_names: @wait_state_names,
@@ -97,7 +100,7 @@ module Phronomy
         entry_actions: @entry_actions,
         auto_transitions: auto_transitions,
         exit_actions: exit_actions
-      ).build
+      )
     end
 
     def invoke(input, config: {})
@@ -138,7 +141,7 @@ module Phronomy
     end
 
     # Posts an application-defined event to the currently live Workflow owner.
-    # EventLoop resolves workflow_instance_id to the current concrete
+    # WorkflowExecutionRegistry resolves workflow_instance_id to the current concrete
     # fsm_session_id. The opaque admission owner token is deliberately not a
     # routing identity and is not exposed here.
     def signal(workflow_instance_id:, event:, payload: nil)
@@ -151,7 +154,10 @@ module Phronomy
           "Valid events: #{@external_events.keys.inspect}"
       end
 
-      Phronomy::Runtime.instance.event_loop.post_to_workflow(
+      registry = @environment.existing_registry
+      return false unless registry
+
+      registry.post_to_workflow(
         workflow_instance_id: workflow_instance_id,
         event: event_name,
         payload: payload
@@ -163,8 +169,7 @@ module Phronomy
     # progression therefore remain EventLoop-owned.
     # @api private
     def deliver_on_event_loop(command)
-      event_loop = Phronomy::Runtime.instance.event_loop
-      assert_event_loop!(event_loop)
+      assert_execution_owner!
 
       case command
       when StartCommand
@@ -206,7 +211,7 @@ module Phronomy
     end
 
     def ensure_blocking_call_allowed!(method_name, async_alternative)
-      return unless Phronomy::Runtime.instance.event_loop.current?
+      return unless Phronomy::WaitPolicy.blocking_forbidden?
 
       raise Phronomy::Error,
         "Cannot call Workflow##{method_name} from the EventLoop thread. " \
@@ -215,7 +220,6 @@ module Phronomy
 
     def start_new_execution(input, config, stable_observer: nil)
       reject_legacy_workflow_identity_key!(config)
-      runtime = Phronomy::Runtime.instance
       result_task = Phronomy::TaskResult.deferred(name: "workflow:preparing")
       explicit_workflow_instance_id = !config[:workflow_instance_id].nil?
       workflow_instance_id = (config[:workflow_instance_id] || SecureRandom.uuid).to_s.freeze
@@ -237,7 +241,7 @@ module Phronomy
         owner_token: Object.new.freeze,
         explicit_workflow_instance_id: explicit_workflow_instance_id
       )
-      fail_task(result_task, runtime_rejected_error(:start)) unless post_control(runtime, command)
+      fail_task(result_task, runtime_rejected_error(:start)) unless post_control(command)
       result_task
     rescue => error
       fail_task(result_task, error) if defined?(result_task) && result_task
@@ -245,7 +249,6 @@ module Phronomy
     end
 
     def start_resume_execution(state, input:, event_name:, current_phase:)
-      runtime = Phronomy::Runtime.instance
       workflow_instance_id = state.workflow_instance_id.to_s.freeze
       result_task = Phronomy::TaskResult.deferred(name: "workflow-resume:#{workflow_instance_id}")
       Phronomy::Tracing::Automatic.observe_task(
@@ -266,7 +269,7 @@ module Phronomy
         workflow_instance_id: workflow_instance_id,
         owner_token: Object.new.freeze
       )
-      fail_task(result_task, runtime_rejected_error(:resume)) unless post_control(runtime, command)
+      fail_task(result_task, runtime_rejected_error(:resume)) unless post_control(command)
       result_task
     rescue => error
       fail_task(result_task, error) if defined?(result_task) && result_task
@@ -274,10 +277,8 @@ module Phronomy
     end
 
     def begin_start_on_event_loop(request)
-      runtime = Phronomy::Runtime.instance
-      event_loop = runtime.event_loop
       admitted = false
-      event_loop.admit_workflow(
+      @environment.registry.admit_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -285,7 +286,7 @@ module Phronomy
 
       recursion_limit = request.config.fetch(
         :recursion_limit,
-        Phronomy.configuration.recursion_limit
+        Phronomy::WorkflowSettings.current.recursion_limit
       )
       repository = configured_repository
       persist = request.explicit_workflow_instance_id && !repository.nil?
@@ -310,7 +311,6 @@ module Phronomy
       end
 
       submit_workflow_load(
-        runtime,
         repository,
         request.workflow_instance_id,
         StartLoadReady,
@@ -318,7 +318,7 @@ module Phronomy
       )
     rescue => error
       if admitted
-        event_loop.release_workflow(
+        @environment.registry.release_workflow(
           request.workflow_instance_id,
           owner_token: request.owner_token
         )
@@ -327,10 +327,8 @@ module Phronomy
     end
 
     def begin_resume_on_event_loop(request)
-      runtime = Phronomy::Runtime.instance
-      event_loop = runtime.event_loop
       admitted = false
-      event_loop.admit_workflow(
+      @environment.registry.admit_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -343,7 +341,7 @@ module Phronomy
           context: context,
           workflow_instance_id: request.workflow_instance_id,
           owner_token: request.owner_token,
-          recursion_limit: Phronomy.configuration.recursion_limit,
+          recursion_limit: Phronomy::WorkflowSettings.current.recursion_limit,
           repository: nil,
           persist: false,
           expected_revision: nil
@@ -358,7 +356,6 @@ module Phronomy
       end
 
       submit_workflow_load(
-        runtime,
         repository,
         request.workflow_instance_id,
         ResumeLoadReady,
@@ -366,7 +363,7 @@ module Phronomy
       )
     rescue => error
       if admitted
-        event_loop.release_workflow(
+        @environment.registry.release_workflow(
           request.workflow_instance_id,
           owner_token: request.owner_token
         )
@@ -374,12 +371,12 @@ module Phronomy
       fail_task(request.result_task, error)
     end
 
-    def submit_workflow_load(runtime, repository, workflow_instance_id, ready_class, request)
+    def submit_workflow_load(repository, workflow_instance_id, ready_class, request)
       operation = WorkflowLoadCommand.new(
         repository: repository,
         workflow_instance_id: workflow_instance_id.to_s.freeze
       )
-      task = runtime.offload.submit(on_full: :raise) do
+      task = @environment.submit(on_full: :raise) do
         record = operation.repository.load(operation.workflow_instance_id)
         WorkflowLoadResult.new(
           repository: operation.repository,
@@ -395,7 +392,7 @@ module Phronomy
           error: error
         )
         fail_task(request.result_task, runtime_rejected_error(:load_result)) unless
-          post_control(runtime, ready)
+          post_control(ready)
       end
       nil
     end
@@ -409,7 +406,7 @@ module Phronomy
 
       recursion_limit = request.config.fetch(
         :recursion_limit,
-        Phronomy.configuration.recursion_limit
+        Phronomy::WorkflowSettings.current.recursion_limit
       )
       execution = build_new_execution(
         request.input,
@@ -447,7 +444,7 @@ module Phronomy
         context: context,
         workflow_instance_id: request.workflow_instance_id,
         owner_token: request.owner_token,
-        recursion_limit: Phronomy.configuration.recursion_limit,
+        recursion_limit: Phronomy::WorkflowSettings.current.recursion_limit,
         repository: ready.result.repository,
         persist: true,
         expected_revision: expected_revision
@@ -503,7 +500,7 @@ module Phronomy
       local_snapshot = normalize_snapshot(snapshot_for(state))
       return durable_revision if normalized_durable == local_snapshot
 
-      raise Phronomy::Persistence::ConflictError,
+      raise Phronomy::Persistence::StateConflictError,
         "Workflow state changed since the supplied halted context for " \
         "workflow_instance_id #{state.workflow_instance_id.inspect}; explicit reload/reconciliation is required"
     end
@@ -555,8 +552,7 @@ module Phronomy
     end
 
     def configured_repository
-      persistence = @persistence || Phronomy.configuration.persistence
-      persistence&.workflow_states
+      @persistence || Phronomy::WorkflowSettings.current.workflow_store
     end
 
     def register_execution(
@@ -566,17 +562,14 @@ module Phronomy
       resume_phase: nil,
       stable_observer: nil
     )
-      runtime = Phronomy::Runtime.instance
-      event_loop = runtime.event_loop
-      assert_event_loop!(event_loop)
+      assert_execution_owner!
       session = build_session_for(
         execution: execution,
-        runtime: runtime,
         resume_event: resume_event,
         resume_phase: resume_phase,
         stable_observer: stable_observer
       )
-      event_loop.bind_workflow_session(
+      @environment.registry.bind_workflow_session(
         execution.workflow_instance_id,
         owner_token: execution.owner_token,
         fsm_session_id: session.id
@@ -591,11 +584,11 @@ module Phronomy
           error: error
         )
       end
-      event_loop.register(session, completion: source_task)
+      @environment.register_session(session, completion: source_task)
       result_task
     rescue => error
-      if event_loop&.current?
-        event_loop&.release_workflow(
+      if @environment.executing?
+        @environment.registry.release_workflow(
           execution.workflow_instance_id,
           owner_token: execution.owner_token
         )
@@ -606,9 +599,8 @@ 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:)
-      event_loop = Phronomy::Runtime.instance.event_loop
-      assert_event_loop!(event_loop)
-      event_loop.release_workflow(
+      assert_execution_owner!
+      @environment.registry.release_workflow(
         execution.workflow_instance_id,
         owner_token: execution.owner_token
       )
@@ -621,76 +613,117 @@ module Phronomy
       context:,
       event_sink:
     )
-      runtime = Phronomy::Runtime.instance
-      event_loop = runtime.event_loop
-      assert_event_loop!(event_loop)
-      event_loop.mark_workflow_admission(
+      assert_execution_owner!
+      @environment.registry.mark_workflow_admission(
         execution.workflow_instance_id,
         owner_token: execution.owner_token,
         state: :persisting_terminal
       )
 
-      operation = WorkflowTerminalPersistenceCommand.new(
+      operation = Phronomy::WorkflowRunner::WorkflowTerminalPersistenceCommand.new(
         repository: execution.repository,
         workflow_instance_id: execution.workflow_instance_id.to_s.freeze,
         expected_revision: execution.expected_revision,
         snapshot: deep_immutable_copy(snapshot_for(context))
       )
-      task = runtime.offload.submit(on_full: :raise) do
-        revision = operation.repository.save(
-          operation.workflow_instance_id,
-          expected_revision: operation.expected_revision,
-          snapshot: operation.snapshot
+
+      task = @environment.submit(on_full: :raise) do
+        persist_terminal_snapshot(operation)
+      end
+      task.on_complete do |result, operation_error|
+        deliver_terminal_persistence_result(execution, event_sink, result, operation_error)
+      end
+      terminal_type
+    end
+
+    def persist_terminal_snapshot(operation)
+      revision = operation.repository.save(
+        operation.workflow_instance_id,
+        expected_revision: operation.expected_revision,
+        snapshot: operation.snapshot
+      )
+      Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+        outcome: :success,
+        revision: revision,
+        error: nil
+      )
+    rescue Phronomy::Persistence::ConflictError,
+      Phronomy::Persistence::NotFoundError,
+      Phronomy::Persistence::SerializationError,
+      Phronomy::Persistence::UnsupportedBackendError => error
+      Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+        outcome: :known_failure,
+        revision: nil,
+        error: error
+      )
+    rescue => error
+      reconcile_workflow_terminal_f1(operation, error)
+    end
+
+    def deliver_terminal_persistence_result(execution, event_sink, result, operation_error)
+      delivery = if operation_error
+        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+          outcome: :outcome_unknown,
+          revision: nil,
+          error: operation_error
+        )
+      else
+        result
+      end
+      accepted = event_sink.post(:workflow_terminal_persistence_result, delivery)
+      unless accepted
+        Phronomy::RuntimeSettings.current.logger&.warn(
+          "[Phronomy] EventLoop rejected Workflow terminal persistence result " \
+          "for #{execution.workflow_instance_id.inspect}"
         )
-        WorkflowTerminalPersistenceResult.new(
+      end
+    end
+
+    def reconcile_workflow_terminal_f1(operation, original_error)
+      record = operation.repository.load(operation.workflow_instance_id)
+      case Phronomy::Persistence::SnapshotComparison.compare_revisioned_snapshot(
+        record: record,
+        expected_pre_revision: operation.expected_revision,
+        intended_snapshot: operation.snapshot
+      )
+      when :post_state
+        revision = Phronomy::Persistence::SnapshotComparison.fetch_value(record, :revision)
+        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
           outcome: :success,
           revision: revision,
           error: nil
         )
-      rescue Phronomy::Persistence::ConflictError,
-        Phronomy::Persistence::NotFoundError,
-        Phronomy::Persistence::SerializationError,
-        Phronomy::Persistence::UnsupportedBackendError => error
-        WorkflowTerminalPersistenceResult.new(
+      when :pre_state
+        # The uncertain save is now known not to have committed. Do not blindly
+        # retry it here; surface a known failure through the ordinary terminal
+        # barrier semantics.
+        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
           outcome: :known_failure,
           revision: nil,
-          error: error
+          error: original_error
+        )
+      else
+        conflict = Phronomy::Persistence::StateConflictError.new(
+          "Workflow terminal Persistence outcome conflicts with both expected " \
+          "pre-state and intended post-state for #{operation.workflow_instance_id.inspect}"
         )
-      rescue => error
-        # The Backend SPI does not currently provide a portable commit-outcome
-        # classifier for arbitrary storage/transport failures. If non-commit is
-        # not guaranteed by the Phronomy error contract, fail closed as F1.
-        WorkflowTerminalPersistenceResult.new(
+        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
           outcome: :outcome_unknown,
           revision: nil,
-          error: error
+          error: conflict
         )
       end
-      task.on_complete do |result, operation_error|
-        delivery = if operation_error
-          WorkflowTerminalPersistenceResult.new(
-            outcome: :outcome_unknown,
-            revision: nil,
-            error: operation_error
-          )
-        else
-          result
-        end
-        accepted = event_sink.post(:workflow_terminal_persistence_result, delivery)
-        unless accepted
-          Phronomy.configuration.logger&.warn(
-            "[Phronomy] EventLoop rejected Workflow terminal persistence result " \
-            "for #{execution.workflow_instance_id.inspect}"
-          )
-        end
-      end
-      terminal_type
+    rescue => reconciliation_error
+      Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+        outcome: :outcome_unknown,
+        revision: nil,
+        error: reconciliation_error
+      )
     end
 
     def release_and_fail(request, error)
-      event_loop = Phronomy::Runtime.instance.event_loop
-      assert_event_loop!(event_loop)
-      event_loop.release_workflow(
+      assert_execution_owner!
+      @environment.registry.release_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -706,23 +739,11 @@ module Phronomy
 
     def build_session_for(
       execution:,
-      runtime:,
       resume_event: nil,
       resume_phase: nil,
       stable_observer: nil
     )
-      terminal_barrier = if execution.repository && execution.persist
-        ->(terminal_type:, context:, event_sink:) {
-          begin_terminal_persistence_on_event_loop(
-            execution,
-            terminal_type: terminal_type,
-            context: context,
-            event_sink: event_sink
-          )
-        }
-      end
-
-      Phronomy::FSMSession.new(
+      @environment.build_session(
         context: execution.context,
         context_metadata: {
           workflow_instance_id: execution.workflow_instance_id
@@ -735,14 +756,26 @@ module Phronomy
         external_events: @external_events,
         phase_machine_class: @phase_machine_class,
         recursion_limit: execution.recursion_limit,
-        event_loop: runtime.event_loop,
         resume_event: resume_event,
         resume_phase: resume_phase,
         stable_observer: stable_observer,
-        terminal_barrier: terminal_barrier
+        persist: terminal_persistence_callback(execution)
       )
     end
 
+    def terminal_persistence_callback(execution)
+      return unless execution.repository && execution.persist
+
+      ->(terminal_type:, context:, event_sink:) {
+        begin_terminal_persistence_on_event_loop(
+          execution,
+          terminal_type: terminal_type,
+          context: context,
+          event_sink: event_sink
+        )
+      }
+    end
+
     def resolve_resume_event(current_phase, event)
       event_name = event.to_sym
       unless event_name == :resume
@@ -765,14 +798,11 @@ module Phronomy
         "No external event registered for state #{current_phase.inspect}"
     end
 
-    def post_control(runtime, command)
-      runtime.event_loop.post(
-        Phronomy::Event.new(
-          type: :workflow_control,
-          target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
-          payload: {command: command}
-        )
-      )
+    def post_control(command)
+      admission = command.is_a?(StartCommand) || command.is_a?(ResumeCommand)
+      completion = admission ? command.result_task : command.request.result_task
+      @environment.registry.post(command,
+        admission: admission, completion: completion)
     end
 
     def runtime_rejected_error(action)
@@ -781,8 +811,8 @@ module Phronomy
       )
     end
 
-    def assert_event_loop!(event_loop)
-      return if event_loop.current?
+    def assert_execution_owner!
+      return if @environment.executing?
 
       raise Phronomy::Error,
         "Workflow live-state progression must run on EventLoop"

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Workflow-owned progress limit and optional state repository. Composition
+  # supplies these values; existing execution boundaries decide when to read.
+  # @api private
+  class WorkflowSettings
+    class << self
+      # Bind at boot without reading settings or starting runtime resources.
+      def install_provider(&provider)
+        raise ArgumentError, "settings provider requires a block" unless provider
+        @provider = provider
+        nil
+      end
+
+      # Read only when requested; no cache or change notification is involved.
+      def current
+        @provider.call
+      end
+    end
+
+    attr_accessor :recursion_limit, :workflow_store
+
+    def initialize(recursion_limit:)
+      @recursion_limit = recursion_limit
+    end
+  end
+end