phronomy 0.27.0 → 0.28.0

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../engine/concurrency/worker_input_restricted"
+require_relative "../../execution/concurrency/worker_input_restricted"
 
 require "securerandom"
 
@@ -14,7 +14,7 @@ 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
@@ -91,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,
@@ -99,7 +100,7 @@ module Phronomy
         entry_actions: @entry_actions,
         auto_transitions: auto_transitions,
         exit_actions: exit_actions
-      ).build
+      )
     end
 
     def invoke(input, config: {})
@@ -153,7 +154,7 @@ module Phronomy
           "Valid events: #{@external_events.keys.inspect}"
       end
 
-      registry = Phronomy::WorkflowExecutionRegistry.existing_for(Phronomy::Runtime.instance)
+      registry = @environment.existing_registry
       return false unless registry
 
       registry.post_to_workflow(
@@ -168,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
@@ -211,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. " \
@@ -220,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
@@ -242,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
@@ -250,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(
@@ -271,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
@@ -279,10 +277,8 @@ module Phronomy
     end
 
     def begin_start_on_event_loop(request)
-      runtime = Phronomy::Runtime.instance
-      event_loop = runtime.event_loop
       admitted = false
-      Phronomy::WorkflowExecutionRegistry.for(event_loop).admit_workflow(
+      @environment.registry.admit_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -290,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?
@@ -315,7 +311,6 @@ module Phronomy
       end
 
       submit_workflow_load(
-        runtime,
         repository,
         request.workflow_instance_id,
         StartLoadReady,
@@ -323,7 +318,7 @@ module Phronomy
       )
     rescue => error
       if admitted
-        Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
+        @environment.registry.release_workflow(
           request.workflow_instance_id,
           owner_token: request.owner_token
         )
@@ -332,10 +327,8 @@ module Phronomy
     end
 
     def begin_resume_on_event_loop(request)
-      runtime = Phronomy::Runtime.instance
-      event_loop = runtime.event_loop
       admitted = false
-      Phronomy::WorkflowExecutionRegistry.for(event_loop).admit_workflow(
+      @environment.registry.admit_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -348,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
@@ -363,7 +356,6 @@ module Phronomy
       end
 
       submit_workflow_load(
-        runtime,
         repository,
         request.workflow_instance_id,
         ResumeLoadReady,
@@ -371,7 +363,7 @@ module Phronomy
       )
     rescue => error
       if admitted
-        Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
+        @environment.registry.release_workflow(
           request.workflow_instance_id,
           owner_token: request.owner_token
         )
@@ -379,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,
@@ -400,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
@@ -414,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,
@@ -452,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
@@ -508,7 +500,7 @@ module Phronomy
       local_snapshot = normalize_snapshot(snapshot_for(state))
       return durable_revision if normalized_durable == local_snapshot
 
-      raise Phronomy::Storage::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
@@ -560,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(
@@ -571,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
       )
-      Phronomy::WorkflowExecutionRegistry.for(event_loop).bind_workflow_session(
+      @environment.registry.bind_workflow_session(
         execution.workflow_instance_id,
         owner_token: execution.owner_token,
         fsm_session_id: session.id
@@ -596,12 +584,11 @@ module Phronomy
           error: error
         )
       end
-      event_loop.register(session, completion: source_task,
-        receiver: Phronomy::WorkflowExecutionRegistry.for(event_loop))
+      @environment.register_session(session, completion: source_task)
       result_task
     rescue => error
-      if event_loop&.current?
-        Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
+      if @environment.executing?
+        @environment.registry.release_workflow(
           execution.workflow_instance_id,
           owner_token: execution.owner_token
         )
@@ -612,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)
-      Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
+      assert_execution_owner!
+      @environment.registry.release_workflow(
         execution.workflow_instance_id,
         owner_token: execution.owner_token
       )
@@ -627,10 +613,8 @@ module Phronomy
       context:,
       event_sink:
     )
-      runtime = Phronomy::Runtime.instance
-      event_loop = runtime.event_loop
-      assert_event_loop!(event_loop)
-      Phronomy::WorkflowExecutionRegistry.for(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
@@ -643,7 +627,7 @@ module Phronomy
         snapshot: deep_immutable_copy(snapshot_for(context))
       )
 
-      task = runtime.offload.submit(on_full: :raise) do
+      task = @environment.submit(on_full: :raise) do
         persist_terminal_snapshot(operation)
       end
       task.on_complete do |result, operation_error|
@@ -663,10 +647,10 @@ module Phronomy
         revision: revision,
         error: nil
       )
-    rescue Phronomy::Storage::ConflictError,
-      Phronomy::Storage::NotFoundError,
-      Phronomy::Storage::SerializationError,
-      Phronomy::Storage::UnsupportedBackendError => error
+    rescue Phronomy::Persistence::ConflictError,
+      Phronomy::Persistence::NotFoundError,
+      Phronomy::Persistence::SerializationError,
+      Phronomy::Persistence::UnsupportedBackendError => error
       Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
         outcome: :known_failure,
         revision: nil,
@@ -688,7 +672,7 @@ module Phronomy
       end
       accepted = event_sink.post(:workflow_terminal_persistence_result, delivery)
       unless accepted
-        Phronomy.configuration.logger&.warn(
+        Phronomy::RuntimeSettings.current.logger&.warn(
           "[Phronomy] EventLoop rejected Workflow terminal persistence result " \
           "for #{execution.workflow_instance_id.inspect}"
         )
@@ -697,13 +681,13 @@ module Phronomy
 
     def reconcile_workflow_terminal_f1(operation, original_error)
       record = operation.repository.load(operation.workflow_instance_id)
-      case Phronomy::Recovery.compare_revisioned_snapshot(
+      case Phronomy::Persistence::SnapshotComparison.compare_revisioned_snapshot(
         record: record,
         expected_pre_revision: operation.expected_revision,
         intended_snapshot: operation.snapshot
       )
       when :post_state
-        revision = Phronomy::Recovery.fetch_value(record, :revision)
+        revision = Phronomy::Persistence::SnapshotComparison.fetch_value(record, :revision)
         Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
           outcome: :success,
           revision: revision,
@@ -719,7 +703,7 @@ module Phronomy
           error: original_error
         )
       else
-        conflict = Phronomy::Storage::ConflictError.new(
+        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}"
         )
@@ -738,9 +722,8 @@ module Phronomy
     end
 
     def release_and_fail(request, error)
-      event_loop = Phronomy::Runtime.instance.event_loop
-      assert_event_loop!(event_loop)
-      Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
+      assert_execution_owner!
+      @environment.registry.release_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -756,12 +739,11 @@ module Phronomy
 
     def build_session_for(
       execution:,
-      runtime:,
       resume_event: nil,
       resume_phase: nil,
       stable_observer: nil
     )
-      Phronomy::FSMSession.new(
+      @environment.build_session(
         context: execution.context,
         context_metadata: {
           workflow_instance_id: execution.workflow_instance_id
@@ -774,27 +756,24 @@ 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_policy: build_terminal_policy(execution)
+        persist: terminal_persistence_callback(execution)
       )
     end
 
-    def build_terminal_policy(execution)
+    def terminal_persistence_callback(execution)
       return unless execution.repository && execution.persist
 
-      Phronomy::WorkflowTerminalPolicy.new(
-        persist: ->(terminal_type:, context:, event_sink:) {
-          begin_terminal_persistence_on_event_loop(
-            execution,
-            terminal_type: terminal_type,
-            context: context,
-            event_sink: event_sink
-          )
-        }
-      )
+      ->(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)
@@ -819,10 +798,10 @@ module Phronomy
         "No external event registered for state #{current_phase.inspect}"
     end
 
-    def post_control(runtime, command)
+    def post_control(command)
       admission = command.is_a?(StartCommand) || command.is_a?(ResumeCommand)
       completion = admission ? command.result_task : command.request.result_task
-      Phronomy::WorkflowExecutionRegistry.for(runtime.event_loop).post(command,
+      @environment.registry.post(command,
         admission: admission, completion: completion)
     end
 
@@ -832,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

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,38 @@
+# 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 = WorkflowExecutionRegistry.for(@runtime.event_loop)
+    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, **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
+      Phronomy::FSMSession.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
+  end
+end