phronomy 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d95954b46d12542673b5a319b338c7733d579b72105499a55dc4251628bc807f
-  data.tar.gz: 174341a0e329d861066d475b062260c3d78fac86da3d024ebc1594d7a37ec348
+  metadata.gz: c0aaadfedad1ee8b4afa1efb2e205a626a20cd636f268e711dce29128c84b6fe
+  data.tar.gz: f781f66ae3d570caca771d2b5579874169acef5eeed7f6cf99474a4c82fd077a
 SHA512:
-  metadata.gz: ee299b8d67fec8cb268683ffe672daab04a5c5b4794728dbeea3877e6c5216cefe91f292acac977d7293b837cd0b159445d58a87f925781a26f24438faecd010
-  data.tar.gz: 6da71943dc65b3671f5bd34ff18509a8ee2e0b12bfb5fcb206df77ba2c7345c9fd1b59dec90088dc3e8588e9327cb162046a803a9ac7cd405f4d30fc6712ebc3
+  metadata.gz: 73793efee9cf2c0cb81828fc86927181edca2b4d3fa830a6cefa176b30fd70c57c75e71173d57b51d385377ec3795f1d8cb42e25c3650be40eff543fc2f856fd
+  data.tar.gz: b7dd9cc538e478774d46cf7823e4f5e52b599a02fdd1edf300439287dabfe2fc9a90e93f50647fffa246f7f3c90bd4abf6cf258e9723af1222f836d89125dc59

data/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Added
+
+- **`Phronomy::Graph::Context`** module — canonical module for defining workflow
+  context classes (replaces the removed `Phronomy::Graph::State`).
+- **`Phronomy::Graph.register_context_class`** — registers context classes for
+  deserialization from external stores (Redis, DB).
+- **`Phronomy::Workflow.define`** DSL — primary high-level API for declaring
+  stateful workflows (`state`, `wait_state`, `event`, `after`, `initial`).
+- **`Phronomy::Graph::WorkflowRunner`** — state-machine execution engine backing
+  the Workflow DSL. Replaces the removed `CompiledGraph`.
+- **`app.send_event(event, config:)`** — event-driven resume for workflows halted
+  at a `wait_state`.
+- **`state.halted?`** — returns `true` when the workflow is paused at a `wait_state`.
+- **`state.phase`** — single source of truth for execution state.
+
+### Removed
+
+- `Phronomy::Graph::StateGraph` / `CompiledGraph` — use `Phronomy::Workflow.define`.
+- `Phronomy::Graph::State` — use `Phronomy::Graph::Context`.
+- `Phronomy::Graph.register_state_class` — use `register_context_class`.
+- `state.current_nodes` / `state.halted_before` — use `state.phase` / `state.halted?`.
+- `compiled.interrupt_before` / `compiled.interrupt_after` — use `wait_state` + `event`.
+- `compiled.resume` — use `app.send_event`.
+
+---
+
+## [0.2.0] - 2026-05-13
+
+### Added
+
+- `Phronomy::Graph::WorkflowRunner` — state_machines-based execution engine
+  (introduced as the internal successor to `CompiledGraph`).
+- `state.phase` — single source of truth for graph execution state (replaces
+  `current_nodes` + `halted_before` dual attributes).
+- `state.halted?` — returns `true` when the graph is paused.
+- `CompiledGraph#add_wait_state` — declared a named wait state that halts
+  automatically when reached (later superseded by `wait_state` DSL in `Workflow.define`).
+- `CompiledGraph#send_event(state:, event:, input: nil)` — event-driven resume API
+  (later superseded by `app.send_event`).
+
+### Removed
+
+- `ParallelNode` and `add_parallel_node` DSL. Use `Thread.new` or
+  `Concurrent::Future` at the application level instead.
+- `Phronomy::Graph::TimeoutError` (was only used by `ParallelNode`).

data/README.md

@@ -1,12 +1,12 @@
 # Phronomy
 
 **Phronomy** is a Ruby AI agent framework inspired by open-source AI agent frameworks.  
