phronomy 0.26.0 → 0.28.0

data/lib/phronomy/{agent → common/values}/immutable.rb

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
 
+require_relative "../canonical_json"
+
 module Phronomy
-  module Agent
+  module Values
+    # Shared value operations for snapshots, recovery facts, and result views.
+    # Hash, Array, and String trees are copied and frozen; other values retain
+    # their identity. Canonical JSON validation is a separate operation.
+    # @api private
     module Immutable
       module_function
 
+      # @api private
       def copy(value)
         case value
         when Hash
@@ -20,6 +27,7 @@ module Phronomy
         end
       end
 
+      # @api private
       def validate_canonical_json!(value, label: "value")
         Phronomy::CanonicalJSON.dump(value)
         true

data/lib/phronomy/common/values/serializable.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Values
+    # Prepares a Ruby value tree for JSON serialization. Hash keys and Symbol
+    # values become Strings; containers are rebuilt and scalar objects retained.
+    # This neither freezes values nor validates canonical JSON numbers/encoding.
+    # @api private
+    module Serializable
+      module_function
+
+      def convert(value, unsupported_message:)
+        case value
+        when Hash
+          value.to_h { |key, child| [key.to_s, convert(child, unsupported_message: unsupported_message)] }
+        when Array
+          value.map { |child| convert(child, unsupported_message: unsupported_message) }
+        when String, Integer, Float, TrueClass, FalseClass, NilClass
+          value
+        when Symbol
+          value.to_s
+        else
+          if value.respond_to?(:to_h)
+            convert(value.to_h, unsupported_message: unsupported_message)
+          else
+            raise ArgumentError, "#{unsupported_message}: #{value.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/configuration/runtime_settings.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../common/configuration_error"
+
+module Phronomy
+  # Neutral runtime values only. Application composition supplies the current
+  # settings object; Tool and Tracing own their domain-specific settings.
+  # @api private
+  class RuntimeSettings
+    # Bind the application's settings accessor without evaluating it at boot.
+    # @api private
+    def self.install_provider(&provider)
+      raise ArgumentError, "RuntimeSettings provider requires a block" unless provider
+
+      @provider = provider
+      nil
+    end
+
+    # Resolve on every read so configuration reset/scoped restoration is visible.
+    # @return [RuntimeSettings]
+    # @api private
+    def self.current
+      settings = @provider&.call
+      unless settings.is_a?(RuntimeSettings)
+        raise ConfigurationError, "RuntimeSettings provider must return RuntimeSettings"
+      end
+
+      settings
+    end
+
+    attr_accessor :logger
+    attr_accessor :event_loop_stop_grace_seconds
+    attr_accessor :event_loop_starvation_threshold_seconds
+    attr_accessor :event_loop_dispatch_threshold_seconds
+    attr_accessor :offload_pool_size, :offload_queue_size
+    attr_accessor :authorization_pool_size, :authorization_queue_size
+
+    # @api private
+    def initialize
+      @event_loop_stop_grace_seconds = 5
+      @event_loop_starvation_threshold_seconds = nil
+      @event_loop_dispatch_threshold_seconds = nil
+      @offload_pool_size = 10
+      @offload_queue_size = 100
+      @authorization_pool_size = 4
+      @authorization_queue_size = 100
+    end
+  end
+end

data/lib/phronomy/content_store/storage_schema.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module ContentStore
+    # Resources owned by the content service and supplied to Storage composition.
+    # @api private
+    module StorageSchema
+      CONTENTS = Phronomy::Storage::Resource.new(id: "content.blobs", kind: :blobs,
+        attributes: {canonicalization_version: :integer})
+    end
+  end
+end

