phronomy 0.26.0 → 0.27.0

data/lib/phronomy/agent/{tool_definition_set.rb → tool_execution/tool_definition_set.rb}

@@ -14,10 +14,10 @@ module Phronomy
             "name" => tool.name.to_s,
             "description" => tool.description.to_s,
             "parameters_schema" => normalize(
-              tool.respond_to?(:parameters_schema) ? tool.parameters_schema : {}
+              tool.parameters_schema
             ),
             "provider_options" => normalize(
-              tool.respond_to?(:provider_options) ? tool.provider_options : {}
+              tool.provider_options
             )
           }
         end.freeze
@@ -47,13 +47,13 @@ module Phronomy
 
       def initialize(runtime_tools:, definitions:)
         @runtime_tools = Array(runtime_tools).freeze
-        @definitions = Immutable.copy(definitions)
+        @definitions = Phronomy::Values::Immutable.copy(definitions)
         validate_unique_names!
         freeze
       end
 
       def select_definitions(expected_definitions)
-        expected = Immutable.copy(Array(expected_definitions))
+        expected = Phronomy::Values::Immutable.copy(Array(expected_definitions))
         current_by_name = definitions.each_with_index.to_h do |definition, index|
           [definition.fetch("name"), [definition, runtime_tools.fetch(index)]]
         end
@@ -70,6 +70,11 @@ module Phronomy
             raise Phronomy::ConfigurationError,
               "ContextPolicy selected Tool not present in current Agent configuration: #{name}"
           end
+          if definition["parameters_schema"] == {} && current_definition["parameters_schema"] != {}
+            raise Phronomy::ConfigurationError,
+              "Saved Tool definition lacks a verifiable parameters_schema: #{name}; " \
+              "finish this in-flight execution on its original version before upgrading"
+          end
           unless Phronomy::CanonicalJSON.dump(current_definition) ==
               Phronomy::CanonicalJSON.dump(definition)
             raise Phronomy::ConfigurationError,

data/lib/phronomy/agent/{tool_invocation.rb → tool_execution/tool_invocation.rb}

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "../../engine/concurrency/worker_input_restricted"
+
+require "digest"
 require "securerandom"
 
 module Phronomy
   module Agent
     class ToolInvocation
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       AuthorizationOutcome = Data.define(
         :tool_invocation_id, :decision, :facts, :reason, :error, :cancelled
       ) do
@@ -74,6 +79,20 @@ module Phronomy
         :origin,
         :metadata
 
+      # Stable identity used both before dispatch and when rebuilding facts.
+      # This does not construct, authorize, or execute a Tool invocation.
+      # @api private
+      def self.semantic_id(execution_id:, llm_call_id:, tool_call_id:, tool_name:)
+        source = [
+          "tool_invocation",
+          execution_id.to_s,
+          llm_call_id.to_s,
+          tool_call_id.to_s,
+          tool_name.to_s
+        ].join("\0")
+        "tool_invocation-#{Digest::SHA256.hexdigest(source)}".freeze
+      end
+
       def self.missing(
         execution_id:,
         agent:,
@@ -135,6 +154,16 @@ module Phronomy
         @phase = phase
       end
 
+      # Restores a newly constructed invocation from materialized saved facts.
+      # Recovery owns snapshot decoding and identity matching. This operation
+      # owns state application; it neither dispatches nor reevaluates approval.
+      # @api private
+      def restore_state!(status:, result: nil, approval_item: nil)
+        restore_saved_state!(status, result)
+        restore_approval_evidence!(approval_item)
+        self
+      end
+
       def handle_fsm_event(event)
         case event.type
         when :authorization_completed
@@ -215,7 +244,7 @@ module Phronomy
           cancellation_token: @config[:cancellation_token],
           on_full: :raise
         ) { evaluator.send(:evaluate_authorization_command, command) }
