phronomy 0.27.0 → 0.28.0

data/lib/phronomy/content_store/stored_contents.rb

@@ -2,7 +2,8 @@
 
 module Phronomy
   module ContentStore
-    # Content identity and digest validation belong to ContentStore, not Blobs.
+    # 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

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/{llm_contract/context_budget_exceeded_error.rb → context/budget_exceeded_error.rb}

@@ -6,5 +6,7 @@ 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_contract → context}/context_plan.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module Context
     ContextPlan = Data.define(
       :instruction,
       :knowledge,

data/lib/phronomy/{agent/context_contract → 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_contract → 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_contract → 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,

data/lib/phronomy/{agent/context_assembly → 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

data/lib/phronomy/context/default_policy.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Context
+    class DefaultPolicy < ContextPolicy
+      CONVERSATION_SHARE = 0.60
+
+      def self.instance
+        @instance ||= new.freeze
+      end
+
+      def call(input)
+        unless input.is_a?(ContextPolicyInput)
+          raise ArgumentError, "Default ContextPolicy expected ContextPolicyInput"
+        end
+
+        return all_context(input) unless input.token_budget
+
+        limit = input.token_budget.effective_input_limit
+        required_knowledge = input.knowledge.select(&:required?)
+        optional_knowledge = input.knowledge.reject(&:required?)
+        required_conversation = input.conversation.select { |group| group.any?(&:required?) }
+        optional_conversation = input.conversation.reject { |group| group.any?(&:required?) }
+
+        fixed_cost = item_cost(input.instruction) + item_cost(input.tools) +
+          item_cost(required_knowledge) + group_cost(required_conversation)
+        if fixed_cost > limit
+          raise Phronomy::Context::BudgetExceededError,
+            "Required Context (estimated #{fixed_cost} tokens) exceeds " \
+            "available input budget (#{limit} tokens)"
+        end
+
+        remaining = limit - fixed_cost
+        conversation_budget = (remaining * CONVERSATION_SHARE).floor
+        knowledge_budget = remaining - conversation_budget
+
+        selected_conversation, older_conversation, conversation_used =
+          select_recent_suffix(optional_conversation, conversation_budget)
+        selected_knowledge, remaining_knowledge, knowledge_used =
+          select_stable_fit(optional_knowledge, knowledge_budget)
+
+        reusable = remaining - conversation_used - knowledge_used
+        if reusable.positive? && !older_conversation.empty?
+          more_conversation, _, used =
+            select_recent_suffix(older_conversation, reusable)
+          selected_conversation = more_conversation + selected_conversation
+          reusable -= used
+        end
+        if reusable.positive? && !remaining_knowledge.empty?
+          more_knowledge, _remaining_knowledge, used =
+            select_stable_fit(remaining_knowledge, reusable)
+          selected_knowledge += more_knowledge
+          reusable -= used
+        end
+
+        conversation = (required_conversation + selected_conversation)
+          .uniq
+          .sort_by { |group| group_sequence(group) }
+        knowledge_ids = (required_knowledge + selected_knowledge).to_h { |item| [item.id, true] }
+        knowledge = input.knowledge.select { |item| knowledge_ids[item.id] }
+
+        plan(
+          instruction: input.instruction,
+          knowledge: knowledge,
+          tools: input.tools,
+          conversation: conversation,
+          metadata: {
+            "default_policy" => true,
+            "estimated_fixed_tokens" => fixed_cost,
+            "estimated_unused_tokens" => reusable
+          }
+        )
+      end
+
+      private
+
+      def all_context(input)
+        plan(
+          instruction: input.instruction,
+          knowledge: input.knowledge,
+          tools: input.tools,
+          conversation: input.conversation,
+          metadata: {"default_policy" => true}
+        )
+      end
+
+      def item_cost(items)
+        Array(items).sum { |item| Integer(item.estimated_tokens || 0) }
+      end
+
+      def group_cost(groups)
+        Array(groups).sum { |group| item_cost(group) }
+      end
+
+      def group_sequence(group)
+        group.filter_map(&:sequence).min || 0
+      end
+
+      def select_recent_suffix(groups, budget)
+        ordered = Array(groups).sort_by { |group| group_sequence(group) }
+        selected = []
+        remaining = Integer(budget)
+        stop_index = -1
+
+        (ordered.length - 1).downto(0) do |index|
+          cost = item_cost(ordered[index])
+          if cost > remaining
+            stop_index = index
+            break
+          end
+          selected.unshift(ordered[index])
+          remaining -= cost
+        end
+
+        older = if stop_index >= 0
+          ordered[0..stop_index]
+        else
+          []
+        end
+        [selected.freeze, older.freeze, Integer(budget) - remaining]
+      end
+
+      def select_stable_fit(items, budget)
+        remaining = Integer(budget)
+        selected = []
+        unselected = []
+        Array(items).each do |item|
+          cost = Integer(item.estimated_tokens || 0)
+          if cost <= remaining
+            selected << item
+            remaining -= cost
+          else
+            unselected << item
+          end
+        end
+        [selected.freeze, unselected.freeze, Integer(budget) - remaining]
+      end
+    end
+  end
+end

data/lib/phronomy/context/final_budget_validator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Context
+    class FinalBudgetValidator
+      def initialize(content_loader:)
+        @content_loader = content_loader
+      end
+
+      def validate!(token_budget:, segments:, extra_values: [])
+        return 0 unless token_budget
+
+        estimated = Array(segments).sum do |segment|
+          Phronomy::LlmContextWindow::TokenEstimator.estimate(
+            @content_loader.call(segment.fetch(:content_ref))
+          )
+        end
+        estimated += Array(extra_values).sum do |value|
+          bytes = value.is_a?(String) ? value : Phronomy::CanonicalJSON.dump(value)
+          Phronomy::LlmContextWindow::TokenEstimator.estimate(bytes)
+        end
+
+        limit = token_budget.effective_input_limit
+        if estimated > limit
+          raise Phronomy::Context::BudgetExceededError,
+            "Canonical LLM input (estimated #{estimated} tokens) exceeds " \
+            "available input budget (#{limit} tokens)"
+        end
+        estimated
+      end
+    end
+  end
+end

data/lib/phronomy/{agent/context_contract → context}/llm_input_build_context.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module Context
     # 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(