phronomy 0.1.4 → 0.2.0

data/lib/phronomy/memory/storage/active_record.rb

@@ -170,6 +170,26 @@ module Phronomy
           @model_class.where(thread_id: thread_id).where("created_at < ?", older_than).delete_all
         end
 
+        # Returns the next seq number to use for new raw messages for +thread_id+.
+        # Derived from MAX(seq) in the database; since purge_older_than does not
+        # touch raw records, this value is always correct.
+        #
+        # @param thread_id [String]
+        # @return [Integer]
+        def next_seq(thread_id:)
+          return 0 unless @raw_model_class
+
+          ((@raw_model_class.where(thread_id: thread_id).maximum(:seq) || -1) + 1)
+        end
+
+        # Delegates to the block directly; serialisation of concurrent saves
+        # for the same thread_id is the caller's responsibility (e.g. DB-level
+        # transaction isolation or application-layer queuing).
+        # @param thread_id [String]
+        def with_thread_lock(thread_id:)
+          yield
+        end
+
         private
 
         def ensure_raw_model!

data/lib/phronomy/memory/storage/base.rb

@@ -127,6 +127,28 @@ module Phronomy
         def purge_older_than(thread_id:, older_than:)
           # no-op by default
         end
+
+        # Returns the next seq number to assign when appending new raw messages
+        # for +thread_id+. Must be monotonically increasing and must survive
+        # purge_older_than (i.e. the counter must not reset when old raw records
+        # are deleted by a TTL purge).
+        #
+        # @param thread_id [String]
+        # @return [Integer]
+        def next_seq(thread_id:)
+          raise NotImplementedError, "#{self.class}#next_seq is not implemented"
+        end
+
+        # Executes the block while holding a per-thread-id lock for +thread_id+.
+        # Used by ConversationManager to prevent concurrent compaction for the
+        # same thread. The default implementation yields without locking; backends
+        # that require serialisation should override this method.
+        #
+        # @param thread_id [String]
+        # @yield
+        def with_thread_lock(thread_id:)
+          yield
+        end
       end
     end
   end

data/lib/phronomy/memory/storage/in_memory.rb

@@ -3,18 +3,19 @@
 module Phronomy
   module Memory
     module Storage
-      # In-process Hash-backed storage for conversation messages.
+      # In-process storage for conversation messages backed by per-thread-id
+      # {Phronomy::Actor} instances from {Phronomy::ThreadActorRegistry}.
       # Messages are lost when the process exits.
       #
       # @example
       #   storage = Phronomy::Memory::Storage::InMemory.new
       #   manager = Phronomy::Memory::ConversationManager.new(storage: storage, ...)
       class InMemory < Base
+        # Thread-local key for per-thread-id storage data (namespaced by store
+        # instance object_id to support multiple independent InMemory stores).
+        THREAD_DATA_KEY = :phronomy_storage_in_memory_data
+
         def initialize
-          @mutex = Mutex.new
-          @store = {}
-          @raw_store = {}       # thread_id => [{seq:, message:}, ...]
-          @compaction_store = {} # thread_id => [{start_seq:, end_seq:, summary_text:}, ...]
         end
 
         # -----------------------------------------------------------------------
@@ -24,21 +25,20 @@ module Phronomy
         # @param thread_id [String]
         # @return [Array]
         def load(thread_id:)
-          @mutex.synchronize { (@store[thread_id] || []).dup }
+          Phronomy::ThreadActorRegistry.for(thread_id).call { (thread_data.store || []).dup }
         end
 
         # @param thread_id [String]
         # @param messages  [Array]
         def save(thread_id:, messages:)
-          @mutex.synchronize { @store[thread_id] = messages.dup }
+          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.store = messages.dup }
         end
 
         # @param thread_id [String]
         def clear(thread_id:)
-          @mutex.synchronize do
-            @store.delete(thread_id)
-            @raw_store.delete(thread_id)
-            @compaction_store.delete(thread_id)
+          store_id = object_id
+          Phronomy::ThreadActorRegistry.for(thread_id).call do
+            (Thread.current[THREAD_DATA_KEY] ||= {}).delete(store_id)
           end
         end
 
