phronomy 0.18.0 → 0.19.0

data/lib/phronomy/agent/journal_projection.rb

@@ -10,9 +10,13 @@ module Phronomy
       ].freeze
       KNOWLEDGE_RESET_KINDS = %i[knowledge_cleared context_reset].freeze
 
-      def initialize(persistence:, agent_root:)
+      def initialize(agent_root:, persistence: nil, records: nil)
         @persistence = persistence
         @agent_root = agent_root
+        @records = records&.dup&.freeze
+        if @records.nil? && @persistence.nil?
+          raise ArgumentError, "JournalProjection requires persistence: or records:"
+        end
       end
 
       def transcript_records

data/lib/phronomy/configuration.rb

@@ -16,7 +16,7 @@ module Phronomy
     attr_accessor :trace_pii
     attr_accessor :logger
     attr_accessor :event_loop_stop_grace_seconds
-    attr_accessor :state_store
+    attr_accessor :persistence
     attr_accessor :tool_result_max_size
     attr_accessor :llm_adapter
     attr_accessor :event_loop_starvation_threshold_seconds
@@ -53,6 +53,7 @@ module Phronomy
       @authorization_pool_size = 4
       @authorization_queue_size = 100
       @authorization_timeout = 5
+      @persistence = nil
     end
   end
 end

data/lib/phronomy/engine/event_loop.rb

@@ -29,6 +29,7 @@ module Phronomy
       @fsms = {}
       @waiting = {}
       @admitted_session_ids = Set.new
+      @workflow_admissions = {}
 
       @lifecycle_mutex = Mutex.new
       @idle_cond = ConditionVariable.new
@@ -99,7 +100,7 @@ module Phronomy
         rescue
           @admitted_session_ids.delete(fsm_session.id)
           @outstanding_sessions -= 1
-          @idle_cond.broadcast if @outstanding_sessions.zero?
+          @idle_cond.broadcast if runtime_idle_locked?
           raise
         end
       end
@@ -152,6 +153,73 @@ module Phronomy
       true
     end
 
+    # Reserves one logical Workflow thread for one concrete FSMSession execution.
+    # thread_id is durable Workflow identity; owner_fsm_session_id is the
+    # Runtime-only identity of the invocation/resume that currently owns it.
+    def admit_workflow(thread_id, owner_fsm_session_id:)
+      key = thread_id.to_s
+      owner = owner_fsm_session_id.to_s
+      raise ArgumentError, "thread_id must not be empty" if key.empty?
+      raise ArgumentError, "owner_fsm_session_id must not be empty" if owner.empty?
+
+      @lifecycle_mutex.synchronize do
+        ensure_accepting_registrations!
+        current_owner = @workflow_admissions[key]
+        if current_owner
+          raise Phronomy::Error,
+            "Workflow thread #{key.inspect} is already owned by " \
+            "FSMSession #{current_owner.inspect}"
+        end
+        @workflow_admissions[key] = owner
+      end
+      true
+    end
+
+    # Releases a Workflow reservation only when the caller is its current owner.
+    # A failed competing admission can therefore never release another session's
+    # reservation during cleanup.
+    def release_workflow(thread_id, owner_fsm_session_id:)
+      key = thread_id.to_s
+      owner = owner_fsm_session_id.to_s
+      @lifecycle_mutex.synchronize do
+        next false unless @workflow_admissions[key] == owner
+
+        @workflow_admissions.delete(key)
+        @idle_cond.broadcast if runtime_idle_locked?
+        true
+      end
+    end
+
+    def workflow_admission_owner(thread_id)
+      @lifecycle_mutex.synchronize { @workflow_admissions[thread_id.to_s] }
+    end
+
+    # Resolves durable Workflow identity to the currently owning FSMSession and
+    # enqueues the event atomically with that ownership check.
+    def post_to_workflow(thread_id:, event:, payload: nil)
+      queued_depth = nil
+      posted_event = nil
+      accepted = @lifecycle_mutex.synchronize do
+        next false unless accepting_events?
+
+        owner = @workflow_admissions[thread_id.to_s]
+        next false unless owner
+        next false unless @admitted_session_ids.include?(owner)
+
+        posted_event = Phronomy::Event.new(
+          type: event.to_sym,
+          target_id: owner,
+          payload: payload
+        )
+        queued_depth = enqueue([posted_event, monotonic_nanoseconds])
+        true
+      end
+      return false unless accepted
+
+      check_queue_backlog(queued_depth, posted_event)
+      true
+    end
+
     # Interrupts the queue wait so EventLoop can recompute the next timer deadline.
     def wake
       @queue.push(WAKE)
@@ -180,12 +248,12 @@ module Phronomy
     end
 
     def idle?
