phronomy 0.1.3 → 0.2.0

data/lib/phronomy/agent/react_agent.rb

@@ -5,7 +5,11 @@ module Phronomy
     # ReAct pattern (Reasoning + Acting) agent.
     # Repeats the LLM <-> Tool loop until no more tool calls are made.
     class ReactAgent < Base
-      def invoke(input, config: {})
+      private
+
+      # Performs a single (non-retried) ReAct invocation.
+      # Overrides Base#invoke_once so that Base#invoke's retry loop is inherited.
+      def invoke_once(input, config: {})
         caller_meta = {}
         caller_meta[:user_id] = config[:user_id] if config[:user_id]
         caller_meta[:session_id] = config[:session_id] if config[:session_id]
@@ -43,7 +47,11 @@ module Phronomy
 
           save_to_memory(memory, thread_id: thread_id, messages: messages) if memory && thread_id
 
-          output = messages.last&.content
+          # Fall back to the last message that carries non-nil content. This
+          # guards against the case where the final message is a tool-call or
+          # tool-result message (content == nil) when max_iterations is
+          # exhausted before the model produces a text reply.
+          output = messages.reverse.find { |m| m.content && !m.content.empty? }&.content
 
           # Run output guardrails before returning to the caller.
           run_output_guardrails!(output)
@@ -53,6 +61,8 @@ module Phronomy
         end
       end
 
+      public
+
       # Streaming version of #invoke for the ReAct loop.
       # Yields {Phronomy::Agent::StreamEvent} events while the LLM-tool loop runs.
       #
@@ -63,42 +73,50 @@ module Phronomy
       def stream(input, config: {}, &block)
         return invoke(input, config: config) unless block
 
-        run_input_guardrails!(input)
+        caller_meta = {}
+        caller_meta[:user_id] = config[:user_id] if config[:user_id]
+        caller_meta[:session_id] = config[:session_id] if config[:session_id]
 
-        memory = config[:memory]
-        thread_id = config[:thread_id]
-        max_iter = self.class.max_iterations
+        trace("agent.invoke", input: input, **caller_meta) do |_span|
+          run_input_guardrails!(input)
 
-        initial_messages = if memory && thread_id
-          load_from_memory(memory, thread_id: thread_id, query: extract_message(input))
-        else
-          []
-        end
+          memory = config[:memory]
+          thread_id = config[:thread_id]
+          max_iter = self.class.max_iterations
 
-        messages = initial_messages.dup
-        user_asked = false
-        total_usage = Phronomy::TokenUsage.zero
-        iterations_exhausted = true
-
-        max_iter.times do
-          response = stream_step(messages, input, user_asked: user_asked, config: config, &block)
-          user_asked = true
-          messages = response[:messages]
-          total_usage += response[:usage]
-          if response[:done]
-            iterations_exhausted = false
-            break
+          initial_messages = if memory && thread_id
+            load_from_memory(memory, thread_id: thread_id, query: extract_message(input))
+          else
+            []
           end
-        end
 
-        save_to_memory(memory, thread_id: thread_id, messages: messages) if memory && thread_id
+          messages = initial_messages.dup
+          user_asked = false
+          total_usage = Phronomy::TokenUsage.zero
+          iterations_exhausted = true
+
+          max_iter.times do
+            response = stream_step(messages, input, user_asked: user_asked, config: config, &block)
+            user_asked = true
+            messages = response[:messages]
+            total_usage += response[:usage]
+            if response[:done]
+              iterations_exhausted = false
+              break
+            end
+          end
 
-        output = messages.last&.content
-        run_output_guardrails!(output)
+          save_to_memory(memory, thread_id: thread_id, messages: messages) if memory && thread_id
 
-        result = {output: output, messages: messages, usage: total_usage, iterations_exhausted: iterations_exhausted}
-        block.call(StreamEvent.new(type: :done, payload: result))
-        result
+          # Fall back to the last message that carries non-nil content (same as
+          # the non-streaming path above).
+          output = messages.reverse.find { |m| m.content && !m.content.empty? }&.content
+          run_output_guardrails!(output)
+
+          result = {output: output, messages: messages, usage: total_usage, iterations_exhausted: iterations_exhausted}
+          block.call(StreamEvent.new(type: :done, payload: result))
+          [result, total_usage]
+        end
       rescue => e
         block&.call(StreamEvent.new(type: :error, payload: {error: e}))
         raise