@@ -49,25 +49,45 @@ module Phronomy
         # @param thread_id    [String]
         # @param messages     [Array]
         # @param starting_seq [Integer]
-        def append_raw(thread_id:, messages:, starting_seq:)
-          now = Time.now
-          @mutex.synchronize do
-            @raw_store[thread_id] ||= []
+        # @param recorded_at  [Time, nil] timestamp for test overrides; defaults to +Time.now+
+        def append_raw(thread_id:, messages:, starting_seq:, recorded_at: nil)
+          now = recorded_at || Time.now
+          Phronomy::ThreadActorRegistry.for(thread_id).call do
+            data = thread_data
             messages.each_with_index do |msg, i|
-              @raw_store[thread_id] << {seq: starting_seq + i, message: msg, recorded_at: now}
+              seq = starting_seq + i
+              data.raw_messages << {seq: seq, message: msg, recorded_at: now}
+              data.hwm = [data.hwm, seq].max
             end
           end
         end
 
+        # @param thread_id [String]
+        # @return [Integer]
+        def next_seq(thread_id:)
+          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.hwm + 1 }
+        end
+
+        # Routes +block+ through the per-thread-id {Phronomy::Actor}, serialising
+        # all operations for the same thread.  Reentrant calls (the block itself
+        # calling storage methods that also route through the Actor) are safe
+        # because {Phronomy::Actor#call} detects the same-thread case and executes
+        # inline.
+        #
+        # @param thread_id [String]
+        def with_thread_lock(thread_id:, &block)
+          Phronomy::ThreadActorRegistry.for(thread_id).call(&block)
+        end
+
         # @param thread_id [String]
         # @return [Array<Hash>]
         def load_raw(thread_id:)
-          @mutex.synchronize { (@raw_store[thread_id] || []).dup }
+          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.raw_messages.dup }
         end
 
         # @param thread_id [String]
         def clear_raw(thread_id:)
-          @mutex.synchronize { @raw_store.delete(thread_id) }
+          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.raw_messages.clear }
         end
 
         # -----------------------------------------------------------------------
@@ -79,21 +99,20 @@ module Phronomy
         # @param end_seq      [Integer]
         # @param summary_text [String]
         def save_compaction(thread_id:, start_seq:, end_seq:, summary_text:)
-          @mutex.synchronize do
-            @compaction_store[thread_id] ||= []
-            @compaction_store[thread_id] << {start_seq: start_seq, end_seq: end_seq, summary_text: summary_text}
+          Phronomy::ThreadActorRegistry.for(thread_id).call do
+            thread_data.compactions << {start_seq: start_seq, end_seq: end_seq, summary_text: summary_text}
           end
         end
 
         # @param thread_id [String]
         # @return [Array<Hash>]
         def load_compactions(thread_id:)
-          @mutex.synchronize { (@compaction_store[thread_id] || []).dup }
+          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.compactions.dup }
         end
 
         # @param thread_id [String]
         def clear_compactions(thread_id:)
-          @mutex.synchronize { @compaction_store.delete(thread_id) }
+          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.compactions.clear }
         end
 
         # Remove raw messages recorded before +older_than+ for this thread.
@@ -101,10 +120,30 @@ module Phronomy
         # @param thread_id  [String]
         # @param older_than [Time]
         def purge_older_than(thread_id:, older_than:)
-          @mutex.synchronize do
-            next unless @raw_store[thread_id]
+          Phronomy::ThreadActorRegistry.for(thread_id).call do
+            thread_data.raw_messages.reject! { |entry| entry[:recorded_at] && entry[:recorded_at] < older_than }
+          end
+        end
+
+        private
+
+        # Returns (or lazily initialises) the {ThreadData} for the current Actor
+        # thread and this storage instance.  Must only be called from within a
+        # {Phronomy::ThreadActorRegistry.for} block so that +Thread.current+ is
+        # the correct Actor thread.
+        def thread_data
+          (Thread.current[THREAD_DATA_KEY] ||= {})[object_id] ||= ThreadData.new
+        end
+
+        # Value object holding all per-thread-id storage state.
+        class ThreadData
+          attr_accessor :store, :raw_messages, :compactions, :hwm
 