-      @lifecycle_mutex.synchronize { @outstanding_sessions.zero? }
+      @lifecycle_mutex.synchronize { runtime_idle_locked? }
     end
 
     def wait_until_idle(deadline)
       @lifecycle_mutex.synchronize do
-        until @outstanding_sessions.zero?
+        until runtime_idle_locked?
           remaining = deadline - monotonic_now
           return false if remaining <= 0
           @idle_cond.wait(@lifecycle_mutex, remaining)
@@ -287,7 +355,9 @@ module Phronomy
         session_id = event.payload.fetch(:session_id)
         session = @fsms.delete(session_id)
         waiter = @waiting.delete(session_id)
-        # decrement before waking caller so wait_until_idle sees zero immediately
+        # decrement before waking caller so wait_until_idle sees the control-plane
+        # session count immediately; Workflow durable admission may intentionally
+        # keep Runtime non-idle until its terminal save completes.
         decrement_outstanding if session
         complete_waiter(waiter, event.payload.fetch(:result))
       when :start
@@ -297,10 +367,11 @@ module Phronomy
         @waiting[session.id] = waiter if waiter
         session.start
       when :agent_terminal_ready
-        # Existing Agent terminalisation is retained in this proposal. A separate
-        # follow-up may move it to an Agent-owned terminalising FSM state.
         cmd = event.payload.fetch(:command)
         cmd.coordinator.deliver_on_event_loop(cmd)
+      when :workflow_persistence_ready
+        cmd = event.payload.fetch(:command)
+        cmd.runner.deliver_persistence_on_event_loop(cmd)
       end
     end
 
@@ -314,7 +385,7 @@ module Phronomy
     def begin_stopping_if_idle
       @lifecycle_mutex.synchronize do
         return false unless @state == :draining
-        return false unless @outstanding_sessions.zero?
+        return false unless runtime_idle_locked?
 
         @state = :stopping
         @queue.push(STOP)
@@ -337,6 +408,7 @@ module Phronomy
       @fsms.clear
       @lifecycle_mutex.synchronize do
         @admitted_session_ids.clear
+        @workflow_admissions.clear
         @outstanding_sessions = 0
         @idle_cond.broadcast
       end
@@ -356,6 +428,7 @@ module Phronomy
       @lifecycle_mutex.synchronize do
         @state = :failed
         @admitted_session_ids.clear
+        @workflow_admissions.clear
         @idle_cond.broadcast
       end
       cleanup_abandoned_work(error)
@@ -375,10 +448,14 @@ module Phronomy
     def decrement_outstanding
       @lifecycle_mutex.synchronize do
         @outstanding_sessions -= 1 if @outstanding_sessions.positive?
-        @idle_cond.broadcast if @outstanding_sessions.zero?
+        @idle_cond.broadcast if runtime_idle_locked?
       end
     end
 
+    def runtime_idle_locked?
+      @outstanding_sessions.zero? && @workflow_admissions.empty?
+    end
+
     def join_until(deadline)
       remaining = deadline - monotonic_now
       return if remaining <= 0
@@ -391,6 +468,7 @@ module Phronomy
       @lifecycle_mutex.synchronize do
         @state = :terminated
         @admitted_session_ids.clear
+        @workflow_admissions.clear
         @thread = nil unless @thread&.alive?
         @idle_cond.broadcast
       end

data/lib/phronomy/engine/fsm_session.rb

@@ -25,9 +25,11 @@ module Phronomy
       event_loop:,
       resume_event: nil,
       resume_phase: nil,
-      stable_observer: nil
+      stable_observer: nil,
+      graph_thread_id: nil
     )
       @id = id
+      @graph_thread_id = graph_thread_id || id
       @ctx = context
       @context = context
       @entry_point = entry_point
@@ -217,7 +219,7 @@ module Phronomy
       return if @done
 
       @done = true
-      @ctx.set_graph_metadata(thread_id: @id, phase: :__end__)
+      @ctx.set_graph_metadata(thread_id: @graph_thread_id, phase: :__end__)
       post_terminal_event(:finished, @ctx)
     end
 
@@ -225,7 +227,7 @@ module Phronomy
       return if @done
 
       @done = true
-      @ctx.set_graph_metadata(thread_id: @id, phase: @current_state)
+      @ctx.set_graph_metadata(thread_id: @graph_thread_id, phase: @current_state)
       post_terminal_event(:halted, @ctx)
     end
 
@@ -248,7 +250,7 @@ module Phronomy
 
       Phronomy.configuration.logger&.warn(
         "[Phronomy::FSMSession] EventLoop rejected terminal event " \
-        "#{type.inspect} for #{@id}"
+          "#{type.inspect} for #{@id}"
       )
     end
 

data/lib/phronomy/engine/runtime.rb

