phronomy 0.22.0 → 0.23.0

data/lib/phronomy/engine/fsm_session.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Phronomy
   # Event-driven execution wrapper for a single FSM session.
   #
@@ -7,12 +9,76 @@ module Phronomy
   # FSMSession owns FSM execution only; it does not own external Task handles,
   # activity tokens, callback correlation, or domain-specific stale-event policy.
   class FSMSession
+    class IdentityReservation
+      attr_reader :fsm_session_id
+
+      def initialize
+        @fsm_session_id = SecureRandom.uuid.to_s.freeze
+        @claimed = false
+        @mutex = Mutex.new
+      end
+
+      def claim!
+        @mutex.synchronize do
+          raise Phronomy::Error, "FSMSession identity reservation already claimed" if @claimed
+
+          @claimed = true
+          @fsm_session_id
+        end
+      end
+    end
+    private_constant :IdentityReservation
+
+    class EventSink
+      attr_reader :fsm_session_id
+
+      def initialize(event_loop:)
+        @event_loop = event_loop
+        @fsm_session_id = nil
+      end
+
+      def bind!(fsm_session_id)
+        raise Phronomy::Error, "FSMSession EventSink is already bound" if @fsm_session_id
+
+        @fsm_session_id = fsm_session_id.to_s.freeze
+        self
+      end
+
+      def post(type, payload = nil)
+        raise Phronomy::Error, "FSMSession EventSink is not bound" unless @fsm_session_id
+
+        event = Phronomy::Event.new(
+          type: type,
+          target_id: @fsm_session_id,
+          payload: payload
+        )
+        if @event_loop.respond_to?(:post_to_session)
+          @event_loop.post_to_session(event)
+        else
+          @event_loop.post(event)
+        end
+      end
+    end
+
     FINISH = WorkflowRunner::FINISH
 
-    attr_reader :id, :context
+    attr_reader :id, :context, :event_sink
+
+    # Returns the live current Workflow phase. During an active FSM transition
+    # the tracker phase is authoritative; @current_state lags until
+    # fire_and_advance! returns. Terminal persistence lifecycle is deliberately
+    # separate from this logical Workflow phase.
+    def current_state
+      return @tracker.phase.to_sym if @tracker
+      @current_state
+    end
+
+    # @api private
+    def self.reserve_identity
+      IdentityReservation.new
+    end
 
     def initialize(
-      id:,
       context:,
       entry_point:,
       entry_actions:,
@@ -26,10 +92,23 @@ module Phronomy
       resume_event: nil,
       resume_phase: nil,
       stable_observer: nil,
-      graph_thread_id: nil
+      context_metadata: {},
+      event_sink: nil,
+      identity_reservation: nil,
+      terminal_barrier: nil
     )
-      @id = id
-      @graph_thread_id = graph_thread_id || id
+      @id = if identity_reservation
+        unless identity_reservation.is_a?(IdentityReservation)
+          raise ArgumentError,
+            "identity_reservation must come from FSMSession.reserve_identity"
+        end
+        identity_reservation.send(:claim!).to_s.freeze
+      else
+        SecureRandom.uuid.to_s.freeze
+      end
+      @event_sink = event_sink || EventSink.new(event_loop: event_loop)
+      @event_sink.bind!(@id)
+      @context_metadata = context_metadata.dup.freeze
       @ctx = context
       @context = context
       @entry_point = entry_point
@@ -44,6 +123,10 @@ module Phronomy
       @resume_event = resume_event
       @resume_phase = resume_phase
       @stable_observer = stable_observer
+      @terminal_barrier = terminal_barrier
+      @terminal_lifecycle_state = :running
+      @pending_terminal_type = nil
+      @pending_terminal_notify_stable = false
       @step = 0
       @done = false
       @current_state = nil
@@ -77,6 +160,16 @@ module Phronomy
     def handle(event)
       return if @done
 
+      if event.type == :workflow_terminal_persistence_result
+        handle_terminal_persistence_result(event.payload)
+        return
+      end
+
+      # Once terminal persistence begins, ordinary Workflow events no longer
+      # have result authority. Only the persistence completion for this concrete
+      # FSMSession can advance its terminal lifecycle.
+      return unless @terminal_lifecycle_state == :running
+
       context_disposition = apply_context_event(event)
       return if context_disposition == :consume
 