-            @raw_store[thread_id].reject! { |entry| entry[:recorded_at] && entry[:recorded_at] < older_than }
+          def initialize
+            @store = nil
+            @raw_messages = []
+            @compactions = []
+            @hwm = -1
           end
         end
       end

data/lib/phronomy/state_store/active_record.rb

@@ -38,7 +38,7 @@ module Phronomy
       end
 
       # Serializes and upserts the state for the given thread_id.
-      # @param state [Object] includes Phronomy::Graph::State
+      # @param state [Object] includes Phronomy::WorkflowContext
       # @return [self]
       def save(state)
         json = serialize_state(state)

data/lib/phronomy/state_store/base.rb

@@ -7,11 +7,11 @@ module Phronomy
     # Abstract base class for state persistence backends.
     # Subclasses must implement save, load, and clear.
     #
-    # The state object passed to save must include Phronomy::Graph::State
-    # and have a non-nil thread_id (set automatically by CompiledGraph#invoke).
+    # The state object passed to save must include Phronomy::WorkflowContext
+    # and have a non-nil thread_id (set automatically by WorkflowRunner#invoke).
     class Base
       # Persists the state. The thread_id is read from state.thread_id.
-      # @param state [Object] object including Phronomy::Graph::State
+      # @param state [Object] object including Phronomy::WorkflowContext
       # @return [self]
       def save(state)
         raise NotImplementedError, "#{self.class}#save is not implemented"
@@ -40,8 +40,7 @@ module Phronomy
           state_class: state.class.name,
           state_data: json_safe(state.to_h),
           thread_id: state.thread_id,
-          current_nodes: state.current_nodes&.map(&:to_s),
-          halted_before: state.halted_before
+          phase: state.phase&.to_s
         )
       end
 
@@ -54,37 +53,36 @@ module Phronomy
         state = state_class.new(**state_data)
         state.set_graph_metadata(
           thread_id: data[:thread_id],
-          current_nodes: data[:current_nodes]&.map(&:to_sym),
-          halted_before: data[:halted_before]
+          phase: data[:phase]&.to_sym
         )
         state
       end
 
-      # Resolves and validates a state class name.
-      # When a registry has been configured via +Phronomy::Graph.register_state_class+,
+      # Resolves and validates a context class name.
+      # When a registry has been configured via +Phronomy.register_workflow_context+,
       # only registered classes are accepted — this prevents unintended autoloading
       # of arbitrary files from an untrusted class name stored in Redis/DB.
       # When no registry is configured, falls back to Object.const_get with a check
-      # that the resolved class includes Phronomy::Graph::State.
+      # that the resolved class includes Phronomy::WorkflowContext.
       def safe_state_class(class_name)
-        registry = Phronomy::Graph.state_class_registry
+        registry = Phronomy.workflow_context_registry
         if registry
           klass = registry[class_name.to_s]
           unless klass
             raise ArgumentError,
-              "Unregistered state class: #{class_name.inspect}. " \
-              "Call Phronomy::Graph.register_state_class(#{class_name}) at startup."
+              "Unregistered context class: #{class_name.inspect}. " \
+              "Call Phronomy.register_workflow_context(#{class_name}) at startup."
           end
           return klass
         end
 
         klass = Object.const_get(class_name.to_s)
-        unless klass.is_a?(Class) && klass.include?(Phronomy::Graph::State)
-          raise ArgumentError, "Invalid state class: #{class_name.inspect}"
+        unless klass.is_a?(Class) && klass.include?(Phronomy::WorkflowContext)
+          raise ArgumentError, "Invalid context class: #{class_name.inspect}"
         end
         klass
       rescue NameError
-        raise ArgumentError, "Unknown state class: #{class_name.inspect}"
+        raise ArgumentError, "Unknown context class: #{class_name.inspect}"
       end
 
       # Recursively converts objects to JSON-safe primitives.