@@ -69,6 +69,7 @@ module Phronomy
       @pool_registry = Phronomy::Concurrency::PoolRegistry.new(
         timer_queue_provider: -> { timer_queue }
       )
+      @agent_activations = Phronomy::Agent::ActivationRegistry.new
       @lifecycle_mutex = Mutex.new
       @shutdown_mutex = Mutex.new
       @state = :running
@@ -107,6 +108,12 @@ module Phronomy
       @timer_service.timer_queue
     end
 
+    # Process-local live Agent executions. Activations are transient runtime
+    # state and deliberately do not belong to Persistence.
+    def __agent_activations
+      @agent_activations
+    end
+
     def event_loop
       @lifecycle_mutex.synchronize do
         case @state

data/lib/phronomy/persistence/in_memory.rb

@@ -66,7 +66,7 @@ module Phronomy
 
         def save(agent_id, expected_revision:, root:)
           @owner.synchronize do
-            current = load(agent_id)
+            current = @owner.state[:agents].fetch(agent_id.to_s) { raise NotFoundError, "agent not found: #{agent_id}" }
             unless current.agent_revision == expected_revision
               raise ConflictError,
                 "agent revision conflict: expected #{expected_revision}, actual #{current.agent_revision}"
@@ -162,7 +162,7 @@ module Phronomy
 
         def save(execution_id, expected_revision:, execution:)
           @owner.synchronize do
-            current = load(execution_id)
+            current = @owner.state[:executions].fetch(execution_id.to_s) { raise NotFoundError, "execution not found: #{execution_id}" }
             unless current.execution_revision == expected_revision
               raise ConflictError,
                 "execution revision conflict: expected #{expected_revision}, actual #{current.execution_revision}"
@@ -209,31 +209,112 @@ module Phronomy
         end
       end
 
-      attr_reader :state
+      class WorkflowStates
+        def initialize(owner) = @owner = owner
+
+        def load(thread_id)
+          @owner.synchronize do
+            record = @owner.workflow_state_data[thread_id.to_s]
+            next nil unless record
+
+            {
+              snapshot: @owner.deep_dup_workflow_value(record.fetch(:snapshot)),
+              revision: record.fetch(:revision)
+            }.freeze
+          end
+        end
+
+        def save(thread_id, expected_revision:, snapshot:)
+          @owner.synchronize do
+            key = thread_id.to_s
+            current = @owner.workflow_state_data[key]
+            actual_revision = current&.fetch(:revision)
+            unless actual_revision == expected_revision
+              raise ConflictError,
+                "workflow state revision conflict for #{key}: " \
+                "expected #{expected_revision.inspect}, actual #{actual_revision.inspect}"
+            end
+
+            next_revision = actual_revision ? actual_revision + 1 : 1
+            @owner.workflow_state_data[key] = {
+              snapshot: @owner.deep_dup_workflow_value(snapshot),
+              revision: next_revision
+            }
+            next_revision
+          end
+        end
+
+        def delete(thread_id, expected_revision:)
+          @owner.synchronize do
+            key = thread_id.to_s
+            current = @owner.workflow_state_data[key]
+            actual_revision = current&.fetch(:revision)
+            unless actual_revision == expected_revision
+              raise ConflictError,
+                "workflow state revision conflict for #{key}: " \
+                "expected #{expected_revision.inspect}, actual #{actual_revision.inspect}"
+            end
+            @owner.workflow_state_data.delete(key)
+          end
+          nil
+        end
+      end
+
+      attr_reader :state, :workflow_state_data
 
       def initialize
         @monitor = Monitor.new
         @state = {contents: {}, agents: {}, journals: {}, executions: {}}
+        @workflow_state_data = {}
         @contents = Contents.new(self)
         @agents = Agents.new(self)
         @journals = Journals.new(self)
         @executions = Executions.new(self)
-        @activations = Phronomy::Agent::ActivationRegistry.new
-        super(contents: @contents, agents: @agents, journals: @journals,
-              executions: @executions, activations: @activations)
+        @workflow_states = WorkflowStates.new(self)
+        super(
+          contents: @contents,
+          agents: @agents,
+          journals: @journals,
+          executions: @executions,
+          workflow_states: @workflow_states
+        )
       end
 
       def capabilities
         {atomic_all: true, atomic_admission: true, optimistic_revision: true}.freeze
       end
 
+      def assert_agent_watermark!(agent_id:, agent_revision:, journal_position:)
+        synchronize do
+          stored = @state[:agents][agent_id.to_s]
+          unless stored
+            raise NotFoundError, "Agent not found: #{agent_id}"
+          end
+
+          if stored.agent_revision != agent_revision
+            raise ConflictError,
+              "agent revision conflict: expected #{agent_revision}, actual #{stored.agent_revision}"
+          end
+
+          actual_position = Array(@state[:journals][agent_id.to_s]).length
+          if actual_position != journal_position
+            raise ConflictError,
+              "journal position conflict: expected #{journal_position}, actual #{actual_position}"
+          end
+
+          true
+        end
+      end
+
       def transaction
         synchronize do