@@ -92,6 +185,8 @@ module Phronomy
 
     private
 
+    attr_reader :terminal_lifecycle_state
+
     def run_initial_entry_actions!
       Array(@entry_actions[@current_state]).each do |callable|
         result = callable.call(@ctx)
@@ -110,6 +205,7 @@ module Phronomy
       if _fsm_context?(result)
         @ctx = result
         @context = result
+        apply_context_metadata!
       end
     end
 
@@ -122,6 +218,7 @@ module Phronomy
       if _fsm_context?(result)
         @ctx = result
         @context = result
+        apply_context_metadata!
         @tracker.context = @ctx
         true
       else
@@ -143,6 +240,7 @@ module Phronomy
 
       @ctx = @tracker.context
       @context = @ctx
+      apply_context_metadata!
       @current_state = @tracker.phase.to_sym
       @step += 1
       advance_or_halt
@@ -165,25 +263,33 @@ module Phronomy
     def advance_or_halt
       return finish! if @current_state == FINISH
 
-      notify_stable_state!
-
+      # A wait state is the logical end of this Workflow execution segment. Its
+      # public stable-state notification is therefore part of terminalization
+      # and, for durable Workflows, must not escape before the durable barrier.
       if @wait_state_names.include?(@current_state)
         halt!
         return
       end
 
       if @auto_state_set.key?(@current_state)
+        notify_stable_state!
         post_session_event(:state_completed)
         return
       end
 
-      return if has_external_event_from?(@current_state)
+      if has_external_event_from?(@current_state)
+        notify_stable_state!
+        return
+      end
 
       unless @declared_states.include?(@current_state)
         raise ArgumentError, "State #{@current_state.inspect} is not defined"
       end
 
-      finish!
+      # A declared state with no outgoing transition is also a logical terminal
+      # boundary. Preserve its stable-state notification, but for durable
+      # Workflows publish it only after the terminal save succeeds.
+      finish!(notify_stable: true)
     end
 
     def notify_stable_state!
@@ -215,35 +321,96 @@ module Phronomy
         "EventLoop rejected #{type.inspect} for FSMSession #{@id}"
     end
 
-    def finish!
-      return if @done
-
-      @done = true
-      @ctx.set_graph_metadata(thread_id: @graph_thread_id, phase: :__end__)
-      post_terminal_event(:finished, @ctx)
+    def finish!(notify_stable: false)
+      request_terminal!(
+        :finished,
+        phase: :__end__,
+        notify_stable: notify_stable
+      )
     end
 
     def halt!
-      return if @done
+      request_terminal!(:halted, phase: @current_state, notify_stable: true)
+    end
+
+    def request_terminal!(terminal_type, phase:, notify_stable:)
+      return if @done || @terminal_lifecycle_state != :running
+
+      apply_context_metadata!(phase: phase)
+      @pending_terminal_type = terminal_type
+      @pending_terminal_notify_stable = notify_stable
+      unless @terminal_barrier
+        complete_terminal!(terminal_type)
+        return
+      end
+
+      @terminal_lifecycle_state = :persisting_terminal
+      @terminal_barrier.call(
+        terminal_type: terminal_type,
+        context: @ctx,
+        event_sink: @event_sink
+      )
+    rescue => error
+      finish_with_error(error)
+    end
+
+    def handle_terminal_persistence_result(result)
+      return unless @terminal_lifecycle_state == :persisting_terminal
 
+      case result.outcome
+      when :success
+        complete_terminal!(@pending_terminal_type)
+      when :known_failure
+        finish_with_error(
+          result.error || Phronomy::Error.new("Workflow terminal persistence failed")
+        )
+      when :outcome_unknown
+        @done = true
+        @terminal_lifecycle_state = :recovery_required
+        post_recovery_required_event(result.error)
+      else
+        raise Phronomy::Error,
+          "unknown Workflow terminal persistence outcome: #{result.outcome.inspect}"
+      end
+    end
+
+    def complete_terminal!(terminal_type)
       @done = true