-It provides composable building blocks — Graphs, Agents, and Memory — all powered by [RubyLLM](https://github.com/crmne/ruby_llm) for LLM abstraction.
+It provides composable building blocks — Workflows, Agents, and Memory — all powered by [RubyLLM](https://github.com/crmne/ruby_llm) for LLM abstraction.
 
 ## Features
 
-- **Graph** — Build stateful, branching agent workflows with interrupt/resume support
-- **Graph Parallel Node** — Execute independent graph branches concurrently with configurable merge and error policies
+- **Workflow** — Build stateful, branching agent workflows with wait_state/send_event support
+- **Workflow Parallel Node** — Execute independent workflow branches concurrently using application-level Ruby threads
 - **Agent** — ReAct-style tool-calling agents with memory and guardrails
 - **Before-Completion Hook** — Three-tier (global / class / instance) LLM parameter injection before each chat request
 - **Memory** — Window, summary, ActiveRecord-backed, semantic, and composite conversation memory
@@ -70,31 +70,39 @@ result = ResearchAgent.new.invoke("What happened in AI research this week?")
 puts result[:output]
 ```
 
-### Graph — Stateful workflow with interrupt/resume
+### Workflow — Stateful workflow with wait_state/send_event
 
 ```ruby
-class ReviewState
-  include Phronomy::Graph::State
+class ReviewContext
+  include Phronomy::WorkflowContext
   field :draft,    type: :replace
   field :feedback, type: :replace
   field :approved, type: :replace, default: false
 end
 
-graph = Phronomy::Graph::StateGraph.new(ReviewState)
-graph.add_node(:write)    { |s| { draft: Writer.call(s) } }
-graph.add_node(:review)   { |s| { feedback: Reviewer.call(s.draft) } }
-graph.add_node(:finalize) { |s| { approved: true } }
-graph.add_edge(:write, :review)
-graph.add_edge(:review, :finalize)
-graph.set_entry_point(:write)
-
-# Register an interrupt callback before the :finalize node
-graph.interrupt_before(:finalize) do |state|
-  puts "Draft ready for human review: #{state.draft}"
+app = Phronomy::Workflow.define(ReviewContext) do
+  initial :write
+  state     :write,    action: ->(s) { s.merge(draft: Writer.call(s)) }
+  state     :review,   action: ->(s) { s.merge(feedback: Reviewer.call(s.draft)) }
+  wait_state :awaiting_approval           # halts here for human decision
+  state     :finalize, action: ->(s) { s.merge(approved: true) }
+  after :write,    to: :review
+  after :review,   to: :awaiting_approval
+  after :finalize, to: :__finish__
+  event :approve, from: :awaiting_approval, to: :finalize
+  event :reject,  from: :awaiting_approval, to: :write
 end
 
-compiled = graph.compile
-compiled.invoke({ draft: "" }, config: { thread_id: "doc-1" })
+Phronomy.configure { |c| c.default_state_store = Phronomy::StateStore::InMemory.new }
+
+# First run — halts at :awaiting_approval
+state = app.invoke({ draft: "" }, config: { thread_id: "doc-1" })
+puts "Halted: #{state.halted?}"   # => true
+puts "Draft: #{state.draft}"
+
+# Resume after human approval
+final = app.send_event(:approve, config: { thread_id: "doc-1" })
+puts "Approved: #{final.approved}"  # => true
 ```
 
 ### Multi-Agent — Agent-as-Tool pattern
@@ -238,29 +246,32 @@ result.citations.each do |c|
 end
 ```
 
-### Graph Parallel Node — Concurrent branches
+### Workflow Parallel Node — Concurrent branches
+
+Phronomy does not provide a built-in parallel abstraction. Use application-level Ruby threads inside a `state` action:
 
 ```ruby
-class MyState
-  include Phronomy::Graph::State
+class EnrichContext
+  include Phronomy::WorkflowContext
   field :summary, type: :replace
-  field :tags,    type: :append,  default: -> { [] }
+  field :tags,    type: :append, default: -> { [] }
 end
 
-graph = Phronomy::Graph::StateGraph.new(MyState)
-
-graph.add_parallel_node(
-  :enrich,
-  ->(s) { { summary: Summarizer.call(s) } },
-  ->(s) { { tags:    Tagger.call(s) } },
-  timeout:  10,
-  on_error: :best_effort
-)
+app = Phronomy::Workflow.define(EnrichContext) do
+  initial :enrich
+  state :enrich, action: ->(s) do
+    results = {}
+    threads = [
+      Thread.new { results[:summary] = Summarizer.call(s) },
+      Thread.new { results[:tags]    = Tagger.call(s) }
+    ]
+    threads.each { |t| t.join(10) }  # 10-second timeout
+    s.merge(summary: results[:summary], tags: Array(results[:tags]))
+  end
+  after :enrich, to: :__finish__
+end
 
-graph.set_entry_point(:enrich)
-graph.add_edge(:enrich, Phronomy::Graph::StateGraph::FINISH)
-app = graph.compile
-app.invoke({}, config: { thread_id: "t1" })
+state = app.invoke({}, config: { thread_id: "t1" })
 ```
 
 ### Output Parser — Structured LLM responses
@@ -483,8 +494,8 @@ bundle exec ruby NN_example_name/run.rb
 |---|-----------|----------------------|
 | 01 | `01_basic_chain/` | PromptTemplate → LLMChain pipeline |
 | 02 | `02_react_agent/` | ReAct tool-calling agent |
-| 03 | `03_state_graph/` | Stateful graph with interrupt/resume |
-| 04 | `04_interrupt_resume/` | Human-in-the-loop interrupt and resume |
+| 03 | `03_state_graph/` | Stateful workflow with wait_state/send_event |
+| 04 | `04_interrupt_resume/` | Human-in-the-loop wait_state and resume |
 | 05 | `05_multi_agent/` | Multi-agent coordination via Agent-as-Tool |
 | 06 | `06_guardrails/` | Input/output guardrails |
 | 07 | `07_tracing/` | Custom observability with Langfuse tracer |

data/docs/trustworthy_ai_enhancements.md

@@ -49,7 +49,7 @@ cannot be delegated to the LLM must be enforced by phronomy or the application l
 | Layer | Responsibility | Status |
 |---|---|---|
 | LLM | Basic harmful-content avoidance (RLHF) | Model-dependent, not guaranteed |
-| **phronomy** | Intervention points, iteration limits, approval gates | ✅ `interrupt_before/after`, `requires_approval`, `max_iterations` — see `lib/phronomy/graph/compiled_graph.rb`, `lib/phronomy/agent/base.rb` |
+| **phronomy** | Intervention points, iteration limits, approval gates | ✅ `wait_state`/`send_event`, `requires_approval`, `max_iterations` — see `lib/phronomy/workflow.rb`, `lib/phronomy/agent/base.rb` |
 | **phronomy** | Built-in guardrails (PII, prompt injection) | ❌ Not implemented — **planned (Feature A)** |
 | Application | Concrete guardrail logic, approval workflows | Application responsibility |
 
@@ -82,7 +82,7 @@ cannot be delegated to the LLM must be enforced by phronomy or the application l
 | Layer | Responsibility | Status |
 |---|---|---|
 | LLM | Chain-of-thought generation | Prompt-dependent |
-| **phronomy** | Processing step recording via Graph and Tracing | ✅ Partial — `StateGraph`, `Tracing` |
+| **phronomy** | Processing step recording via Graph and Tracing | ✅ Partial — `Workflow`/`WorkflowRunner`, `Tracing` |
 | Application | Explanation UI, CoT prompt design | Application responsibility |
 
 **Planned work:** None in this iteration.
@@ -184,8 +184,8 @@ attributed to users or sessions, which is a requirement for accountability under
 NIST AI RMF 3.4.
 
 **Design:**
-- `Agent::Base#invoke` and `CompiledGraph#invoke` already accept `config: {}` — see
-  `lib/phronomy/agent/base.rb:367` and `lib/phronomy/graph/compiled_graph.rb`.
+- `Agent::Base#invoke` and `WorkflowRunner#invoke` already accept `config: {}` — see
+  `lib/phronomy/agent/base.rb` and `lib/phronomy/graph/workflow_runner.rb`.
 - Add two new optional keys to `config:`:
   - `user_id:` (String | nil) — caller identity
   - `session_id:` (String | nil) — session / request identity

data/lib/phronomy/actor.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Lightweight synchronous actor backed by a dedicated +Thread+ and a +Queue+.
+  #
+  # A caller submits work via {#call}, which blocks until the actor's thread
+  # finishes executing the block and then returns the result (or re-raises any
+  # exception that occurred inside the actor).
+  #
+  # === Reentrant safety
+  #
+  # If {#call} is invoked from within the actor's own thread (i.e. from inside
+  # a block that is already executing on this actor), the block is executed
+  # directly in the current thread instead of being pushed onto the queue.
+  # This prevents deadlocks in deeply nested call paths without requiring
+  # callers to track whether they are already "inside" the actor.
+  #
+  # === Usage
+  #
+  #   actor = Phronomy::Actor.new
+  #   result = actor.call { expensive_operation() }   # blocks caller; runs on actor thread
+  #   actor.stop                                       # graceful shutdown
+  class Actor
+    def initialize
+      @queue = Queue.new
+      @thread = Thread.new do
+        loop do
+          task = @queue.pop
+          break if task == :stop
+          task.call
+        end
+      end
+    end
+
+    # Run +block+ on the actor's thread and return its result.
+    #
+    # If the current thread is already the actor's thread (reentrant call),
+    # the block is executed inline to prevent deadlocks.
+    #
+    # Any exception raised inside the block is captured and re-raised in the
+    # calling thread.
+    #
+    # @yield block to execute on the actor's thread
+    # @return the return value of the block
+    def call(&block)
+      return block.call if Thread.current == @thread
+
+      done = Queue.new
+      @queue.push(-> {
+        begin
+          done.push([true, block.call])
+        rescue => e
+          done.push([false, e])
+        end
+      })
+      success, value = done.pop
+      raise value unless success
+      value
+    end
+
+    # Send a +:stop+ sentinel to gracefully terminate the actor's thread.
+    # Pending tasks already in the queue will still be processed before
+    # the thread exits.
+    def stop
+      @queue.push(:stop)
+    end
+  end
+end

data/lib/phronomy/agent/base.rb

@@ -412,21 +412,8 @@ module Phronomy
       #   result = MyAgent.new.invoke("What is Ruby?")
       #   puts result[:output]
       def invoke(input, config: {})
-        policy = self.class._retry_policy
-        attempt = 0
-        begin
-          invoke_once(input, config: config)
-        rescue Phronomy::GuardrailError
-          raise
-        rescue
-          if policy && attempt < policy[:times]
-            wait = compute_agent_retry_wait(policy[:wait], policy[:base], attempt)
-            self.class._sleep_proc.call(wait) if wait > 0
-            attempt += 1
-            retry
-          end
-          raise
-        end
+        thread_id = config[:thread_id]
+        _run_in_thread_actor(thread_id) { _invoke_impl(input, config: config) }
       end
 
       # Streaming version of #invoke. Yields {Phronomy::Agent::StreamEvent} objects
@@ -446,6 +433,76 @@ module Phronomy
       def stream(input, config: {}, &block)
         return invoke(input, config: config) unless block
 
+        thread_id = config[:thread_id]
+        _run_in_thread_actor(thread_id) { _stream_impl(input, config: config, &block) }
+      rescue => e
+        block&.call(StreamEvent.new(type: :error, payload: {error: e}))
+        raise
+      end
+
+      # Registers a callback that is invoked before executing any tool that has
+      # +requires_approval true+ set. The block receives the tool name (String)
+      # and the arguments Hash, and must return a truthy value to allow execution.
+      # Returning a falsy value causes the tool to return a denial message instead
+      # of executing.
+      #
+      # When no handler is registered, tools with +requires_approval+ execute
+      # without interruption (backward-compatible behaviour).
+      #
+      # @example
+      #   agent = MyAgent.new
+      #   agent.on_approval_required { |tool_name, args| prompt_user(tool_name, args) }
+      # @return [self]
+      def on_approval_required(&block)
+        @approval_handler = block
+        self
+      end
+
+      # Attach a guardrail that validates input before every #invoke call.
+      # @param guardrail [Phronomy::Guardrail::InputGuardrail]
+      def add_input_guardrail(guardrail)
+        @input_guardrails ||= []
+        @input_guardrails << guardrail
+        self
+      end
+
+      # Attach a guardrail that validates output before it is returned.
+      # @param guardrail [Phronomy::Guardrail::OutputGuardrail]
+      def add_output_guardrail(guardrail)
+        @output_guardrails ||= []
+        @output_guardrails << guardrail
+        self
+      end
+
+      # Returns the {Context::ContextVersionCache} for the current thread.
+      # @api private
+      def context_version_cache
+        (Thread.current[:phronomy_context_version_caches] ||= {})[object_id]
+      end
+
+      private
+
+      # Retry loop for #invoke. Separated so that ReactAgent can override #invoke_once.
+      def _invoke_impl(input, config: {})
+        policy = self.class._retry_policy
+        attempt = 0
+        begin
+          invoke_once(input, config: config)
+        rescue Phronomy::GuardrailError
+          raise
+        rescue
+          if policy && attempt < policy[:times]
+            wait = compute_agent_retry_wait(policy[:wait], policy[:base], attempt)
+            self.class._sleep_proc.call(wait) if wait > 0
+            attempt += 1
+            retry
+          end
+          raise
+        end
+      end
+
+      # Streaming implementation for #stream.
+      def _stream_impl(input, config: {}, &block)
         caller_meta = {}
         caller_meta[:user_id] = config[:user_id] if config[:user_id]
         caller_meta[:session_id] = config[:session_id] if config[:session_id]
@@ -528,47 +585,16 @@ module Phronomy
           block.call(StreamEvent.new(type: :done, payload: result))
           [result, usage]
         end
-      rescue => e
-        block&.call(StreamEvent.new(type: :error, payload: {error: e}))
-        raise
       end
 
-      # Registers a callback that is invoked before executing any tool that has
-      # +requires_approval true+ set. The block receives the tool name (String)
-      # and the arguments Hash, and must return a truthy value to allow execution.
-      # Returning a falsy value causes the tool to return a denial message instead
-      # of executing.
-      #
-      # When no handler is registered, tools with +requires_approval+ execute
-      # without interruption (backward-compatible behaviour).
-      #
-      # @example
-      #   agent = MyAgent.new
-      #   agent.on_approval_required { |tool_name, args| prompt_user(tool_name, args) }
-      # @return [self]
-      def on_approval_required(&block)
-        @approval_handler = block
-        self
-      end
+      # Runs +block+ inside the {Phronomy::ThreadActorRegistry} Actor for
+      # +thread_id+. When +thread_id+ is nil the block executes on the calling thread.
+      def _run_in_thread_actor(thread_id, &block)
+        return block.call unless thread_id
 
-      # Attach a guardrail that validates input before every #invoke call.
-      # @param guardrail [Phronomy::Guardrail::InputGuardrail]
-      def add_input_guardrail(guardrail)
-        @input_guardrails ||= []
-        @input_guardrails << guardrail
-        self
+        Phronomy::ThreadActorRegistry.for(thread_id).call(&block)
       end
 
-      # Attach a guardrail that validates output before it is returned.
-      # @param guardrail [Phronomy::Guardrail::OutputGuardrail]
-      def add_output_guardrail(guardrail)
-        @output_guardrails ||= []
-        @output_guardrails << guardrail
-        self
-      end
-
-      private
-
       # Performs a single (non-retried) invocation. Extracted so that #invoke can
       # wrap it in a retry loop without duplicating the LLM interaction logic.
       def invoke_once(input, config: {})
@@ -790,7 +816,9 @@ module Phronomy
           [instruction.to_s, *static_chunks.map { |c| c[:content] }].join("\0")
         )
 
-        cache = (@_context_version_cache ||= Context::ContextVersionCache.new)
+        agent_id = object_id
+        cache = (Thread.current[:phronomy_context_version_caches] ||= {})[agent_id] ||=
+          Context::ContextVersionCache.new
         unless cache.valid?(fingerprint)
           parts = [instruction]
           static_chunks.each do |chunk|

data/lib/phronomy/context/context_version_cache.rb

@@ -2,20 +2,9 @@
 
 module Phronomy
   module Context
-    # Caches the assembled static system prompt text per agent instance.
-    #
-    # The cache is keyed by a SHA-256 fingerprint computed from the agent's
-    # instruction text and the content of all registered static knowledge
-    # sources. When the fingerprint matches the stored value the previously
-    # assembled system_text is reused without re-fetching any sources.
-    #
-    # A cache miss (fingerprint changed or first call) triggers a full
-    # rebuild: instruction + static-knowledge XML tags are concatenated and
-    # the result is stored alongside the new fingerprint.
-    #
-    # Each agent *instance* holds one cache object. The cache persists across
-    # #invoke calls on the same instance, which is the typical usage pattern
-    # for long-running agents.
+    # Caches the assembled static system prompt text keyed by a SHA-256
+    # fingerprint of the agent's instructions + static knowledge content.
+    # Each instance is owned by one thread (stored in +Thread.current+).
     class ContextVersionCache
       # @return [String, nil] last stored fingerprint
       attr_reader :fingerprint
@@ -27,46 +16,34 @@ module Phronomy
       attr_reader :system_tokens
 
       def initialize
-        @mutex = Mutex.new
         @fingerprint = nil
         @system_text = nil
         @system_tokens = 0
       end
 
       # Returns true when the given fingerprint matches the stored one.
-      # The check is performed under a mutex so that a concurrent #update cannot
-      # expose a partially-written state where fingerprint is new but system_text
-      # is still nil (Issue #55).
       #
       # @param fingerprint [String] SHA-256 hex digest to compare
       # @return [Boolean]
       def valid?(fingerprint)
-        @mutex.synchronize do
-          !@fingerprint.nil? && !@system_text.nil? && @fingerprint == fingerprint
-        end
+        !@fingerprint.nil? && !@system_text.nil? && @fingerprint == fingerprint
       end
 
       # Update the cache with a new fingerprint and system text.
-      # All three assignments are performed atomically under a mutex so that
-      # concurrent readers never observe a partial state (Issue #55).
       #
       # @param fingerprint  [String] new SHA-256 hex digest
       # @param system_text  [String] fully assembled system prompt text
       def update(fingerprint:, system_text:)
-        @mutex.synchronize do
-          @fingerprint = fingerprint
-          @system_text = system_text.to_s
-          @system_tokens = TokenEstimator.estimate(@system_text)
-        end
+        @fingerprint = fingerprint
+        @system_text = system_text.to_s
+        @system_tokens = TokenEstimator.estimate(@system_text)
       end
 
       # Clear all cached values (used for testing and forced invalidation).
       def reset
-        @mutex.synchronize do
-          @fingerprint = nil
-          @system_text = nil
-          @system_tokens = 0
-        end
+        @fingerprint = nil
+        @system_text = nil
+        @system_tokens = 0
       end
     end
   end

data/lib/phronomy/memory/conversation_manager.rb

@@ -48,16 +48,6 @@ module Phronomy
         @retrieval = retrieval
         @compression = compression
         @ttl = ttl
-        # Per-thread mutexes allow concurrent saves for different thread_ids while
-        # preventing races (duplicate compaction records) within the same thread_id.
-        @thread_mutexes = {}
-        @thread_mutexes_mutex = Mutex.new
-        # Tracks the monotonically increasing next-seq per thread so that TTL
-        # purges (which reduce raw.length) do not reset the sequence counter.
-        # Protected by a dedicated mutex so concurrent saves for distinct
-        # thread_ids do not race on the shared Hash (Issue #60).
-        @raw_seq_hwm = {}
-        @raw_seq_hwm_mutex = Mutex.new
       end
 
       # Load conversation messages for a thread, applying retrieval selection.
@@ -92,8 +82,8 @@ module Phronomy
       # @param thread_id [String]
       # @param messages  [Array] full conversation history up to this point
       def save(thread_id:, messages:)
-        thread_mutex(thread_id).synchronize do
-          append_new_messages_unlocked(thread_id: thread_id, messages: messages)
+        @storage.with_thread_lock(thread_id: thread_id) do
+          append_new_messages(thread_id: thread_id, messages: messages)
           compress_and_save(thread_id: thread_id, messages: messages)
         end
         @retrieval.index(thread_id: thread_id, messages: messages) if @retrieval.respond_to?(:index)
@@ -135,36 +125,17 @@ module Phronomy
 
       private
 
-      # Returns (or lazily creates) the per-thread mutex for +thread_id+.
-      # The outer @thread_mutexes_mutex protects the hash from concurrent creation.
-      def thread_mutex(thread_id)
-        @thread_mutexes_mutex.synchronize do
-          @thread_mutexes[thread_id] ||= Mutex.new
-        end
-      end
-
       # Append messages that are new since the last save to the raw history.
-      # Must be called while holding the per-thread mutex (via thread_mutex).
+      # Must be called while holding the per-thread lock (via Storage#with_thread_lock).
       # Messages are append-only; existing raw entries are never modified.
       #
-      # Uses a per-thread high-water-mark (HWM) to determine the next seq number.
-      # The HWM is the maximum of:
-      #   - The highest seq stored in the raw store (correct after normal appends)
-      #   - The in-memory HWM (correct after TTL purge empties the raw store)
-      # This prevents seq number collisions when TTL purge reduces raw.length.
-      def append_new_messages_unlocked(thread_id:, messages:)
-        raw = @storage.load_raw(thread_id: thread_id)
-        # Derive the next seq from the raw store's high-water-mark seq when
-        # entries are present. Fall back to the in-memory HWM when the raw
-        # store has been partially or fully purged by TTL expiry.
-        stored_next_seq = raw.any? ? raw.map { |e| e[:seq] }.max + 1 : nil
-        hwm = @raw_seq_hwm_mutex.synchronize { @raw_seq_hwm[thread_id] }
-        next_seq = [stored_next_seq, hwm].compact.max || 0
+      # The next seq number is derived from Storage#next_seq, which owns the
+      # high-water-mark counter. This survives TTL purges because Storage tracks
+      # the HWM independently of the stored raw entries.
+      def append_new_messages(thread_id:, messages:)
+        next_seq = @storage.next_seq(thread_id: thread_id)
         new_messages = messages[next_seq..]
-        if new_messages&.any?
-          @storage.append_raw(thread_id: thread_id, messages: new_messages, starting_seq: next_seq)
-          @raw_seq_hwm_mutex.synchronize { @raw_seq_hwm[thread_id] = next_seq + new_messages.length }
-        end
+        @storage.append_raw(thread_id: thread_id, messages: new_messages, starting_seq: next_seq) if new_messages&.any?
       end
 
       # Apply the configured compression strategy and persist the result.

data/lib/phronomy/memory/retrieval/semantic.rb

@@ -28,7 +28,7 @@ module Phronomy
           @index = {}   # id => message  (insertion-ordered via Ruby Hash)
           @counter = 0
           @max_index_size = max_index_size
-          @mutex = Mutex.new
+          @actor = Phronomy::Actor.new
           @indexed_object_ids = {}  # thread_id => { object_id => true }
         end
 
@@ -43,14 +43,14 @@ module Phronomy
         def index(thread_id:, messages:)
           messages.each do |msg|
             # Fast path: skip already-indexed messages without calling embed.
-            already_indexed = @mutex.synchronize do
+            already_indexed = @actor.call do
               (@indexed_object_ids[thread_id] ||= {})[msg.object_id]
             end
             next if already_indexed
 
             embedding = @embeddings.embed(msg.content.to_s)
-            @mutex.synchronize do
-              # Re-check inside lock to handle concurrent callers for the same thread.
+            @actor.call do
+              # Re-check inside Actor to handle concurrent callers for the same thread.
               indexed = (@indexed_object_ids[thread_id] ||= {})
               next if indexed[msg.object_id]
 
@@ -68,7 +68,7 @@ module Phronomy
         #
         # @param thread_id [String]
         def clear_index(thread_id:)
-          @mutex.synchronize do
+          @actor.call do
             ids = @index.keys.select { |id| id.start_with?("#{thread_id}:") }
             ids.each do |id|
               @index.delete(id)
@@ -87,7 +87,7 @@ module Phronomy
         def select(messages, query: nil, thread_id: nil)
           if query && !query.strip.empty?
             query_embedding = @embeddings.embed(query)
-            results = @mutex.synchronize { @store.search(query_embedding: query_embedding, k: @k * 3) }
+            results = @actor.call { @store.search(query_embedding: query_embedding, k: @k * 3) }
             results
               .select { |r| thread_id.nil? || r[:metadata][:thread_id] == thread_id }
               .first(@k)
@@ -100,7 +100,7 @@ module Phronomy
         private
 
         # Evicts the oldest index entry to enforce max_index_size.
-        # Must be called inside @mutex.synchronize.
+        # Must be called inside the Actor.
         def evict_oldest!
           oldest_id = @index.keys.first
           return unless oldest_id