phronomy 0.26.0 → 0.27.0

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

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Workflow-owned segment admission and routing, mutated only on EventLoop.
+  # @api private
+  class WorkflowExecutionRegistry < Phronomy::ExecutionReceiver
+    # Workflow-owned process-local Workflow execution-segment admission. The
+    # owner token is a Runtime coordination capability, not a domain identity or
+    # routing identity. fsm_session_id is bound only after durable load/hydration
+    # completes and a concrete FSMSession has been constructed.
+    WorkflowAdmission = Data.define(
+      :workflow_instance_id, :owner_token, :fsm_session_id, :state
+    )
+    private_constant :WorkflowAdmission
+
+    def initialize(event_loop:)
+      super
+      @workflow_admissions = {}
+    end
+
+    def post(command, admission: false, completion: nil)
+      post_message(command, admission: admission, completion: completion)
+    end
+
+    def deliver(command)
+      assert_event_loop_thread!
+      command.runner.deliver_on_event_loop(command)
+    end
+
+    def idle?
+      !workflow_admission_transition_in_progress_locked?
+    end
+
+    def session_retired(fsm_session_id, reason:)
+      assert_event_loop_thread!
+      mark_workflow_recovery_required_for_session(fsm_session_id) if reason == :recovery_required
+    end
+
+    def shutdown(error:)
+      synchronize { @workflow_admissions.clear }
+    end
+
+    # Reserves one logical Workflow execution segment before durable load or
+    # hydration. The owner token is independent from any later FSMSession id.
+    # @api private
+    def admit_workflow(workflow_instance_id, owner_token:)
+      assert_event_loop_thread!
+      key = workflow_instance_id.to_s
+      raise ArgumentError, "workflow_instance_id must not be empty" if key.empty?
+      raise ArgumentError, "owner_token is required" unless owner_token
+
+      admit do
+        if @workflow_admissions.key?(key)
+          raise Phronomy::Error,
+            "Workflow instance #{key.inspect} already has a live execution segment"
+        end
+        @workflow_admissions[key] = WorkflowAdmission.new(
+          workflow_instance_id: key.freeze,
+          owner_token: owner_token,
+          fsm_session_id: nil,
+          state: :admitting
+        )
+      end
+      true
+    end
+
+    # Binds the concrete routing identity after admission and durable hydration.
+    # @api private
+    def bind_workflow_session(workflow_instance_id, owner_token:, fsm_session_id:)
+      assert_event_loop_thread!
+      key = workflow_instance_id.to_s
+      fsm_key = fsm_session_id.to_s
+      raise ArgumentError, "fsm_session_id must not be empty" if fsm_key.empty?
+
+      synchronize do
+        current = @workflow_admissions.fetch(key) do
+          raise Phronomy::Error, "Workflow instance #{key.inspect} has no Runtime admission"
+        end
+        unless current.owner_token.equal?(owner_token) && current.fsm_session_id.nil?
+          raise Phronomy::Error, "stale Workflow admission bind for #{key.inspect}"
+        end
+        @workflow_admissions[key] = WorkflowAdmission.new(
+          workflow_instance_id: current.workflow_instance_id,
+          owner_token: current.owner_token,
+          fsm_session_id: fsm_key.freeze,
+          state: :executing
+        )
+      end
+      true
+    end
+
+    # @api private
+    def mark_workflow_admission(workflow_instance_id, owner_token:, state:)
+      assert_event_loop_thread!
+      key = workflow_instance_id.to_s
+      next_state = state.to_sym
+      unless %i[executing persisting_terminal recovery_required].include?(next_state)
+        raise ArgumentError, "unsupported Workflow admission state: #{next_state.inspect}"
+      end
+
+      synchronize do
+        current = @workflow_admissions.fetch(key) do
+          raise Phronomy::Error, "Workflow instance #{key.inspect} has no Runtime admission"
+        end
+        unless current.owner_token.equal?(owner_token)
+          raise Phronomy::Error, "stale Workflow admission update for #{key.inspect}"
+        end
+        @workflow_admissions[key] = WorkflowAdmission.new(
+          workflow_instance_id: current.workflow_instance_id,
+          owner_token: current.owner_token,
+          fsm_session_id: current.fsm_session_id,
+          state: next_state
+        )
+      end
+      true
+    end
+
+    # Owner-aware release. A competing or stale attempt cannot release the
+    # current Workflow execution segment.
+    # @api private
+    def release_workflow(workflow_instance_id, owner_token:)
+      assert_event_loop_thread!
+      key = workflow_instance_id.to_s
+      synchronize do
+        current = @workflow_admissions[key]
+        next false unless current&.owner_token&.equal?(owner_token)
+
+        @workflow_admissions.delete(key)
+        true
+      end
+    end
+
+    # Read-only diagnostics used by internal tests and routing assertions.
+    def workflow_admission_owner(workflow_instance_id)
+      synchronize do
+        @workflow_admissions[workflow_instance_id.to_s]&.owner_token
+      end
+    end
+
+    def workflow_admission_fsm_session_id(workflow_instance_id)
+      synchronize do
+        @workflow_admissions[workflow_instance_id.to_s]&.fsm_session_id
+      end
+    end
+
+    def workflow_admission_state(workflow_instance_id)
+      synchronize do
+        @workflow_admissions[workflow_instance_id.to_s]&.state
+      end
+    end
+
+    def post_to_workflow(workflow_instance_id:, event:, payload: nil)
+      @event_loop.__route_execution_event(self) do
+        admission = @workflow_admissions[workflow_instance_id.to_s]
+        next unless admission&.state == :executing && admission.fsm_session_id
+
+        Phronomy::Event.new(
+          type: event.to_sym, target_id: admission.fsm_session_id, payload: payload
+        )
+      end
+    end
+
+    private
+
+    def mark_workflow_recovery_required_for_session(fsm_session_id)
+      synchronize do
+        key, admission = @workflow_admissions.find do |_workflow_instance_id, candidate|
+          candidate.fsm_session_id == fsm_session_id.to_s
+        end
+        return false unless admission
+
+        @workflow_admissions[key] = WorkflowAdmission.new(
+          workflow_instance_id: admission.workflow_instance_id,
+          owner_token: admission.owner_token,
+          fsm_session_id: nil,
+          state: :recovery_required
+        )
+      end
+      true
+    end
+
+    def workflow_admission_transition_in_progress_locked?
+      @workflow_admissions.values.any? do |admission|
+        %i[admitting executing persisting_terminal].include?(admission.state)
+      end
+    end
+  end
+end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../engine/concurrency/worker_input_restricted"
+
 require "securerandom"
 
 module Phronomy