@@ -136,8 +154,8 @@ module Phronomy
         chat = build_chat
         messages.each { |m| chat.add_message(m) }
 
-        chat.on_tool_call { |tc| block.call(StreamEvent.new(type: :tool_call, payload: {tool_call: tc})) }
-        chat.on_tool_result { |tr| block.call(StreamEvent.new(type: :tool_result, payload: {tool_result: tr})) }
+        chat.before_tool_call { |tc| block.call(StreamEvent.new(type: :tool_call, payload: {tool_call: tc})) }
+        chat.after_tool_result { |tr| block.call(StreamEvent.new(type: :tool_result, payload: {tool_result: tr})) }
 
         # Run before_completion hooks before each LLM call in the streaming loop.
         run_before_completion_hooks!(chat, config)

data/lib/phronomy/context/assembler.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "cgi"
+
 module Phronomy
   module Context
     # Assembler collects all four context regions and produces the final
@@ -34,7 +36,7 @@ module Phronomy
       # @param trusted [Boolean]
       # @return [String]
       def self.xml_tag(text, type:, trusted: false)
-        "<context type=\"#{type}\" trusted=\"#{trusted}\">\n#{text}\n</context>"
+        "<context type=\"#{CGI.escapeHTML(type.to_s)}\" trusted=\"#{trusted}\">\n#{CGI.escapeHTML(text.to_s)}\n</context>"
       end
 
       # @param budget [Phronomy::Context::TokenBudget, nil]
@@ -104,8 +106,8 @@ module Phronomy
       private
 
       def xml_context_tag(chunk)
-        src_attr = chunk[:source] ? " source=\"#{chunk[:source]}\"" : ""
-        "<context type=\"#{chunk[:type]}\"#{src_attr} trusted=\"#{chunk[:trusted]}\">\n#{chunk[:text]}\n</context>"
+        src_attr = chunk[:source] ? " source=\"#{CGI.escapeHTML(chunk[:source].to_s)}\"" : ""
+        "<context type=\"#{CGI.escapeHTML(chunk[:type].to_s)}\"#{src_attr} trusted=\"#{chunk[:trusted]}\">\n#{CGI.escapeHTML(chunk[:text].to_s)}\n</context>"
       end
 
       def trim_messages_to_budget(messages, system_text)
@@ -122,6 +124,12 @@ module Phronomy
           accumulated += tokens
           result.push(msg)
         end
+
+        if result.empty? && messages.any?
+          warn "[Phronomy::Assembler] All #{messages.length} conversation message(s) dropped: " \
+               "token budget exhausted by system context (budget=#{@budget.context_window}, used_by_system=#{used})"
+        end
+
         result.reverse
       end
     end

data/lib/phronomy/context/compaction_context.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Phronomy
   module Context
     # Context object passed to the +on_compact+ callback registered on an agent.
@@ -103,7 +101,7 @@ module Phronomy
         end
 
         remaining = (@message_elements[(last_idx + 1)..] || []).map { |e| e[:message] }
-        summary_msg = OpenStruct.new(role: :system, content: summary_text)
+        summary_msg = RubyLLM::Message.new(role: :system, content: summary_text)
         @result_messages = [summary_msg] + remaining
       end
     end

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,7 +16,9 @@ module Phronomy
       attr_reader :system_tokens
 
       def initialize
-        reset
+        @fingerprint = nil
+        @system_text = nil
+        @system_tokens = 0
       end
 
       # Returns true when the given fingerprint matches the stored one.
@@ -35,7 +26,7 @@ module Phronomy
       # @param fingerprint [String] SHA-256 hex digest to compare
       # @return [Boolean]
       def valid?(fingerprint)
-        !@fingerprint.nil? && @fingerprint == fingerprint
+        !@fingerprint.nil? && !@system_text.nil? && @fingerprint == fingerprint
       end
 
       # Update the cache with a new fingerprint and system text.

data/lib/phronomy/eval/runner.rb

@@ -22,24 +22,52 @@ module Phronomy
         @scorer = scorer
       end
 