-          snapshot = Marshal.load(Marshal.dump(@state))
+          state_snapshot = Marshal.load(Marshal.dump(@state))
+          workflow_snapshot = deep_dup_workflow_value(@workflow_state_data)
           begin
             yield self
           rescue
-            @state = snapshot
+            @state.replace(state_snapshot)
+            @workflow_state_data.replace(workflow_snapshot)
             raise
           end
         end
@@ -242,6 +323,30 @@ module Phronomy
       def synchronize(&block)
         @monitor.synchronize(&block)
       end
+
+      # Workflow fields historically accepted ordinary Ruby values in the
+      # in-memory store. Keep that contract without forcing the Agent durable
+      # state Marshal snapshot to serialize arbitrary Workflow values.
+      def deep_dup_workflow_value(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, child), result|
+            result[deep_dup_workflow_value(key)] = deep_dup_workflow_value(child)
+          end
+        when Array
+          value.map { |child| deep_dup_workflow_value(child) }
+        when NilClass, Symbol, Integer, Float, TrueClass, FalseClass
+          value
+        else
+          return value if value.frozen?
+
+          begin
+            value.dup
+          rescue TypeError
+            value
+          end
+        end
+      end
     end
   end
 end

data/lib/phronomy/persistence.rb

@@ -6,14 +6,14 @@ module Phronomy
     class NotFoundError < Phronomy::Error; end
     class UnsupportedBackendError < Phronomy::Error; end
 
-    attr_reader :contents, :agents, :journals, :executions, :activations
+    attr_reader :contents, :agents, :journals, :executions, :workflow_states
 
-    def initialize(contents:, agents:, journals:, executions:, activations:)
+    def initialize(contents:, agents:, journals:, executions:, workflow_states:)
       @contents = contents
       @agents = agents
       @journals = journals
       @executions = executions
-      @activations = activations
+      @workflow_states = workflow_states
       validate_capabilities!
     end
 
@@ -25,6 +25,15 @@ module Phronomy
       raise UnsupportedBackendError, "#{self.class} does not provide atomic_all"
     end
 
+    # Verifies that a live Agent still owns the durable base it hydrated.
+    # Backends should implement this as a revision/position precondition check,
+    # not as a state reload returned to the caller.
+    # @api private
+    def assert_agent_watermark!(agent_id:, agent_revision:, journal_position:)
+      raise UnsupportedBackendError,
+        "#{self.class} does not provide Agent durable-watermark checks"
+    end
+
     private
 
     def validate_capabilities!

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.18.0"
+  VERSION = "0.19.0"
 end

data/lib/phronomy/workflow.rb

@@ -8,8 +8,8 @@ module Phronomy
   class Workflow
     include Phronomy::Runnable
 
-    def self.define(context_class, state_store: nil, &block)
-      builder = Builder.new(context_class, state_store: state_store)
+    def self.define(context_class, persistence: nil, &block)
+      builder = Builder.new(context_class, persistence: persistence)
       builder.instance_eval(&block)
       builder.build
     end
@@ -41,12 +41,13 @@ module Phronomy
       @runner.send_event(state: state, event: event, input: input)
     end
 
-    # Sends an event to an active Workflow session without blocking.
+    # Sends an event to an active Workflow execution without blocking.
     #
-    # This method is safe to call from an Agent/Tool listener running on the
-    # EventLoop thread because it only enqueues a later dispatch.
+    # +thread_id+ is the logical/durable Workflow identity. EventLoop resolves it
+    # to the currently owning Runtime-only fsm_session_id. InvocationContext's
+    # application session_id is unrelated to this routing.
     #
-    # @return [Boolean] true when admitted; false when the session is not live
+    # @return [Boolean] true when admitted; false when the Workflow is not live
     #   or Runtime shutdown has begun
     # @api public
     def signal(thread_id:, event:, payload: nil)
@@ -76,9 +77,9 @@ module Phronomy
     class Builder
       FINISH = Phronomy::WorkflowRunner::FINISH
 
-      def initialize(context_class, state_store: nil)
+      def initialize(context_class, persistence: nil)
         @context_class = context_class
-        @state_store = state_store
+        @persistence = persistence
         @initial = nil
         @declared_states = []
         @entry_actions = {}
@@ -167,7 +168,7 @@ module Phronomy
           external_events: external_events,
           entry_point: @initial || @declared_states.first,
           wait_state_names: @wait_state_names.dup,
-          state_store: @state_store
+          persistence: @persistence
         )
         Workflow.new(runner)
       end