-      @ctx.set_graph_metadata(thread_id: @graph_thread_id, phase: @current_state)
-      post_terminal_event(:halted, @ctx)
+      @terminal_lifecycle_state =
+        (terminal_type == :halted) ? :halted : :completed
+      notify_stable_state! if @pending_terminal_notify_stable
+      post_terminal_event(terminal_type, @ctx)
     end
 
     def finish_with_error(error)
       return if @done
 
       @done = true
+      @terminal_lifecycle_state = :error
       post_terminal_event(:error, error)
     end
 
+    def post_recovery_required_event(error)
+      accepted = @event_loop.post(
+        Phronomy::Event.new(
+          type: :recovery_required,
+          target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
+          payload: {fsm_session_id: @id, error: error}
+        )
+      )
+      return if accepted
+
+      Phronomy.configuration.logger&.warn(
+        "[Phronomy::FSMSession] EventLoop rejected recovery-required event for #{@id}"
+      )
+    end
+
     def post_terminal_event(type, result)
       accepted = @event_loop.post(
         Phronomy::Event.new(
           type: type,
           target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
-          payload: {session_id: @id, result: result}
+          payload: {fsm_session_id: @id, result: result}
         )
       )
       return if accepted
@@ -254,6 +421,14 @@ module Phronomy
       )
     end
 
+    def apply_context_metadata!(phase: nil)
+      return unless @ctx.respond_to?(:set_graph_metadata)
+
+      metadata = @context_metadata
+      metadata = metadata.merge(phase: phase) unless phase.nil?
+      @ctx.set_graph_metadata(**metadata)
+    end
+
     def fire_event!(tracker, event_name, from_state)
       unless tracker.respond_to?(event_name)
         raise ArgumentError,
@@ -262,8 +437,6 @@ module Phronomy
 
       return true if tracker.public_send(event_name)
 
-      # A declared external event whose guards all reject is a valid no-op.
-      # Applications use this to reject stale or unrelated correlated events.
       return false if has_external_event_from?(from_state, event_name)
 
       raise ArgumentError,