-      # @param dataset  [Dataset]  collection of EvalCase objects
-      # @param callable [#call]    accepts a single String argument
+      # @param dataset     [Dataset]  collection of EvalCase objects
+      # @param callable    [#call]    accepts a single String argument
+      # @param concurrency [Integer]  number of parallel threads (default: 1, sequential)
       # @return [Array<EvalResult>]
-      def run(dataset, callable)
-        dataset.map do |eval_case|
-          t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
-          result = callable.call(eval_case.input)
-          latency_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - t0
+      def run(dataset, callable, concurrency: 1)
+        cases = dataset.to_a
+        return cases.map { |eval_case| run_one(eval_case, callable) } if concurrency <= 1
 
-          actual, usage = extract(result)
-          score, score_error = score_safely(@scorer, actual: actual, expected: eval_case.expected, input: eval_case.input)
-
-          EvalResult.new(eval_case: eval_case, actual: actual, score: score, usage: usage, latency_ms: latency_ms, error: score_error)
+        # Run cases in slices of +concurrency+ threads. Each slice is joined
+        # before the next starts, bounding peak thread count to +concurrency+.
+        # Writing to pre-allocated slots (one per thread) is safe because each
+        # thread writes to a unique index and all threads in a slice are joined
+        # before the next slice begins.
+        # Exceptions in worker threads are collected and re-raised after all
+        # threads in the slice are joined, preventing orphaned threads.
+        results = Array.new(cases.length)
+        cases.each_with_index.each_slice(concurrency) do |batch|
+          errors = []
+          errors_mu = Mutex.new
+          threads = batch.map do |eval_case, i|
+            Thread.new do
+              results[i] = run_one(eval_case, callable)
+            rescue => e
+              errors_mu.synchronize { errors << e }
+            end
+          end
+          threads.each(&:join)
+          raise errors.first if errors.any?
         end
+        results
       end
 
       private
 
+      # Evaluate a single EvalCase with the given callable and return an EvalResult.
+      def run_one(eval_case, callable)
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+        result = callable.call(eval_case.input)
+        latency_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - t0
+
+        actual, usage = extract(result)
+        score, score_error = score_safely(@scorer, actual: actual, expected: eval_case.expected, input: eval_case.input)
+
+        EvalResult.new(eval_case: eval_case, actual: actual, score: score, usage: usage, latency_ms: latency_ms, error: score_error)
+      end
+
       # Normalises the callable's return value into [actual_string, usage_or_nil].
       def extract(result)
         if result.is_a?(Hash)

data/lib/phronomy/guardrail/builtin/pii_pattern_detector.rb