data/lib/phronomy/content_store/stored_contents.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module ContentStore
+    # Content-addressed storage service over an injected Storage view.
+    # Content identity and digest validation belong here; Storage owns I/O.
+    # @api private
+    class StoredContents < Base
+      def initialize(view) = @view = view
+
+      def put(bytes, canonicalization_version:)
+        value = String(bytes).b
+        id = content_id_for(value)
+        @view.atomic do |bound|
+          blob = bound.blobs(StorageSchema::CONTENTS).put_if_absent(key: id, bytes: value,
+            attributes: {canonicalization_version: Integer(canonicalization_version)})
+          verify!(blob, id)
+          id
+        end
+      rescue Phronomy::Storage::BlobConflictError => error
+        raise IntegrityError, error.message
+      end
+
+      def fetch(content_id)
+        id = content_id.to_s
+        @view.atomic do |bound|
+          blob = bound.blobs(StorageSchema::CONTENTS).fetch(id)
+          verify!(blob, id)
+          blob.bytes.dup
+        end
+      end
+
+      def exist?(content_id) = @view.blobs(StorageSchema::CONTENTS).exist?(content_id.to_s)
+
+      private
+
+      def verify!(blob, id)
+        unless blob.key == id && content_id_for(blob.bytes) == id
+          raise IntegrityError, "content digest mismatch: #{id}"
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/context/assembly.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Context
+    # Context preparation framework: policy, plan invariants, canonical input and budget.
+    class Assembly
+      ASSEMBLY_POLICY_VERSION = 9
+      POLICY_ORIGIN_METADATA_KEY = "context_policy_origin"
+      POLICY_ITEM_ID_METADATA_KEY = "context_policy_item_id"
+      SEMANTIC_CATEGORY_METADATA_KEY = "context_policy_semantic_category"
+      CONTENT_FORMAT_METADATA_KEY = "context_policy_content_format"
+      CONVERSATION_GROUP_ID_METADATA_KEY = "context_policy_conversation_group_id"
+      TRUSTED_HANDOFF_METADATA_KEYS = %w[
+        handoff_policy_category
+        handoff_provenance
+      ].freeze
+      HANDOFF_POLICY_CATEGORY_METADATA_KEY = "handoff_policy_category"
+
+      Prepared = Data.define(:input, :plan, :model_config, :call_sequence, :call_mode, :adapter_identity)
+
+      def initialize(tracer: Phronomy::Tracing::Settings.current.tracer)
+        @tracer = tracer
+      end
+
+      # Executes policy once against an immutable snapshot, outside a save transaction.
+      # All policies share validation and canonicalization; callers never replay policy to recover.
+      def prepare(input:, policy:, adapter_identity:)
+        plan = invoke_policy(policy, input)
+        Phronomy::Context::ContextPlanValidator.new.validate!(input: input, plan: plan)
+        Prepared.new(
+          input: input, plan: plan, model_config: input.model_config,
+          call_sequence: input.call_sequence, call_mode: input.call_mode,
+          adapter_identity: Phronomy::Values::Immutable.copy(adapter_identity)
+        )
+      end
+
+      def store(prepared, contents:)
+        unless prepared.is_a?(Prepared)
+          raise ArgumentError, "Context::Assembly#store expected Context::Assembly::Prepared"
+        end
+
+        plan = Phronomy::Context::ContextPlanValidator.new.validate!(input: prepared.input, plan: prepared.plan)
+        segments = []
+        plan.instruction.each do |item|
+          segments << segment_from_content_item(
+            item,
+            contents: contents,
+            additional_metadata: {SEMANTIC_CATEGORY_METADATA_KEY => "instruction"}
+          )
+        end
+        plan.knowledge.each do |item|
+          segments << segment_from_content_item(
+            item,
+            contents: contents,
+            additional_metadata: {SEMANTIC_CATEGORY_METADATA_KEY => "knowledge"}
+          )
+        end
+        plan.conversation.each_with_index do |group, group_index|
+          group_metadata = {
+            SEMANTIC_CATEGORY_METADATA_KEY => "conversation",
+            CONVERSATION_GROUP_ID_METADATA_KEY =>
+              "conversation:#{prepared.call_sequence}:#{group_index}"
+          }
+          if tool_exchange_group?(group)
+            group_metadata[HANDOFF_POLICY_CATEGORY_METADATA_KEY] = "tool_exchanges"
+          end
+
+          group.each do |item|
+            segments << segment_from_content_item(
+              item,
+              contents: contents,
+              additional_metadata: group_metadata
+            )
+          end
+        end
+
+        selected_tool_definitions = plan.tools.map(&:definition)
+        Phronomy::Context::FinalBudgetValidator.new(
+          content_loader: lambda { |ref| fetch_content_from(contents, ref) }
+        ).validate!(
+          token_budget: prepared.input.token_budget,
+          segments: segments,
+          extra_values: [selected_tool_definitions]
+        )
+
+        store_manifest(
+          contents: contents,
+          call_sequence: prepared.call_sequence,
+          call_mode: prepared.call_mode,
+          segments: segments,
+          model_config_ref: contents.put_json(prepared.model_config),
+          tool_definitions_ref: contents.put_json(selected_tool_definitions),
+          adapter_identity: prepared.adapter_identity
+        )
+      end
+
+      private
+
+      def invoke_policy(policy, policy_input)
+        tracer = @tracer
+        span = tracer.start_span(
+          "context_policy",
+          agent_id: policy_input.agent_id,
+          execution_id: policy_input.execution_id,
+          call_sequence: policy_input.call_sequence,
+          policy_class: policy.class.name || policy.class.to_s,
+          instruction_count: policy_input.instruction.length,
+          knowledge_count: policy_input.knowledge.length,
+          tool_count: policy_input.tools.length,
+          conversation_group_count: policy_input.conversation.length
+        )
+        result = policy.call(policy_input)
+        tracer.finish_span(span)
+        result
+      rescue => error
+        tracer&.finish_span(span, error: error) if defined?(span) && span
+        raise
+      end
+
+      def store_manifest(
+        contents:,
+        call_sequence:,
+        call_mode:,
+        segments:,
+        model_config_ref:,
+        tool_definitions_ref:,
+        adapter_identity:
+      )
+        positioned = segments.each_with_index.map do |value, position|
+          Phronomy::Context::LLMInputManifest::Segment.new(**value.merge(position: position))
+        end
+        manifest = Phronomy::Context::LLMInputManifest.new(
+          call_sequence: call_sequence,
+          call_mode: call_mode,
+          segments: positioned,
+          model_config_ref: model_config_ref,
+          tool_definitions_ref: tool_definitions_ref,
+          assembly_policy_version: ASSEMBLY_POLICY_VERSION,
+          ruby_llm_version: adapter_identity["sdk_version"],
+          adapter_name: adapter_identity["adapter_name"]
+        )
+        [manifest, contents.put_json(manifest.to_h)]
+      end
+
+      def segment_from_content_item(item, contents:, additional_metadata: {})
+        content_ref = item.provenance.content_ref || store_item_content(item, contents)
+        metadata = sanitized_item_metadata(item).merge(additional_metadata).merge(
+          CONTENT_FORMAT_METADATA_KEY => item.content_format.to_s,
+          POLICY_ITEM_ID_METADATA_KEY => item.id,
+          POLICY_ORIGIN_METADATA_KEY => item.provenance.origin.to_s,
+          "journal_record_id" => item.provenance.record_id,
+          "source_agent_id" => item.provenance.agent_id,
+          "source_execution_id" => item.provenance.execution_id,
+          "llm_call_id" => item.provenance.llm_call_id
+        ).compact
+
+        {
+          category: item.kind,
+          role: item.role,
+          content_ref: content_ref,
+          delivery: item.respond_to?(:delivery) ? item.delivery : :chat_message,
+          tool_call_id: item.respond_to?(:tool_call_id) ? item.tool_call_id : nil,
+          metadata: metadata
+        }
+      end
+
+      def sanitized_item_metadata(item)
+        raw = item.metadata.to_h.transform_keys(&:to_s)
+        # :working origin is Phronomy-controlled (from InitialPreparation),
+        # so handoff routing metadata on working records is equally trusted.
+        trusted_handoff = if item.provenance.origin == :handoff || item.provenance.origin == :working
+          raw.slice(*TRUSTED_HANDOFF_METADATA_KEYS)
+        else
+          {}
+        end
+
+        raw.except(*Phronomy::Context::ContextPolicyInput::FRAMEWORK_METADATA_KEYS)
+          .merge(trusted_handoff)
+      end
+
+      def tool_exchange_group?(group)
+        Array(group).any? do |item|
+          item.kind == :assistant_message && !item.tool_call_ids.empty?
+        end && Array(group).any? { |item| item.kind == :tool_message }
+      end
+
+      def store_item_content(item, contents)
+        if item.content_format == :json
+          contents.put_json(item.content)
+        else
+          contents.put_text(item.content.to_s)
+        end
+      end
+
+      def fetch_content_from(contents, ref)
+        contents.fetch_text(ref)
+      rescue
+        contents.fetch(ref)
+      end
+    end
+  end
+end