data/lib/phronomy/engine/runtime/agent_ownership_registry.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Process-local authoritative owner registry for mutable Agent instances.
+    #
+    # This is not a cache. While a Runtime is alive, one agent_id maps to at most
+    # one mutable live Agent object. Construction is reserved before durable
+    # create/load so concurrent callers cannot materialize independent objects.
+    class AgentOwnershipRegistry
+      Entry = Data.define(:state, :agent, :token)
+      private_constant :Entry
+
+      def initialize(runtime:)
+        @runtime = runtime
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @entries = {}
+        @state = :running
+      end
+
+      def create(agent_id, expected_class:)
+        key = normalize_agent_id(agent_id)
+        token = reserve_create!(key)
+
+        begin
+          agent = yield(@runtime)
+        rescue Phronomy::AgentAlreadyExistsError,
+          Phronomy::Persistence::ConflictError,
+          Phronomy::Persistence::NotFoundError,
+          Phronomy::Persistence::SerializationError,
+          ArgumentError,
+          Phronomy::ConfigurationError
+          release_construction!(key, token)
+          raise
+        rescue
+          # A generic backend/transport failure can be an indeterminate commit.
+          # Do not make the same identity creatable again until recovery proves
+          # which durable lineage exists.
+          fail_construction_closed!(key, token)
+          raise
+        end
+
+        publish_constructed!(
+          key,
+          token,
+          agent,
+          expected_class,
+          fail_closed: true
+        )
+      end
+
+      def load(agent_id, expected_class:)
+        key = normalize_agent_id(agent_id)
+        token = nil
+
+        loop do
+          existing = @mutex.synchronize do
+            ensure_running!
+            entry = @entries[key]
+            case entry&.state
+            when :live
+              entry.agent
+            when :constructing, :purging
+              @condition.wait(@mutex)
+              :retry
+            when :recovery_required
+              raise ownership_recovery_error(key)
+            when nil
+              token = Object.new.freeze
+              @entries[key] = Entry.new(state: :constructing, agent: nil, token: token)
+              nil
+            # :nocov:
+            else
+              raise Phronomy::Error,
+                "unknown Agent ownership state for #{key.inspect}: #{entry.state.inspect}"
+              # :cover:
+            end
+          end
+
+          next if existing == :retry
+          return validate_expected_class!(existing, expected_class, key) if existing
+          break
+        end
+
+        begin
+          agent = yield(@runtime)
+          publish_constructed!(
+            key,
+            token,
+            agent,
+            expected_class,
+            fail_closed: false
+          )
+        rescue
+          # Hydration is read-only. A failed load does not establish a new
+          # durable Agent lineage, so the reservation can safely be released.
+          release_construction!(key, token)
+          raise
+        end
+      end
+
+      def get(agent_id, expected_class:)
+        key = normalize_agent_id(agent_id)
+        agent = @mutex.synchronize do
+          entry = @entries[key]
+          case entry&.state
+          when :live
+            entry.agent
+          when :recovery_required
+            raise ownership_recovery_error(key)
+          # :nocov:
+          when :purging
+            raise Phronomy::Error, "Agent #{key.inspect} is being purged"
+            # :cover:
+          end
+        end
+        return nil unless agent
+
+        validate_expected_class!(agent, expected_class, key)
+      end
+
+      def owned?(agent)
+        return false unless agent
+
+        key = normalize_agent_id(agent.agent_id)
+        @mutex.synchronize do
+          entry = @entries[key]
+          entry&.state == :live && entry.agent.equal?(agent)
+        end
+      rescue ArgumentError
+        false
+      end
+
+      # Moves an exact live owner into :purging before any durable deletion.
+      # The returned opaque token must be supplied to complete/abort.
+      def begin_purge(agent)
+        key = normalize_agent_id(agent.agent_id)
+        token = Object.new.freeze
+
+        @mutex.synchronize do
+          ensure_running!
+          entry = @entries[key]
+          unless entry&.state == :live && entry.agent.equal?(agent)
+            raise Phronomy::RuntimeShutdownError,
+              "Agent #{key.inspect} is not the live owner in this Runtime"
+          end
+          @entries[key] = Entry.new(state: :purging, agent: agent, token: token)
+        end
+        agent.send(:__mark_purging!, @runtime)
+        token
+      end
+
+      def complete_purge(agent, token)
+        key = normalize_agent_id(agent.agent_id)
+        @mutex.synchronize do
+          entry = @entries[key]
+          validate_purge_entry!(entry, agent, token, key)
+          @entries.delete(key)
+          @condition.broadcast
+        end
+        agent.send(:__mark_purged!, @runtime)
+        true
+      end
+
+      # Use only when the durable purge is known not to have committed.
+      def abort_purge(agent, token)
+        key = normalize_agent_id(agent.agent_id)
+        @mutex.synchronize do
+          entry = @entries[key]
+          validate_purge_entry!(entry, agent, token, key)
+          @entries[key] = Entry.new(state: :live, agent: agent, token: nil)
+          @condition.broadcast
+        end
+        agent.send(:__restore_live_after_purge_abort!, @runtime)
+        true
+      end
+
+      # Unknown durable outcome is fail-closed, but it must not leave load/shutdown
+      # waiters blocked forever. Convert the transition into an explicit stable
+      # recovery-required state and wake all waiters.
+      def leave_purge_uncertain(agent, token)
+        key = normalize_agent_id(agent.agent_id)
+        @mutex.synchronize do
+          validate_purge_entry!(@entries[key], agent, token, key)
+          @entries[key] = Entry.new(
+            state: :recovery_required,
+            agent: agent,
+            token: nil
+          )
+          @condition.broadcast
+        end
+        agent.send(:__mark_ownership_recovery_required!, @runtime)
+        true
+      end
+
+      def begin_draining
+        @mutex.synchronize do
+          @state = :draining if @state == :running
+          @condition.broadcast
+        end
+        self
+      end
+
+      # Live/recovery-required entries do not prevent Runtime shutdown. Only an
+      # ownership transition that is still actively changing state must settle.
+      def wait_until_stable(deadline)
+        @mutex.synchronize do
+          while @entries.values.any? { |entry| %i[constructing purging].include?(entry.state) }
+            remaining = deadline - monotonic_now
+            # :nocov:
+            return false if remaining <= 0
+            # :cover:
+            @condition.wait(@mutex, remaining)
+          end
+          true
+        end
+      end
+
+      def shutdown!
+        agents = @mutex.synchronize do
+          @state = :terminated
+          owned = @entries.values.filter_map(&:agent).uniq
+          @entries.clear
+          @condition.broadcast
+          owned
+        end
+        agents.each { |agent| agent.send(:__release_runtime_owner!, @runtime) }
+        true
+      end
+
+      private
+
+      def reserve_create!(key)
+        token = Object.new.freeze
+        @mutex.synchronize do
+          ensure_running!
+          if (entry = @entries[key])
+            raise ownership_recovery_error(key) if entry.state == :recovery_required
+
+            raise Phronomy::AgentAlreadyExistsError,
+              "Agent #{key.inspect} already exists in this Runtime (#{entry.state})"
+          end
+          @entries[key] = Entry.new(state: :constructing, agent: nil, token: token)
+        end
+        token
+      end
+
+      def publish_constructed!(key, token, agent, expected_class, fail_closed:)
+        validate_expected_class!(agent, expected_class, key)
+        unless agent.agent_id.to_s == key
+          raise Phronomy::Error,
+            "constructed Agent identity mismatch: reserved #{key.inspect}, got #{agent.agent_id.inspect}"
+        end
+
+        agent.send(:__bind_runtime_owner!, @runtime)
+        @mutex.synchronize do
+          entry = @entries[key]
+          unless entry&.state == :constructing && entry.token.equal?(token)
+            raise Phronomy::Error,
+              "Agent ownership reservation for #{key.inspect} was lost during construction"
+          end
+          @entries[key] = Entry.new(state: :live, agent: agent, token: nil)
+          @condition.broadcast
+        end
+        agent
+      rescue
+        # :nocov:
+        if fail_closed
+          fail_construction_closed!(key, token, agent: agent)
+          agent&.send(:__mark_ownership_recovery_required!, @runtime)
+        else
+          release_construction!(key, token)
+        end
+        # :cover:
+        raise
+      end
+
+      def release_construction!(key, token)
+        @mutex.synchronize do
+          entry = @entries[key]
+          # :nocov:
+          if entry&.state == :constructing && entry.token.equal?(token)
+            @entries.delete(key)
+            @condition.broadcast
+          end
+          # :cover:
+        end
+      end
+
+      def fail_construction_closed!(key, token, agent: nil)
+        @mutex.synchronize do
+          entry = @entries[key]
+          # :nocov:
+          return unless entry&.state == :constructing && entry.token.equal?(token)
+          # :cover:
+
+          @entries[key] = Entry.new(
+            state: :recovery_required,
+            agent: agent,
+            token: nil
+          )
+          @condition.broadcast
+        end
+      end
+
+      def validate_expected_class!(agent, expected_class, key)
+        return agent if agent.is_a?(expected_class)
+
+        raise Phronomy::ConfigurationError,
+          "Agent definition mismatch: #{key.inspect} is already live as #{agent.class}, not #{expected_class}"
+      end
+
+      def validate_purge_entry!(entry, agent, token, key)
+        return if entry&.state == :purging &&
+          entry.agent.equal?(agent) && entry.token.equal?(token)
+
+        # :nocov:
+        raise Phronomy::Error,
+          "Agent purge ownership for #{key.inspect} is no longer authoritative"
+        # :cover:
+      end
+
+      def ownership_recovery_error(key)
+        Phronomy::Error.new(
+          "Agent #{key.inspect} ownership requires durable recovery/reconciliation"
+        )
+      end
+
+      def normalize_agent_id(agent_id)
+        key = agent_id.to_s
+        # :nocov:
+        raise ArgumentError, "agent_id must not be empty" if key.empty?
+        # :cover:
+        key.freeze
+      end
+
+      def ensure_running!
+        return if @state == :running
+
+        # :nocov:
+        raise Phronomy::RuntimeShutdownError,
+          "Runtime is #{@state}; Agent ownership changes are not accepted"
+        # :cover:
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end