@@ -25,14 +25,20 @@ module Phronomy
         # Recognised PII categories and their detection patterns.
         PATTERNS = {
           # Japanese My Number: 12 consecutive or grouped digits (4-4-4).
+          # Matched candidates are additionally validated with the official check-digit
+          # algorithm (JIS X 0076) to eliminate false positives from arbitrary 12-digit strings.
           my_number: {
             pattern: /(?<!\d)(?<!\d[- ])\d{4}[- ]?\d{4}[- ]?\d{4}(?![- ]?\d)/,
-            label: "My Number"
+            label: "My Number",
+            validate_my_number: true
           },
           # Credit / debit card: 16 digits, optionally separated by spaces or hyphens.
+          # Matched candidates are additionally validated with the Luhn algorithm
+          # to eliminate false positives from arbitrary 16-digit sequences.
           credit_card: {
             pattern: /\b(?:\d{4}[- ]?){3}\d{4}\b/,
-            label: "credit card number"
+            label: "credit card number",
+            validate_luhn: true
           },
           # Email address (simplified RFC 5322).
           email: {
@@ -64,9 +70,47 @@ module Phronomy
         def check(value)
           text = value.to_s
           @active_patterns.each do |entry|
-            fail!("PII detected in input: #{entry[:label]}") if text.match?(entry[:pattern])
+            detected = if entry[:validate_luhn]
+              # Scan for all candidates then filter by Luhn check-digit validation.
+              # This avoids false positives on arbitrary 16-digit strings (e.g. internal IDs).
+              text.scan(entry[:pattern]).any? { |m| luhn_valid?(m.gsub(/[- ]/, "")) }
+            elsif entry[:validate_my_number]
+              # Scan for all candidates then apply the JIS X 0076 check-digit algorithm.
+              # This avoids false positives on arbitrary 12-digit strings.
+              text.scan(entry[:pattern]).any? { |m| my_number_valid?(m.gsub(/[- ]/, "")) }
+            else
+              text.match?(entry[:pattern])
+            end
+            fail!("PII detected in input: #{entry[:label]}") if detected
           end
         end
+
+        private
+
+        # Returns true when +digits+ (a 12-character string of decimal digits) satisfies
+        # the Japanese My Number check-digit algorithm defined in JIS X 0076.
+        # The check digit is the 12th digit.
+        def my_number_valid?(digits)
+          weights = [6, 5, 4, 3, 2, 7, 6, 5, 4, 3, 2]
+          total = weights.each_with_index.sum { |w, i| w * digits[i].to_i }
+          remainder = total % 11
+          check = (remainder <= 1) ? 0 : 11 - remainder
+          check == digits[11].to_i
+        end
+
+        # Returns true when +digits+ (a string of decimal digits) satisfies the
+        # Luhn check-digit algorithm used by payment card networks.
+        def luhn_valid?(digits)
+          digits.chars.reverse.each_with_index.sum do |d, i|
+            n = d.to_i
+            if i.odd?
+              doubled = n * 2
+              (doubled > 9) ? (doubled - 9) : doubled
+            else
+              n
+            end
+          end % 10 == 0
+        end
       end
     end
   end

data/lib/phronomy/memory/compression/summary.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Phronomy
   module Memory
     module Compression
@@ -64,6 +62,9 @@ module Phronomy
           else
             {messages: messages, compaction: nil}
           end
+        rescue => e
+          warn "[Phronomy] Compression failed (#{e.class}: #{e.message}); saving without compaction."
+          {messages: messages, compaction: nil}
         end
 
         private
@@ -98,7 +99,7 @@ module Phronomy
             #{text}
             </context>
           CONTEXT
-          OpenStruct.new(role: :system, content: content)
+          RubyLLM::Message.new(role: :system, content: content)
         end
       end
     end

data/lib/phronomy/memory/compression/tool_output_pruner.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Phronomy
   module Memory
     module Compression
@@ -25,6 +23,11 @@ module Phronomy
       class ToolOutputPruner < Base
         TRUNCATION_NOTE = "\n[... output truncated ...]"
 
+        # Internal value object for cloned messages.
+        # Uses Struct (not OpenStruct) so that unknown attribute access raises NoMethodError.
+        ClonedMessage = Struct.new(:role, :content, :tool_calls, :model_id, keyword_init: true)
+        private_constant :ClonedMessage
+
         # @param max_chars [Integer] maximum character length for tool-result content
         def initialize(max_chars: 4000)
           @max_chars = max_chars
@@ -51,10 +54,12 @@ module Phronomy
         private
 
         def clone_message(original, new_content)
-          attrs = {role: original.role, content: new_content}
-          attrs[:tool_calls] = original.tool_calls if original.respond_to?(:tool_calls)
-          attrs[:model_id] = original.model_id if original.respond_to?(:model_id)
-          OpenStruct.new(attrs)
+          ClonedMessage.new(
+            role: original.role,
+            content: new_content,
+            tool_calls: (original.tool_calls if original.respond_to?(:tool_calls)),
+            model_id: (original.model_id if original.respond_to?(:model_id))
+          )
         end
       end
     end

data/lib/phronomy/memory/conversation_manager.rb

@@ -48,7 +48,6 @@ module Phronomy
         @retrieval = retrieval
         @compression = compression
         @ttl = ttl
-        @append_mutex = Mutex.new
       end
 
       # Load conversation messages for a thread, applying retrieval selection.
@@ -83,8 +82,10 @@ module Phronomy
       # @param thread_id [String]
       # @param messages  [Array] full conversation history up to this point
       def save(thread_id:, messages:)
-        append_new_messages(thread_id: thread_id, messages: messages)
-        compress_and_save(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)
       end
 
@@ -125,21 +126,24 @@ module Phronomy
       private
 
       # Append messages that are new since the last save to the raw history.
+      # Must be called while holding the per-thread lock (via Storage#with_thread_lock).
       # Messages are append-only; existing raw entries are never modified.
+      #
+      # 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:)
-        # Synchronize load + append to prevent seq number collisions when two
-        # threads save the same thread_id concurrently.
-        @append_mutex.synchronize do
-          raw = @storage.load_raw(thread_id: thread_id)
-          starting_seq = raw.length
-          new_messages = messages[starting_seq..]
-          @storage.append_raw(thread_id: thread_id, messages: new_messages, starting_seq: starting_seq) if new_messages&.any?
-        end
+        next_seq = @storage.next_seq(thread_id: thread_id)
+        new_messages = messages[next_seq..]
+        @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.
       # When no strategy is configured, saves messages directly to the legacy store.
       # When compression fires, also persists the compaction record.
+      # If the compression strategy raises (e.g. LLM timeout), we fall back to
+      # saving the messages without compaction so the conversation is never lost
+      # due to a transient summarization failure (Issue #58).
       def compress_and_save(thread_id:, messages:)
         unless @compression
           @storage.save(thread_id: thread_id, messages: messages)
@@ -151,11 +155,16 @@ module Phronomy
         all_raw = @storage.load_raw(thread_id: thread_id)
         uncompacted = all_raw.select { |r| r[:seq] >= uncompacted_start_seq }.map { |r| r[:message] }
 
-        result = @compression.compress(
-          thread_id: thread_id,
-          messages: uncompacted,
-          seq_offset: uncompacted_start_seq
-        )
+        result = begin
+          @compression.compress(
+            thread_id: thread_id,
+            messages: uncompacted,
+            seq_offset: uncompacted_start_seq
+          )
+        rescue => e
+          warn "[Phronomy] Compression failed (#{e.class}: #{e.message}); saving without compaction."
+          {messages: messages, compaction: nil}
+        end
 
         if result[:compaction]
           @storage.save_compaction(

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

@@ -28,22 +28,37 @@ 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
 
         # Index a new batch of messages so they are searchable on future #select calls.
         # Called by ConversationManager#save.
         #
+        # Messages are deduplicated by object identity: if a message object has already
+        # been indexed for the given thread_id, it is skipped (no duplicate embed call).
+        #
         # @param thread_id [String]
         # @param messages  [Array]
         def index(thread_id:, messages:)
           messages.each do |msg|
+            # Fast path: skip already-indexed messages without calling embed.
+            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
+            @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]
+
               id = "#{thread_id}:#{@counter}"
               @counter += 1
               @store.add(id: id, embedding: embedding, metadata: {thread_id: thread_id, message: msg})
               @index[id] = msg
+              indexed[msg.object_id] = true
               evict_oldest! if @max_index_size && @index.size > @max_index_size
             end
           end
@@ -53,12 +68,13 @@ 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)
               @store.remove(id: id)
             end
+            @indexed_object_ids.delete(thread_id)
           end
         end
 
@@ -71,7 +87,7 @@ module Phronomy
         def select(messages, query: nil, thread_id: nil)
           if query && !query.strip.empty?
             query_embedding = @embeddings.embed(query)
-            results = @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)
@@ -84,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

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

