phronomy 0.22.0 → 0.23.0

data/lib/phronomy/agent/journal_record.rb

@@ -13,7 +13,7 @@ module Phronomy
     class JournalRecord
       ATTRIBUTES = %i[
         record_id agent_id sequence execution_id llm_call_id kind channel role content_ref
-        parent_id causation_id correlation_id visibility context_generation
+        parent_id causation_id visibility context_generation
         context_candidate occurred_at metadata
       ].freeze
 
@@ -31,7 +31,6 @@ module Phronomy
         content_ref: nil,
         parent_id: nil,
         causation_id: nil,
-        correlation_id: nil,
         visibility: :agent,
         context_generation: 0,
         context_candidate: false,
@@ -52,14 +51,28 @@ module Phronomy
         self.class.from_h(to_h.merge("sequence" => sequence))
       end
 
+      # Current semantic payload representation. Persistence format identity and
+      # compatibility validation are owned by Persistence::DurableCodec.
       def to_h
         ATTRIBUTES.to_h { |name| [name.to_s, public_send(name)] }
       end
 
+      # Historical durable fields are not accepted here. Explicit migration must
+      # convert them to the current semantic payload first.
       def self.from_h(hash)
+        source = hash.to_h { |key, value| [key.to_s, value] }
+        expected = ATTRIBUTES.map(&:to_s).sort
+        actual = source.keys.sort
+        unless actual == expected
+          missing = expected - actual
+          unknown = actual - expected
+          raise ArgumentError,
+            "JournalRecord payload schema mismatch: " \
+            "missing=#{missing.inspect}, unknown=#{unknown.inspect}"
+        end
+
         new(**ATTRIBUTES.to_h do |name|
-          key = hash.key?(name.to_s) ? name.to_s : name
-          [name, hash[key]]
+          [name, source.fetch(name.to_s)]
         end)
       end
     end

data/lib/phronomy/agent/llm_input_build_context.rb

@@ -5,7 +5,7 @@ module Phronomy
     # Immutable metadata passed to before_llm_input hooks. Runtime objects such
     # as RubyLLM::Chat, messages and the mutable Agent instance are not exposed.
     LLMInputBuildContext = Data.define(
-      :agent_id, :agent_definition_id, :definition_version,
+      :agent_id, :agent_definition_id, :agent_definition_version,
       :config, :call_sequence
     ) do
       def initialize(**values)

data/lib/phronomy/agent/llm_input_manifest.rb

@@ -2,19 +2,98 @@
 
 module Phronomy
   module Agent
+    # ContentStore-backed durable codec boundary for one Provider input manifest.
+    # It is intentionally separate from Persistence::DurableRecord.
     class LLMInputManifest
-      VERSION = 1
+      VERSION = "0.1"
       CALL_MODES = %i[ask complete].freeze
+      SEGMENT_DELIVERIES = %w[ask_argument chat_message].freeze
 
       Segment = Data.define(
         :position, :category, :role, :content_ref, :delivery,
         :tool_call_id, :metadata
       ) do
         def initialize(**values)
+          delivery = values[:delivery]
+          if delivery.nil? || !SEGMENT_DELIVERIES.include?(delivery.to_s)
+            raise ArgumentError, "unknown Segment delivery: #{delivery.inspect}"
+          end
           super(**values.merge(metadata: Immutable.copy(values[:metadata] || {})))
           freeze
         end
 