data/lib/phronomy/{context_budget_exceeded_error.rb → context/budget_exceeded_error.rb}

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require_relative "../common/error"
+
 module Phronomy
   # Raised when mandatory context content (system instructions, tool definitions,
   # current input) exhausts the model's context window, leaving no room for
   # prior conversation history.
-  class ContextBudgetExceededError < Error; end
+  module Context
+    class BudgetExceededError < Phronomy::Error; end
+  end
 end

data/lib/phronomy/context/candidate.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Context
+    Candidate = Data.define(
+      :candidate_id,
+      :source_kind,
+      :category,
+      :role,
+      :content_ref,
+      :record_id,
+      :agent_id,
+      :execution_id,
+      :llm_call_id,
+      :tool_call_id,
+      :sequence,
+      :constraint,
+      :priority,
+      :metadata
+    ) do
+      def initialize(**values)
+        effective_constraint = values[:constraint] ||
+          Constraint.selectable(origin: :context_policy)
+        unless effective_constraint.is_a?(Constraint)
+          raise ArgumentError,
+            "Candidate constraint must be Constraint"
+        end
+
+        normalized = values.merge(
+          candidate_id: values.fetch(:candidate_id).to_s.freeze,
+          source_kind: values.fetch(:source_kind).to_sym,
+          category: values.fetch(:category).to_sym,
+          role: values[:role]&.to_sym,
+          content_ref: values.fetch(:content_ref).to_s.freeze,
+          record_id: values[:record_id]&.to_s&.freeze,
+          agent_id: values[:agent_id]&.to_s&.freeze,
+          execution_id: values[:execution_id]&.to_s&.freeze,
+          llm_call_id: values[:llm_call_id]&.to_s&.freeze,
+          tool_call_id: values[:tool_call_id]&.to_s&.freeze,
+          sequence: values[:sequence] && Integer(values[:sequence]),
+          constraint: effective_constraint,
+          priority: Integer(values[:priority] || 0),
+          metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})
+        )
+
+        super(**normalized)
+        freeze
+      end
+    end
+  end
+end