data/lib/phronomy/state_store/in_memory.rb

@@ -2,37 +2,50 @@
 
 module Phronomy
   module StateStore
-    # In-memory state store. Stores state objects keyed by thread_id.
-    # State objects are stored directly (no serialization), so this
-    # backend is suitable for single-process use only.
+    # In-memory state store backed by per-thread-id {Phronomy::Actor} instances
+    # from {Phronomy::ThreadActorRegistry}. Suitable for single-process use only.
     class InMemory < Base
+      # Thread-local key for per-thread-id state data (namespaced by store
+      # instance object_id to support multiple independent InMemory stores).
+      THREAD_DATA_KEY = :phronomy_state_store_in_memory_data
+
       def initialize
-        @store = {}
-        @mutex = Mutex.new
       end
 
-      # @param state [Object] includes Phronomy::Graph::State; must have a non-nil thread_id
+      # @param state [Object] includes Phronomy::WorkflowContext; must have a non-nil thread_id
       # @return [self]
       def save(state)
-        @mutex.synchronize { @store[state.thread_id] = state }
+        store_id = object_id
+        Phronomy::ThreadActorRegistry.for(state.thread_id).call do
+          (Thread.current[THREAD_DATA_KEY] ||= {})[store_id] = state
+        end
         self
       end
 
       # @param thread_id [String]
       # @return [Object, nil] state object or nil
       def load(thread_id)
-        @mutex.synchronize { @store[thread_id] }
+        store_id = object_id
+        Phronomy::ThreadActorRegistry.for(thread_id).call do
+          (Thread.current[THREAD_DATA_KEY] ||= {})[store_id]
+        end
       end
 
       # @param thread_id [String]
       # @return [self]
       def clear(thread_id)
-        @mutex.synchronize { @store.delete(thread_id) }
+        store_id = object_id
+        Phronomy::ThreadActorRegistry.for(thread_id).call do
+          (Thread.current[THREAD_DATA_KEY] ||= {}).delete(store_id)
+        end
         self
       end
 
       def clear_all
-        @mutex.synchronize { @store.clear }
+        store_id = object_id
+        Phronomy::ThreadActorRegistry.each_actor do |actor|
+          actor.call { (Thread.current[THREAD_DATA_KEY] ||= {}).delete(store_id) }
+        end
         self
       end
     end

data/lib/phronomy/state_store/redis.rb

@@ -33,7 +33,7 @@ module Phronomy
         @ttl = ttl
       end
 
-      # @param state [Object] includes Phronomy::Graph::State
+      # @param state [Object] includes Phronomy::WorkflowContext
       # @return [self]
       def save(state)
         serialized = serialize_state(state)

data/lib/phronomy/thread_actor_registry.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Global per-thread-id {Actor} registry.
+  #
+  # Maps the +:thread_id+ key from the +config:+ argument passed to
+  # {Phronomy::Agent::Base#invoke} to a {Phronomy::Actor} instance.
+  # Each thread_id gets exactly one Actor so that all operations for the same
+  # conversation are serialised automatically.
+  #
+  # @example
+  #   Phronomy::ThreadActorRegistry.for("user-42").call do
+  #     # runs sequentially on the Actor's thread
+  #   end
+  module ThreadActorRegistry
+    @actors = {}
+    @registry_actor = Actor.new
+
+    class << self
+      # Returns (or lazily creates) the {Actor} for +thread_id+.
+      #
+      # @param thread_id [String]
+      # @return [Phronomy::Actor]
+      def for(thread_id)
+        @registry_actor.call { @actors[thread_id] ||= Actor.new }
+      end
+
+      # Gracefully stops the Actor for +thread_id+ and removes it from the
+      # registry.  The next call to {.for} with the same id creates a fresh Actor.
+      #
+      # @param thread_id [String]
+      def stop(thread_id)
+        @registry_actor.call { @actors.delete(thread_id) }&.stop
+      end
+
+      # Stops and removes every registered Actor.
+      # Intended for test teardown and process shutdown.
+      def clear_all
+        actors = @registry_actor.call { @actors.values.tap { @actors.clear } }
+        actors.each(&:stop)
+      end
+
+      # Yields each currently registered Actor.
+      # A snapshot is taken so the registry cannot change while callers iterate.
+      #
+      # @yield [Phronomy::Actor]
+      def each_actor(&block)
+        @registry_actor.call { @actors.values.dup }.each(&block)
+      end
+    end
+  end
+end