-        runtime.event_loop.supervise_agent_operation(@execution_id, operation)
+        Phronomy::Agent::ExecutionRegistry.for(runtime.event_loop).supervise_agent_operation(@execution_id, operation)
         operation.on_complete do |outcome, error|
           callback.call(
             error ? evaluator.send(:authorization_failure_result, tool_invocation_id, error) : outcome
@@ -259,7 +288,7 @@ module Phronomy
             raise Phronomy::ToolError,
               "Tool #{@tool.class.name}#call_async must return a completion handle"
           end
-          runtime.event_loop.supervise_agent_operation(@execution_id, operation)
+          Phronomy::Agent::ExecutionRegistry.for(runtime.event_loop).supervise_agent_operation(@execution_id, operation)
 
           evaluator = self.class
           tool_invocation_id = @id.to_s.freeze
@@ -332,7 +361,7 @@ module Phronomy
       end
 
       def tool_schema
-        @tool&.respond_to?(:params_schema) ? @tool.params_schema : {}
+        @tool&.respond_to?(:parameters_schema) ? @tool.parameters_schema : {}
       end
 
       def display_arguments
@@ -345,6 +374,40 @@ module Phronomy
 
       private
 
+      def restore_saved_state!(status, result)
+        case status
+        when :awaiting_approval
+          validate! unless terminal?
+          @final_decision = :require_approval
+          mark_awaiting_approval!
+        when :authorized
+          validate! unless terminal?
+          @final_decision = :allow
+          mark_authorized!
+        when :completed
+          @result = result
+          @status = :completed
+        when :rejected
+          mark_rejected!
+        when :failed
+          mark_framework_failed!(
+            Phronomy::ToolError.new("durably restored Tool preflight failure")
+          )
+        when :cancelled
+          mark_cancelled!
+        else
+          raise Phronomy::ExecutionRehydrationRequiredError,
+            "unsupported durable Tool snapshot state: #{status.inspect}"
+        end
+      end
+
+      def restore_approval_evidence!(item)
+        return unless item
+
+        @facts = immutable_copy(item.facts)
+        @authorization_reason = item.reason
+      end
+
       def authorization_command
         definition = @agent.class.agent_definition
 
@@ -490,24 +553,7 @@ module Phronomy
       private_class_method :immutable_command_copy
 
       def self.phronomy_managed_live_domain_object?(value)
-        value.is_a?(Phronomy::Agent::Base) ||
-          value.is_a?(Phronomy::Agent::AgentRoot) ||
-          value.is_a?(Phronomy::Agent::AgentExecution) ||
-          value.is_a?(Phronomy::Agent::AgentInvocation) ||
-          value.is_a?(Phronomy::Agent::ToolInvocation) ||
-          value.is_a?(Phronomy::Agent::JournalProjection) ||
-          value.is_a?(Phronomy::Agent::ExecutionCoordinator) ||
-          value.is_a?(Phronomy::Agent::Context::Capability::Base) ||
-          value.is_a?(Phronomy::Workflow) ||
-          value.is_a?(Phronomy::WorkflowRunner) ||
-          value.is_a?(Phronomy::WorkflowContext) ||
-          value.is_a?(Phronomy::Runtime) ||
-          value.is_a?(Phronomy::TaskResult) ||
-          value.is_a?(Phronomy::EventLoop) ||
-          value.is_a?(Phronomy::FSMSession) ||
-          value.is_a?(Phronomy::FSMSession::EventSink) ||
-          value.is_a?(Phronomy::Concurrency::CancellationToken) ||
-          value.is_a?(Phronomy::Concurrency::OffloadPool)
+        value.is_a?(Phronomy::Concurrency::WorkerInputRestricted)
       end
       private_class_method :phronomy_managed_live_domain_object?
 
@@ -551,7 +597,7 @@ module Phronomy
 
       def start_async_tool_operation(runtime)
         if uses_default_call_async?
-          Phronomy::Agent::ToolExecutor.call_async(
+          Phronomy::Agent::Context::Capability::ToolExecutor.call_async(
             tool: @tool,
             args: @arguments,
             cancellation_token: @config[:cancellation_token],
@@ -665,18 +711,7 @@ module Phronomy
       end
 
       def immutable_copy(value)
-        case value
-        when Hash
-          value.each_with_object({}) do |(key, item), result|
-            result[immutable_copy(key)] = immutable_copy(item)
-          end.freeze
-        when Array
-          value.map { |item| immutable_copy(item) }.freeze
-        when String
-          value.dup.freeze
-        else
-          value
-        end
+        Phronomy::Values::Immutable.copy(value)
       end
 
       def redact_for_display(value)

data/lib/phronomy/common/configuration_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Phronomy
+  class ConfigurationError < Error; end
+end

data/lib/phronomy/common/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Error < StandardError; end
+end

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.rb → configuration/configuration.rb}

@@ -6,13 +6,23 @@ module Phronomy
     STREAM_CALLBACK_ERROR_POLICIES = %i[report fail_task].freeze
     private_constant :STREAM_CALLBACK_ERROR_POLICIES
 
+    DEFAULT_FACTORIES = {}
+    private_constant :DEFAULT_FACTORIES
+
+    # Bind fresh-instance factories once during application loading. Concrete
+    # component selection belongs to runtime_composition, not configuration.
+    # Applications replace instances through the existing configuration writers.
+    # @api private
+    def self.install_default_factories(tracer:, llm_adapter:)
+      DEFAULT_FACTORIES.replace(tracer: tracer, llm_adapter: llm_adapter).freeze
+      nil
+    end
+
     attr_accessor :default_model
     attr_accessor :default_embedding_model
     attr_accessor :tracer
     attr_accessor :before_llm_input
-    attr_accessor :default_output_reserve
     attr_accessor :recursion_limit
-    attr_accessor :parallel_tool_execution
     attr_accessor :trace_pii
     attr_accessor :logger
     attr_accessor :event_loop_stop_grace_seconds
@@ -40,11 +50,10 @@ module Phronomy
 
     def initialize
       @recursion_limit = 25
-      @tracer = Phronomy::Tracing::NullTracer.new
+      @tracer = DEFAULT_FACTORIES.fetch(:tracer).call
       @trace_pii = false
-      @parallel_tool_execution = false
       @event_loop_stop_grace_seconds = 5
-      @llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
+      @llm_adapter = DEFAULT_FACTORIES.fetch(:llm_adapter).call
       @event_loop_starvation_threshold_seconds = nil
       @event_loop_dispatch_threshold_seconds = nil
       @stream_callback_error_policy = :report

data/lib/phronomy/configuration/global_configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Global configuration access, replacement, and scoped overrides.
+# Explicitly loaded by the application entry point; not a common definition.
+module Phronomy
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def with_configuration
+      original = @configuration&.dup
+      yield configuration
+    ensure
+      @configuration = original
+    end
+  end
+end

data/lib/phronomy/content_store/storage_schema.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module ContentStore
+    # @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,43 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module ContentStore
+    # Content identity and digest validation belong to ContentStore, not Blobs.
+    # @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/engine/backpressure_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class BackpressureError < Error; end
+end

data/lib/phronomy/{blocking.rb → engine/blocking.rb}

@@ -22,7 +22,7 @@ module Phronomy
 
       begin
         unless invocation_context.nil?
-          binding = Execution.__operation_binding(invocation_context: invocation_context,
+          binding = Concurrency::OperationBinding.new(invocation_context: invocation_context,
             cancellation_token: cancellation_token)
         end
         result = Phronomy::Runtime.instance.offload.submit(

data/lib/phronomy/engine/cancellation_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class CancellationError < Error; end
+end

data/lib/phronomy/engine/concurrency/cancellation_token.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "worker_input_restricted"
+
 module Phronomy
   module Concurrency
     # Cooperative cancellation token for Agent/Tool work.
     class CancellationToken
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       # Creates a token that expires after +seconds+ measured with the monotonic clock.
       # @api public
       def self.timeout_after(seconds)

data/lib/phronomy/engine/concurrency/offload_pool.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "worker_input_restricted"
+
 module Phronomy
   module Concurrency
     # A bounded, observable thread pool for synchronous work that must not run on
@@ -41,6 +43,8 @@ module Phronomy
     #   task = pool.submit(timeout: 30, cancellation_token: token) { expensive_call }
     #   result = task.wait_result
     class OffloadPool
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       # Private execution record for one submitted synchronous operation.
       #
       # Caller-facing completion is represented exclusively by {Phronomy::TaskResult}.

data/lib/phronomy/engine/concurrency/operation_binding.rb

@@ -4,7 +4,7 @@ module Phronomy
   module Concurrency
     # Connects explicit invocation controls before operation admission. Its token
     # is private: cancelling it never cancels the application's shared tokens.
-    # Used by Execution's Agent and Blocking adapters; it owns no worker.
+    # Used by Agent, Blocking and Orchestrator admission; it owns no worker.
     # @api private
     class OperationBinding
       attr_reader :token, :scope

data/lib/phronomy/engine/concurrency/worker_input_restricted.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # Marks framework-managed objects excluded from authorization worker value
+    # snapshots and application behavior handles. Each owning type opts in.
+    # This methodless contract does not validate arbitrary object graphs or
+    # restrict every OffloadPool command. Application-owned opaque values retain
+    # their existing contract (ADR-024/045).
+    # @api private
+    module WorkerInputRestricted
+    end
+  end
+end