+        def self.from_h(hash)
+          source = LLMInputManifest.send(
+            :strict_source!,
+            hash,
+            required: %w[position category content_ref delivery metadata],
+            optional: %w[role tool_call_id],
+            label: "LLMInputManifest segment"
+          )
+          label = "LLMInputManifest segment"
+          position = LLMInputManifest.send(
+            :require_nonnegative_integer_field!,
+            source,
+            "position",
+            label: label
+          )
+          category = LLMInputManifest.send(
+            :require_nonempty_string_field!,
+            source,
+            "category",
+            label: label
+          )
+          role = LLMInputManifest.send(
+            :require_optional_string_field!,
+            source,
+            "role",
+            label: label
+          )
+          content_ref = LLMInputManifest.send(
+            :require_nonempty_string_field!,
+            source,
+            "content_ref",
+            label: label
+          )
+          delivery = LLMInputManifest.send(
+            :require_nonempty_string_field!,
+            source,
+            "delivery",
+            label: label
+          )
+          unless SEGMENT_DELIVERIES.include?(delivery)
+            raise Phronomy::Persistence::SerializationError,
+              "LLMInputManifest segment delivery must be one of #{SEGMENT_DELIVERIES.inspect}, got #{delivery.inspect}"
+          end
+          tool_call_id = LLMInputManifest.send(
+            :require_optional_string_field!,
+            source,
+            "tool_call_id",
+            label: label
+          )
+          metadata = LLMInputManifest.send(
+            :require_hash_field!,
+            source,
+            "metadata",
+            label: label
+          )
+
+          new(
+            position: position,
+            category: category.to_sym,
+            role: role&.to_sym,
+            content_ref: content_ref,
+            delivery: delivery.to_sym,
+            tool_call_id: tool_call_id,
+            metadata: metadata
+          )
+        rescue Phronomy::Persistence::SerializationError
+          raise
+        rescue => error
+          raise Phronomy::Persistence::SerializationError,
+            "invalid LLMInputManifest segment: #{error.class}: #{error.message}"
+        end
+
         def to_h
           {
             "position" => position,
@@ -28,6 +107,15 @@ module Phronomy
         end
       end
 
+      REQUIRED_KEYS = %w[
+        version call_sequence call_mode assembly_policy_version segments
+        model_config_ref
+      ].freeze
+      OPTIONAL_KEYS = %w[
+        tool_definitions_ref response_schema_ref ruby_llm_version
+        adapter_name adapter_version
+      ].freeze
+
       attr_reader :version, :call_sequence, :call_mode,
         :assembly_policy_version, :segments,
         :model_config_ref, :tool_definitions_ref, :response_schema_ref,
@@ -46,7 +134,7 @@ module Phronomy
         adapter_version: nil,
         version: VERSION
       )
-        @version = Integer(version)
+        @version = String(version).freeze
         @call_sequence = Integer(call_sequence)
         @call_mode = call_mode.to_sym
         @assembly_policy_version = Integer(assembly_policy_version)
@@ -61,6 +149,93 @@ module Phronomy
         freeze
       end
 
+      # Current-format-only durable decoder. Historical format conversion is an
+      # explicit migration operation and is never attempted here. Unlike the
+      # Ruby construction API, this decoder never coerces durable field types.
+      def self.from_h(hash)
+        source = strict_source!(
+          hash,
+          required: REQUIRED_KEYS,
+          optional: OPTIONAL_KEYS,
+          label: "LLMInputManifest"
+        )
+        label = "LLMInputManifest"
+        version = source.fetch("version")
+        unless version.is_a?(String) && version == VERSION
+          raise Phronomy::Persistence::SerializationError,
+            "unsupported LLMInputManifest version: #{version.inspect}; " \
+            "current version is #{VERSION.inspect}"
+        end
+
+        call_sequence = require_positive_integer_field!(
+          source,
+          "call_sequence",
+          label: label
+        )
+        call_mode = require_enum_string_field!(
+          source,
+          "call_mode",
+          CALL_MODES.map(&:to_s),
+          label: label
+        )
+        assembly_policy_version = require_integer_field!(
+          source,
+          "assembly_policy_version",
+          label: label
+        )
+        segments = require_array_field!(source, "segments", label: label)
+          .map { |segment| Segment.from_h(segment) }
+        model_config_ref = require_nonempty_string_field!(
+          source,
+          "model_config_ref",
+          label: label
+        )
+        tool_definitions_ref = require_optional_string_field!(
+          source,
+          "tool_definitions_ref",
+          label: label
+        )
+        response_schema_ref = require_optional_string_field!(
+          source,
+          "response_schema_ref",
+          label: label
+        )
+        ruby_llm_version = require_optional_string_field!(
+          source,
+          "ruby_llm_version",
+          label: label
+        )
+        adapter_name = require_optional_string_field!(
+          source,
+          "adapter_name",
+          label: label
+        )
+        adapter_version = require_optional_string_field!(
+          source,
+          "adapter_version",
+          label: label
+        )
+
+        new(
+          version: version,
+          call_sequence: call_sequence,
+          call_mode: call_mode.to_sym,
+          assembly_policy_version: assembly_policy_version,
+          segments: segments,
+          model_config_ref: model_config_ref,
+          tool_definitions_ref: tool_definitions_ref,
+          response_schema_ref: response_schema_ref,
+          ruby_llm_version: ruby_llm_version,
+          adapter_name: adapter_name,
+          adapter_version: adapter_version
+        )
+      rescue Phronomy::Persistence::SerializationError
+        raise
+      rescue => error
+        raise Phronomy::Persistence::SerializationError,
+          "invalid LLMInputManifest: #{error.class}: #{error.message}"
+      end
+
       def referenced_content_refs
         ([model_config_ref, tool_definitions_ref, response_schema_ref] +
           segments.map(&:content_ref)).compact.uniq.freeze