data/lib/phronomy/context/constraint.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Context
+    CONSTRAINT_MODES = %i[required selectable forbidden].freeze
+
+    Constraint = Data.define(:mode, :origin, :reason) do
+      def initialize(mode:, origin:, reason: nil)
+        normalized_mode = mode.to_sym
+        unless CONSTRAINT_MODES.include?(normalized_mode)
+          raise ArgumentError, "unknown Selection constraint mode: #{mode.inspect}"
+        end
+
+        super(
+          mode: normalized_mode,
+          origin: origin.to_sym,
+          reason: reason&.to_s&.freeze
+        )
+        freeze
+      end
+
+      def required?
+        mode == :required
+      end
+
+      def selectable?
+        mode == :selectable
+      end
+
+      def forbidden?
+        mode == :forbidden
+      end
+
+      def self.required(origin:, reason: nil)
+        new(mode: :required, origin: origin, reason: reason)
+      end
+
+      def self.selectable(origin:, reason: nil)
+        new(mode: :selectable, origin: origin, reason: reason)
+      end
+
+      def self.forbidden(origin:, reason: nil)
+        new(mode: :forbidden, origin: origin, reason: reason)
+      end
+    end
+  end
+end

data/lib/phronomy/{agent → context}/context_plan.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module Context
     ContextPlan = Data.define(
       :instruction,
       :knowledge,
@@ -21,7 +21,7 @@ module Phronomy
           knowledge: Array(knowledge).freeze,
           tools: Array(tools).freeze,
           conversation: Array(conversation).map { |group| Array(group).freeze }.freeze,
-          metadata: Immutable.copy(metadata || {})
+          metadata: Phronomy::Values::Immutable.copy(metadata || {})
         )
         freeze
       end