data/lib/phronomy/tool/base.rb

@@ -58,7 +58,7 @@ module Phronomy
         end
 
         # Sets the access scope for this tool (metadata; enforcement is the responsibility of
-        # the Graph/Guardrail layer).
+        # the Workflow/Guardrail layer).
         # @param value [Symbol] e.g. :read_only, :write, :admin
         def scope(value = nil)
           return @scope if value.nil?

data/lib/phronomy/tool/mcp_tool.rb

@@ -87,7 +87,7 @@ module Phronomy
           # Split the command string into an argv array so that Open3 executes
           # it directly without going through the shell, preventing injection.
           @command = Shellwords.split(command)
-          @mutex = Mutex.new
+          @actor = Phronomy::Actor.new
           @stdin = nil
           @stdout = nil
           @stderr = nil
@@ -97,20 +97,21 @@ module Phronomy
 
         # Shut down the child process and close its IO streams.
         def close
-          @mutex.synchronize do
+          stderr_thread, wait_thr = @actor.call do
             @stdin&.close
             @stdout&.close
             @stderr&.close
             @stdin = nil
             @stdout = nil
             @stderr = nil
+            t = [@stderr_thread, @wait_thr]
+            @stderr_thread = nil
+            @wait_thr = nil
+            t
           end
-          # Join the stderr drain thread and the child process outside the mutex
-          # to avoid holding the lock during potentially slow joins.
-          @stderr_thread&.join(1)
-          @wait_thr&.join(5)
-          @stderr_thread = nil
-          @wait_thr = nil
+          # Join outside the Actor to avoid blocking the Actor thread on slow joins.
+          stderr_thread&.join(1)
+          wait_thr&.join(5)
         end
 
         # Retrieve the tool definition from the server using the MCP `tools/list` method.
@@ -167,7 +168,7 @@ module Phronomy
         end
 
         def rpc_call(method, params)
-          @mutex.synchronize do
+          @actor.call do
             ensure_started!
             payload = JSON.generate(jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params)
             @stdin.puts(payload)

data/lib/phronomy/tracing/langfuse_tracer.rb

@@ -36,7 +36,7 @@ module Phronomy
         @secret_key = secret_key
         @host = host.chomp("/")
         @http = nil
-        @http_mutex = Mutex.new
+        @actor = Phronomy::Actor.new
       end
 
       # Returns a plain Hash that records the span start state.
@@ -90,13 +90,13 @@ module Phronomy
         req["Authorization"] = "Basic #{Base64.strict_encode64("#{@public_key}:#{@secret_key}")}"
         req.body = JSON.generate({batch: events})
 
-        @http_mutex.synchronize do
+        @actor.call do
           @http ||= build_http(uri)
           @http.request(req)
         end
       rescue IOError, Errno::ECONNRESET, Errno::EPIPE => e
         # Connection was reset; drop the cached connection and warn.
-        @http_mutex.synchronize { @http = nil }
+        @actor.call { @http = nil }
         warn "[Phronomy::LangfuseTracer] Ingestion failed: #{e.class}: #{e.message}"
         nil
       rescue => e

data/lib/phronomy/trust_pipeline.rb

@@ -56,7 +56,7 @@ module Phronomy
     # Internal graph state — not part of the public API.
     # @private
     class PipelineState
-      include Phronomy::Graph::State
+      include Phronomy::WorkflowContext
 
       field :input, type: :replace, default: -> { "" }
       field :draft, type: :replace, default: -> {}
@@ -89,7 +89,7 @@ module Phronomy
       @threshold = confidence_threshold.to_f
       @max_iterations = max_iterations.to_i
       @input_delimiter = input_delimiter
-      @graph_mutex = Mutex.new
+      @actor = Phronomy::Actor.new
       @compiled_graph = nil
     end
 