@@ -75,7 +75,7 @@ module Phronomy
               @model_class.create!(
                 thread_id: thread_id,
                 role: msg.role.to_s,
-                content: msg.content.to_s,
+                content: msg.content,
                 tool_calls_json: serialize_tool_calls(msg),
                 model_id: (msg.model_id if msg.respond_to?(:model_id))
               )
@@ -100,15 +100,17 @@ module Phronomy
         def append_raw(thread_id:, messages:, starting_seq:)
           return unless @raw_model_class
 
-          messages.each_with_index do |msg, i|
-            @raw_model_class.create!(
-              thread_id: thread_id,
-              seq: starting_seq + i,
-              role: msg.role.to_s,
-              content: msg.content.to_s,
-              tool_calls_json: serialize_tool_calls(msg),
-              model_id: (msg.model_id if msg.respond_to?(:model_id))
-            )
+          @raw_model_class.transaction do
+            messages.each_with_index do |msg, i|
+              @raw_model_class.create!(
+                thread_id: thread_id,
+                seq: starting_seq + i,
+                role: msg.role.to_s,
+                content: msg.content,
+                tool_calls_json: serialize_tool_calls(msg),
+                model_id: (msg.model_id if msg.respond_to?(:model_id))
+              )
+            end
           end
         end
 
@@ -168,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