data/lib/phronomy/{agent → context}/context_plan_validator.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module Context
     class ContextPlanValidator
       RESERVED_KIND_CATEGORIES = {
         instruction: :instruction,
@@ -82,7 +82,7 @@ module Phronomy
         end
         return if missing.empty?
 
-        raise Phronomy::ContextBudgetExceededError,
+        raise Phronomy::Context::BudgetExceededError,
           "ContextPlan omitted required #{label} item(s): #{missing.map(&:id).inspect}"
       end
 
@@ -130,7 +130,7 @@ module Phronomy
         end
         return if missing_groups.empty?
 
-        raise Phronomy::ContextBudgetExceededError,
+        raise Phronomy::Context::BudgetExceededError,
           "ContextPlan omitted required conversation group(s): " \
           "#{missing_groups.map { |group| group.map(&:id) }.inspect}"
       end

data/lib/phronomy/{agent → context}/context_policy.rb

@@ -3,7 +3,7 @@
 require "securerandom"
 
 module Phronomy
-  module Agent
+  module Context
     class ContextPolicy
       def call(_input)
         raise NotImplementedError, "#{self.class}#call is not implemented"

data/lib/phronomy/{agent → context}/context_policy_input.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module Context
     ContextPolicyInput = Data.define(
       :agent_id,
       :execution_id,
@@ -50,8 +50,8 @@ module Phronomy
           knowledge: normalized_knowledge,
           tools: normalized_tools,
           conversation: normalized_conversation,
-          model_config: Immutable.copy(values[:model_config] || {}),
-          metadata: Immutable.copy(values[:metadata] || {})
+          model_config: Phronomy::Values::Immutable.copy(values[:model_config] || {}),
+          metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})
         ))
         freeze
       end
@@ -145,7 +145,7 @@ module Phronomy
       ) do
         def initialize(**values)
           provenance = ContextPolicyInput.send(:normalize_provenance, values[:provenance])
-          definition = Immutable.copy(values.fetch(:definition))
+          definition = Phronomy::Values::Immutable.copy(values.fetch(:definition))
           unless definition.is_a?(Hash) && definition["name"].to_s != ""
             raise ArgumentError, "ContextPolicyInput ToolItem definition requires a non-empty name"
           end
@@ -156,7 +156,7 @@ module Phronomy
             estimated_tokens: ContextPolicyInput.send(:normalize_estimated_tokens, values[:estimated_tokens]),
             required: !!values[:required],
             provenance: provenance,
-            metadata: Immutable.copy(values[:metadata] || {})
+            metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})
           )
           raise ArgumentError, "ContextPolicyInput ToolItem id must not be empty" if id.empty?
           freeze
@@ -212,12 +212,12 @@ module Phronomy
             id: id,
             kind: kind,
             role: role,
-            content: Immutable.copy(values[:content]),
+            content: Phronomy::Values::Immutable.copy(values[:content]),
             content_format: content_format,
             estimated_tokens: normalize_estimated_tokens(values[:estimated_tokens]),
             required: !!values[:required],
             provenance: normalize_provenance(values[:provenance]),
-            metadata: Immutable.copy(values[:metadata] || {})
+            metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})
           }
         end
 

data/lib/phronomy/{agent → context}/context_policy_input_builder.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module Context
     class ContextPolicyInputBuilder
       KNOWLEDGE_KINDS = %i[knowledge memory summary structured_state].freeze
       CONVERSATION_KINDS = %i[external_message assistant_message tool_message current_input current_request].freeze