@@ -118,66 +118,58 @@ module Phronomy
       [(state.self_score || 0.0).to_f, (state.review_score || 0.0).to_f].min
     end
 
-    # Returns the compiled graph, building and caching it on first call.
-    # Thread-safe via double-checked locking.
+    # Returns the compiled workflow, building and caching it on first call.
     def compiled_graph
-      return @compiled_graph if @compiled_graph
-
-      @graph_mutex.synchronize do
-        @compiled_graph ||= build_graph.compile
-      end
+      @actor.call { @compiled_graph ||= build_workflow }
     end
 
-    def build_graph
+    def build_workflow
       draft_agent = @draft_agent_class.new
       review_agent = @review_agent_class.new
       threshold = @threshold
       max_iter = @max_iterations
+      pipeline = self
 
-      graph = Phronomy::Graph::StateGraph.new(PipelineState)
+      Phronomy::Workflow.define(PipelineState) do
+        initial :draft
 
-      graph.add_node(:draft) do |state|
-        feedback = state.review_notes.last
-        prompt = draft_prompt(state.input, feedback)
-        result = draft_agent.invoke(prompt)
-        parsed = safe_parse_draft(result[:output])
-        state.merge(
-          draft: parsed[:answer].to_s,
-          self_score: clamp(parsed[:confidence]),
-          citations: normalize_citations(parsed[:citations]),
-          iteration: state.iteration + 1
-        )
-      end
+        state :draft, action: ->(state) {
+          feedback = state.review_notes.last
+          prompt = pipeline.__send__(:draft_prompt, state.input, feedback)
+          result = draft_agent.invoke(prompt)
+          parsed = pipeline.__send__(:safe_parse_draft, result[:output])
+          state.merge(
+            draft: parsed[:answer].to_s,
+            self_score: pipeline.__send__(:clamp, parsed[:confidence]),
+            citations: pipeline.__send__(:normalize_citations, parsed[:citations]),
+            iteration: state.iteration + 1
+          )
+        }
 
-      graph.add_node(:review) do |state|
-        prompt = review_prompt(state.input, state.draft, state.citations)
-        result = review_agent.invoke(prompt)
-        parsed = safe_parse_review(result[:output])
-        state.merge(
-          review_score: clamp(parsed[:score]),
-          approved: parsed[:approved] == true,
-          review_notes: parsed[:feedback].to_s
-        )
-      end
+        state :review, action: ->(state) {
+          prompt = pipeline.__send__(:review_prompt, state.input, state.draft, state.citations)
+          result = review_agent.invoke(prompt)
+          parsed = pipeline.__send__(:safe_parse_review, result[:output])
+          state.merge(
+            review_score: pipeline.__send__(:clamp, parsed[:score]),
+            approved: parsed[:approved] == true,
+            review_notes: parsed[:feedback].to_s
+          )
+        }
 
-      graph.add_node(:finalize) do |state|
-        state.merge(output: state.draft)
-      end
+        state :finalize, action: ->(state) { state.merge(output: state.draft) }
 
-      graph.set_entry_point(:draft)
-      graph.add_edge(:draft, :review)
-      graph.add_conditional_edges(
-        :review,
-        ->(state) {
-          confidence = [state.self_score || 0.0, state.review_score || 0.0].min
-          passed = confidence >= threshold && state.approved
-          exhausted = state.iteration >= max_iter
-          (passed || exhausted) ? :finalize : :draft
-        }
-      )
-      graph.add_edge(:finalize, Phronomy::Graph::StateGraph::FINISH)
+        after :draft, to: :review
+        after :finalize, to: :__finish__
 
-      graph
+        event :route_review, from: :review,
+          guard: ->(state) {
+            confidence = [state.self_score || 0.0, state.review_score || 0.0].min
+            (confidence >= threshold && state.approved) || state.iteration >= max_iter
+          },
+          to: :finalize
+        event :route_review, from: :review, to: :draft
+      end
     end
 
     # Wraps +input+ with the configured delimiter pair when +input_delimiter+ is set.