phronomy 0.18.0 → 0.20.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/agent/llm_call_record.rb

@@ -39,6 +39,10 @@ module Phronomy
         freeze
       end
 
+      # Returns the canonical durable representation of this LLM Call record.
+      #
+      # @return [Hash{String => Object}]
+      # @api public
       def to_h
         ATTRIBUTES.to_h do |name|
           value = public_send(name)
@@ -46,6 +50,22 @@ module Phronomy
           [name.to_s, value]
         end
       end
+
+      # Restores an LLM Call record from its canonical durable representation.
+      # String and Symbol top-level keys are accepted so database adapters may
+      # pass either a parsed JSON object or a Ruby-native Hash.
+      #
+      # @param hash [Hash]
+      # @return [LLMCallRecord]
+      # @api public
+      def self.from_h(hash)
+        attributes = ATTRIBUTES.to_h do |name|
+          key = hash.key?(name.to_s) ? name.to_s : name
+          [name, hash.fetch(key)]
+        end
+        attributes[:status] = attributes.fetch(:status).to_sym
+        new(**attributes)
+      end
     end
   end
 end

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

@@ -5,31 +5,134 @@ module Phronomy
     class ConflictError < Phronomy::Error; end
     class NotFoundError < Phronomy::Error; end
     class UnsupportedBackendError < Phronomy::Error; end
+    class SerializationError < Phronomy::Error; end
 
-    attr_reader :contents, :agents, :journals, :executions, :activations
+    REQUIRED_CAPABILITIES = {
+      atomic_all: true,
+      atomic_admission: true,
+      optimistic_revision: true
+    }.freeze
 
-    def initialize(contents:, agents:, journals:, executions:, activations:)
+    # Durable repository accessors supplied by a Persistence backend.
+    #
+    # The repository objects are part of the Backend SPI. They may be private
+    # implementation classes owned by the backend; they do not need to inherit
+    # from Phronomy repository base classes.
+    #
+    # @return [Object] content-addressed immutable content repository
+    # @api public
+    attr_reader :contents
+
+    # @return [Object] AgentRoot repository
+    # @api public
+    attr_reader :agents
+
+    # @return [Object] append-only Agent Journal repository
+    # @api public
+    attr_reader :journals
+
+    # @return [Object] AgentExecution repository
+    # @api public
+    attr_reader :executions
+
+    # @return [Object] durable Workflow snapshot repository
+    # @api public
+    attr_reader :workflow_states
+
+    # Initializes a Persistence backend with its durable repositories.
+    #
+    # Subclasses normally construct backend-specific repository objects and then
+    # call +super+. The backend must advertise every capability in
+    # {REQUIRED_CAPABILITIES}; construction fails fast otherwise.
+    #
+    # @param contents [Object]
+    # @param agents [Object]
+    # @param journals [Object]
+    # @param executions [Object]
+    # @param workflow_states [Object]
+    # @raise [UnsupportedBackendError] when a required capability is missing
+    # @api public
+    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
 
+    # Declares storage semantics provided by this backend.
+    #
+    # Required meanings:
+    # - +atomic_all+: all durable repositories can participate in one atomic
+    #   transaction domain.
+    # - +atomic_admission+: Agent execution admission is atomic; at most one
+    #   active/suspended execution may be admitted for one Agent. This does not
+    #   mean cross-process Workflow admission or distributed locking.
+    # - +optimistic_revision+: Agent, Execution, Workflow revision checks and
+    #   Journal position checks provide compare-and-swap conflict detection.
+    #
+    # @return [Hash{Symbol => Boolean}]
+    # @api public
     def capabilities
-      {atomic_all: false, atomic_admission: false}.freeze
+      {
+        atomic_all: false,
+        atomic_admission: false,
+        optimistic_revision: false
+      }.freeze
     end
 
+    # Executes one atomic durable transaction.
+    #
+    # The object yielded to the block is a transaction-scoped Persistence view.
+    # It must respond to +contents+, +agents+, +journals+, +executions+,
+    # +workflow_states+, and +assert_agent_watermark!+. It may be +self+, but
+    # backends are free to yield a separate transaction view backed by a checked
+    # out connection/session.
+    #
+    # If the block raises, mutations made through the transaction view must not
+    # be committed. Storage failures whose commit outcome is fundamentally
+    # unknown remain backend/database failures; Phronomy does not claim
+    # exactly-once semantics for such failures.
+    #
+    # @yieldparam transaction_view [Object]
+    # @return [Object] the block result
+    # @raise [UnsupportedBackendError] when atomic transactions are unavailable
+    # @api public
     def transaction
       raise UnsupportedBackendError, "#{self.class} does not provide atomic_all"
     end
 
+    # Verifies that a live Agent still owns the durable base it hydrated.
+    #
+    # This is a Backend SPI operation invoked by Phronomy at durable barriers.
+    # Ordinary application code should not call it directly. The backend must
+    # compare the stored Agent revision and current Journal position against the
+    # supplied watermark in the same storage consistency view used by subsequent
+    # writes in the surrounding transaction.
+    #
+    # The method is a precondition check only. It must not reload or return
+    # replacement mutable Agent state; the live Agent remains the logical owner.
+    #
+    # @param agent_id [String]
+    # @param agent_revision [Integer]
+    # @param journal_position [Integer]
+    # @return [true]
+    # @raise [NotFoundError] when the Agent does not exist
+    # @raise [ConflictError] when either durable watermark component differs
+    # @raise [UnsupportedBackendError] when the backend does not implement the check
+    # @api public
+    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!
-      required = {atomic_all: true, atomic_admission: true}
-      missing = required.reject { |key, value| capabilities[key] == value }
+      missing = REQUIRED_CAPABILITIES.reject do |key, value|
+        capabilities[key] == value
+      end
       return if missing.empty?
 
       raise UnsupportedBackendError,

data/lib/phronomy/testing/persistence_contract/a_content_store.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples "a persistence content store" do
+  let(:content_store) { persistence.contents }
+
+  it "returns the same content_id for the same bytes" do
+    first = content_store.put("same".b, canonicalization_version: 1)
+    second = content_store.put("same".b, canonicalization_version: 1)
+
+    expect(second).to eq(first)
+  end
+
+  it "round-trips binary bytes" do
+    bytes = "\x00\xFFpayload".b
+    content_id = content_store.put(bytes, canonicalization_version: 1)
+
+    expect(content_store.fetch(content_id)).to eq(bytes)
+    expect(content_store.exist?(content_id)).to be(true)
+  end
+
+  it "raises NotFoundError for a missing content_id" do
+    expect do
+      content_store.fetch("sha256:#{"0" * 64}")
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
+  end
+
+  it "isolates durable bytes from mutation of fetched values" do
+    content_id = content_store.put("immutable".b, canonicalization_version: 1)
+    fetched = content_store.fetch(content_id)
+    fetched << "-caller-change"
+
+    expect(content_store.fetch(content_id)).to eq("immutable".b)
+  end
+
+  it "supports UTF-8 text helpers" do
+    content_id = content_store.put_text("Grüße")
+
+    expect(content_store.fetch_text(content_id)).to eq("Grüße")
+  end
+
+  it "supports canonical JSON helpers" do
+    value = {
+      "z" => [1, true, nil],
+      "a" => {"message" => "hello"}
+    }
+    content_id = content_store.put_json(value)
+
+    expect(content_store.fetch_json(content_id)).to eq(value)
+  end
+end