@@ -82,9 +257,109 @@ module Phronomy
         }.compact
       end
 
+      class << self
+        private
+
+        def strict_source!(hash, required:, optional:, label:)
+          unless hash.is_a?(Hash)
+            raise Phronomy::Persistence::SerializationError,
+              "#{label} must be a Hash"
+          end
+          unless hash.keys.all? { |key| key.is_a?(String) }
+            raise Phronomy::Persistence::SerializationError,
+              "#{label} keys must all be String"
+          end
+
+          actual = hash.keys
+          missing = required - actual
+          unknown = actual - (required + optional)
+          unless missing.empty? && unknown.empty?
+            details = []
+            details << "missing=#{missing.inspect}" unless missing.empty?
+            details << "unknown=#{unknown.inspect}" unless unknown.empty?
+            raise Phronomy::Persistence::SerializationError,
+              "#{label} schema mismatch (#{details.join(", ")})"
+          end
+          Phronomy::CanonicalJSON.dump(hash)
+          hash
+        rescue ArgumentError => error
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} is not canonical JSON compatible: #{error.message}"
+        end
+
+        def require_integer_field!(hash, key, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(Integer)
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be an Integer"
+        end
+
+        def require_positive_integer_field!(hash, key, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(Integer) && value.positive?
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be a positive Integer"
+        end
+
+        def require_nonnegative_integer_field!(hash, key, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(Integer) && value >= 0
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be a non-negative Integer"
+        end
+
+        def require_nonempty_string_field!(hash, key, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(String) && !value.empty?
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be a non-empty String"
+        end
+
+        def require_optional_string_field!(hash, key, label:)
+          value = hash[key]
+          return value if value.nil? || value.is_a?(String)
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be a String or nil"
+        end
+
+        def require_enum_string_field!(hash, key, allowed, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(String) && allowed.include?(value)
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be one of #{allowed.inspect}"
+        end
+
+        def require_array_field!(hash, key, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(Array)
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be an Array"
+        end
+
+        def require_hash_field!(hash, key, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(Hash)
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be a Hash"
+        end
+      end
+
       private
 
       def validate!
+        unless version == VERSION
+          raise Phronomy::ConfigurationError,
+            "unsupported LLMInputManifest version: #{version.inspect}; " \
+            "current version is #{VERSION.inspect}"
+        end
         raise ArgumentError, "invalid manifest call mode: #{call_mode.inspect}" unless CALL_MODES.include?(call_mode)
         raise ArgumentError, "call_sequence must be positive" unless call_sequence.positive?
         expected = (0...segments.length).to_a

data/lib/phronomy/agent/llm_operation_result.rb

@@ -2,20 +2,25 @@
 
 module Phronomy
   module Agent
-    # Immutable carrier for one LLM adapter operation outcome.
+    # Immutable carrier for one Provider operation outcome.
     #
-    # Worker/timer threads create this value without mutating AgentInvocation.
-    # AgentInvocationSessionBuilder posts it as :llm_completed or :llm_failed,
-    # and AgentInvocation applies it on the EventLoop thread.
+    # The Provider Call identity is allocated on EventLoop before transport starts.
+    # Worker completion carries that semantic identity back to the owning
+    # FSMSession, which validates it against the currently active call before
+    # applying any live state.
     #
     # @api private
     class LLMOperationResult
-      attr_reader :response, :error, :streaming
+      attr_reader :llm_call_id, :response, :error, :streaming
 
-      def initialize(response: nil, error: nil, streaming: false)
+      def initialize(llm_call_id:, response: nil, error: nil, streaming: false)
+        id = llm_call_id&.to_s
+        raise ArgumentError, "LLMOperationResult requires llm_call_id" if id.nil? || id.empty?
+
+        @llm_call_id = id.freeze
         @response = response
         @error = error
-        @streaming = streaming
+        @streaming = !!streaming
         freeze
       end
     end

data/lib/phronomy/agent/phase_machine_builder.rb

@@ -4,12 +4,6 @@ require "state_machines"
 
 module Phronomy
   module Agent
-    # Compiles AgentInvocation phase topology.
-    #
-    # Async completion is represented by explicit FSM events. This builder does
-    # not await Tasks or register Task callbacks.
-    #
-    # @api private
     class PhaseMachineBuilder
       TOOL_EVENTS = %i[
         tool_authorized
@@ -43,6 +37,7 @@ module Phronomy
             state :recording_tool_results
             state :suspended
             state :output_filtering
+            state :handed_off
             state :completed
             state :blocked
             state :failed
@@ -70,7 +65,6 @@ module Phronomy
                 if: ->(machine) { machine.context&.ready_to_dispatch? }
               transition evaluating_tools: :waiting_for_tools
 
-              transition dispatching_tools: :evaluating_tools
               transition recording_tool_results: :calling_llm
 
               transition output_filtering: :completed,
@@ -80,6 +74,12 @@ module Phronomy
             end
 
             event :llm_completed do
+              transition calling_llm: :failed,
+                if: ->(machine) { machine.context&.callback_failed? }
+              transition calling_llm: :failed,
+                if: ->(machine) { machine.context&.handoff_failed? }
+              transition calling_llm: :handed_off,
+                if: ->(machine) { machine.context&.handoff_requested? }
               transition calling_llm: :starting_tools,
                 if: ->(machine) { machine.context&.tool_call_pending? }
               transition calling_llm: :output_filtering
@@ -89,6 +89,18 @@ module Phronomy
               transition calling_llm: :failed
             end
 
+            event :llm_setup_failed do
+              transition calling_llm: :failed
+            end
+
+            event :tool_setup_failed do
+              transition dispatching_tools: :failed
+            end
+
+            event :tool_dispatch_prepared do
+              transition dispatching_tools: :evaluating_tools
+            end
+
             TOOL_EVENTS.each do |event_name|
               event event_name do
                 transition waiting_for_tools: :evaluating_tools

data/lib/phronomy/agent/provider_call_outcome.rb

@@ -3,11 +3,10 @@
 module Phronomy
   module Agent
     # Immutable, Phronomy-owned snapshot of one completed Provider assistant output.
-    # It is captured before Agent-owned Tool execution begins, so durable logging
-    # never depends on RubyLLM's later control flow or Application callbacks.
     ProviderCallOutcome = Data.define(:role, :content, :tool_calls, :usage, :metadata) do
       def self.capture(message)
         return if message.nil?
+        return message if message.is_a?(self)
 
         calls = if message.respond_to?(:tool_calls) && message.tool_calls
           source = message.tool_calls.respond_to?(:values) ? message.tool_calls.values : Array(message.tool_calls)
@@ -32,6 +31,17 @@ module Phronomy
         )
       end
 
+      def self.from_h(hash)
+        source = hash.to_h { |key, value| [key.to_s, value] }
+        new(
+          role: source.fetch("role", "assistant"),
+          content: source["content"],
+          tool_calls: source.fetch("tool_calls", []),
+          usage: source.fetch("usage", {}),
+          metadata: source.fetch("metadata", {})
+        )
+      end
+
       def self.tool_call_hash(call)
         return call.to_h if call.respond_to?(:to_h)
 
@@ -54,11 +64,7 @@ module Phronomy
         when String, Integer, Float, TrueClass, FalseClass, NilClass
           value
         else
-          if value.respond_to?(:to_h)
-            normalize(value.to_h)
-          else
-            value.to_s
-          end
+          value.respond_to?(:to_h) ? normalize(value.to_h) : value.to_s
         end
       end
       private_class_method :normalize
@@ -78,6 +84,16 @@ module Phronomy
         freeze
       end
 
+      def to_h
+        {
+          "role" => role&.to_s,
+          "content" => content,
+          "tool_calls" => tool_calls,
+          "usage" => usage,
+          "metadata" => metadata
+        }.compact
+      end
+
       def content_present?
         !content.nil? && !(content.respond_to?(:empty?) && content.empty?)
       end