@@ -16,9 +18,9 @@ module Phronomy
   # 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,
@@ -138,7 +140,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 +153,10 @@ module Phronomy
           "Valid events: #{@external_events.keys.inspect}"
       end
 
-      Phronomy::Runtime.instance.event_loop.post_to_workflow(
+      registry = Phronomy::WorkflowExecutionRegistry.existing_for(Phronomy::Runtime.instance)
+      return false unless registry
+
+      registry.post_to_workflow(
         workflow_instance_id: workflow_instance_id,
         event: event_name,
         payload: payload
@@ -277,7 +282,7 @@ module Phronomy
       runtime = Phronomy::Runtime.instance
       event_loop = runtime.event_loop
       admitted = false
-      event_loop.admit_workflow(
+      Phronomy::WorkflowExecutionRegistry.for(event_loop).admit_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -318,7 +323,7 @@ module Phronomy
       )
     rescue => error
       if admitted
-        event_loop.release_workflow(
+        Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
           request.workflow_instance_id,
           owner_token: request.owner_token
         )
@@ -330,7 +335,7 @@ module Phronomy
       runtime = Phronomy::Runtime.instance
       event_loop = runtime.event_loop
       admitted = false
-      event_loop.admit_workflow(
+      Phronomy::WorkflowExecutionRegistry.for(event_loop).admit_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -366,7 +371,7 @@ module Phronomy
       )
     rescue => error
       if admitted
-        event_loop.release_workflow(
+        Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
           request.workflow_instance_id,
           owner_token: request.owner_token
         )
@@ -503,7 +508,7 @@ module Phronomy
       local_snapshot = normalize_snapshot(snapshot_for(state))
       return durable_revision if normalized_durable == local_snapshot
 
-      raise Phronomy::Persistence::ConflictError,
+      raise Phronomy::Storage::ConflictError,
         "Workflow state changed since the supplied halted context for " \
         "workflow_instance_id #{state.workflow_instance_id.inspect}; explicit reload/reconciliation is required"
     end
@@ -576,7 +581,7 @@ module Phronomy
         resume_phase: resume_phase,
         stable_observer: stable_observer
       )
-      event_loop.bind_workflow_session(
+      Phronomy::WorkflowExecutionRegistry.for(event_loop).bind_workflow_session(
         execution.workflow_instance_id,
         owner_token: execution.owner_token,
         fsm_session_id: session.id
@@ -591,11 +596,12 @@ module Phronomy
           error: error
         )
       end
-      event_loop.register(session, completion: source_task)
+      event_loop.register(session, completion: source_task,
+        receiver: Phronomy::WorkflowExecutionRegistry.for(event_loop))
       result_task
     rescue => error
       if event_loop&.current?
-        event_loop&.release_workflow(
+        Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
           execution.workflow_instance_id,
           owner_token: execution.owner_token
         )
@@ -608,7 +614,7 @@ module Phronomy
     def finalize_execution(execution:, result_task:, result:, error:)
       event_loop = Phronomy::Runtime.instance.event_loop
       assert_event_loop!(event_loop)
-      event_loop.release_workflow(
+      Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
         execution.workflow_instance_id,
         owner_token: execution.owner_token
       )
@@ -624,73 +630,117 @@ module Phronomy
       runtime = Phronomy::Runtime.instance
       event_loop = runtime.event_loop
       assert_event_loop!(event_loop)
-      event_loop.mark_workflow_admission(
+      Phronomy::WorkflowExecutionRegistry.for(event_loop).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
+        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::Storage::ConflictError,
+      Phronomy::Storage::NotFoundError,
+      Phronomy::Storage::SerializationError,
+      Phronomy::Storage::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
         )
-        WorkflowTerminalPersistenceResult.new(
+      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
+
+    def reconcile_workflow_terminal_f1(operation, original_error)
+      record = operation.repository.load(operation.workflow_instance_id)
+      case Phronomy::Recovery.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)
+        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
         )
-      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(
+      else
+        conflict = Phronomy::Storage::ConflictError.new(
+          "Workflow terminal Persistence outcome conflicts with both expected " \
+          "pre-state and intended post-state for #{operation.workflow_instance_id.inspect}"
+        )
+        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(
+      Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -711,17 +761,6 @@ module Phronomy
       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(
         context: execution.context,
         context_metadata: {
@@ -739,7 +778,22 @@ module Phronomy
         resume_event: resume_event,
         resume_phase: resume_phase,
         stable_observer: stable_observer,
-        terminal_barrier: terminal_barrier
+        terminal_policy: build_terminal_policy(execution)
+      )
+    end
+
+    def build_terminal_policy(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
+          )
+        }
       )
     end
 
@@ -766,13 +820,10 @@ module Phronomy
     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}
-        )
-      )
+      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,
+        admission: admission, completion: completion)
     end
 
     def runtime_rejected_error(action)

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Interprets durable Workflow results for the shared FSM terminal gate.
+  # The session owns pending state; Runner owns persistence and reconciliation.
+  # @api private
+  class WorkflowTerminalPolicy
+    include Phronomy::Concurrency::WorkerInputRestricted
+
+    def initialize(persist:)
+      @persist = persist
+    end
+
+    def start(terminal_type:, context:, event_sink:)
+      @persist.call(terminal_type: terminal_type, context: context, event_sink: event_sink)
+    end
+
+    def handles?(event)
+      event.type == :workflow_terminal_persistence_result
+    end
+
+    def decision_for(event)
+      result = event.payload
+      case result.outcome
+      when :success
+        FSMProtocol::TerminalDecision.new(action: :complete, error: nil)
+      when :known_failure
+        FSMProtocol::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)
+      else
+        raise Phronomy::Error,
+          "unknown Workflow terminal persistence outcome: #{result.outcome.inspect}"
+      end
+    end
+  end
+end