phronomy 0.26.0 → 0.28.0

data/lib/phronomy.rb

@@ -2,120 +2,119 @@
 
 require "zeitwerk"
 require "ruby_llm"
-require_relative "phronomy/ruby_llm_patches"
+require_relative "phronomy/version"
 
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
 loader.inflector.inflect("rag" => "RAG")
 loader.inflector.inflect("fsm_session" => "FSMSession")
+loader.inflector.inflect("fsm_protocol" => "FSMProtocol")
 loader.inflector.inflect("llm_adapter" => "LLMAdapter")
 loader.inflector.inflect("llm_operation_result" => "LLMOperationResult")
 loader.inflector.inflect("ruby_llm" => "RubyLLM")
 loader.inflector.inflect("canonical_json" => "CanonicalJSON")
-loader.inflector.inflect("ruby_llm_materializer" => "RubyLLMMaterializer")
 loader.inflector.inflect("llm_call_record" => "LLMCallRecord")
 loader.inflector.inflect("llm_input_manifest" => "LLMInputManifest")
 loader.inflector.inflect("llm_input_build_context" => "LLMInputBuildContext")
 loader.inflector.inflect("llm_input_patch" => "LLMInputPatch")
 loader.inflector.inflect("before_llm_input" => "BeforeLLMInput")
-loader.collapse("#{__dir__}/phronomy/engine")
-# Loaded via require_relative before loader.setup; ignore to avoid Zeitwerk constant-name mismatch.
-loader.ignore("#{__dir__}/phronomy/ruby_llm_patches.rb")
-# Persistence backend conformance tests are explicit test support. Keep them out
-# of production eager-load so ordinary `require "phronomy"` never requires RSpec.
+# These responsibility directories do not add a public Ruby namespace.
+%w[common configuration engine execution generation runtime_composition].each do |directory|
+  loader.collapse("#{__dir__}/phronomy/#{directory}")
+end
+# Backend contracts, execution clients and implementations have separate source
+# directories, while keeping their existing feature namespace.
+%w[
+  llm_adapter/async llm_adapter/backends
+  vector_store/async vector_store/backends
+  embeddings/async embeddings/backends
+  storage/async
+  multi_agent/runtime_binding
+].each do |directory|
+  loader.collapse("#{__dir__}/phronomy/#{directory}")
+end
+# Agent responsibility directories retain the existing Agent constant names.
+%w[
+  lifecycle execution tool_execution runtime_binding
+  journal handoff recovery
+].each do |directory|
+  loader.collapse("#{__dir__}/phronomy/agent/#{directory}")
+end
+
+# A nested root is independent of its enclosing Ruby namespace. Keep existing
+# Phronomy::Workflow, Phronomy::WorkflowContext, and other canonical constants
+# beside the feature they belong to, without aliases or a new partial-load API.
+%w[
+  agent/api
+  workflow/execution
+  workflow/runtime_binding
+].each do |directory|
+  loader.push_dir("#{__dir__}/phronomy/#{directory}", namespace: Phronomy)
+end
+
+# These files wire composition, reopen namespaces, or patch a dependency.
+loader.ignore(
+  "#{__dir__}/phronomy/persistence/persistence.rb",
+  "#{__dir__}/phronomy/persistence/errors.rb",
+  "#{__dir__}/phronomy/persistence_composition/stores.rb",
+  "#{__dir__}/phronomy/runtime_composition/global_configuration.rb",
+  "#{__dir__}/phronomy/agent/composition",
+  "#{__dir__}/phronomy/runtime_composition/agent_defaults.rb",
+  "#{__dir__}/phronomy/runtime_composition/generation_defaults.rb",
+  "#{__dir__}/phronomy/runtime_composition/evaluation_defaults.rb",
+  "#{__dir__}/phronomy/runtime_composition/workflow_defaults.rb",
+  "#{__dir__}/phronomy/runtime_composition/multi_agent_defaults.rb",
+  "#{__dir__}/phronomy/runtime_composition/configuration_defaults.rb",
+  "#{__dir__}/phronomy/runtime_composition/global_runtime.rb",
+  "#{__dir__}/phronomy/runtime_composition/execution_defaults.rb"
+)
+# Persistence conformance support must never make production loading require RSpec.
 loader.ignore(
   "#{__dir__}/phronomy/testing/persistence_contract.rb",
   "#{__dir__}/phronomy/testing/persistence_contract"
 )
+# Failure contracts can define Persistence before ordinary framework loading.
+# Explicitly install its service methods without constructing a backend/Runtime.
+require_relative "phronomy/persistence/persistence"
+require_relative "phronomy/persistence/errors"
+loader.ignore("#{__dir__}/phronomy/tool/tool_error.rb")
+loader.ignore("#{__dir__}/phronomy/filter/filter_block_error.rb")
+loader.ignore("#{__dir__}/phronomy/output_parser/parse_error.rb")
+loader.ignore("#{__dir__}/phronomy/agent/agent_busy_error.rb")
+loader.ignore("#{__dir__}/phronomy/agent/agent_purged_error.rb")
+loader.ignore("#{__dir__}/phronomy/agent/stream_callback_error.rb")
+loader.ignore("#{__dir__}/phronomy/agent/handoff_error.rb")
+loader.ignore("#{__dir__}/phronomy/agent/agent_already_exists_error.rb")
 loader.setup
-
-require_relative "phronomy/version"
-require_relative "phronomy/token_usage"
-
-module Phronomy
-  class Error < StandardError; end
-  class ParseError < Error; end
-  class RecursionLimitError < Error; end
-  class ToolError < Error; end
-  class TimeoutError < Error; end
-  class ConfigurationError < Error; end
-  class HandoffError < Error; end
-
-  class TransportError < Error; end
-  class RateLimitError < TransportError; end
-  class AuthenticationError < TransportError; end
-  class ContextLengthError < Error; end
-  class CancellationError < Error; end
-
-  # Raised when a synchronous API would block the EventLoop control thread.
-  class EventLoopReentrancyError < Error; end
-
-  # Backward-compatible error class name for callers that still rescue the old
-  # scheduler-oriented exception. New code should use EventLoopReentrancyError.
-  class SchedulerReentrancyError < EventLoopReentrancyError; end
-
-  class RuntimeShutdownError < Error; end
-  class RuntimeShutdownReentrancyError < RuntimeShutdownError; end
-
-  class LowConfidenceError < Error
-    attr_reader :result
-
-    def initialize(result)
-      @result = result
-      super("Answer confidence #{result.confidence} is below the required threshold")
-    end
-  end
-
-  class FilterBlockError < Error
-    attr_reader :filter
-
-    def initialize(message, filter: nil)
-      super(message)
-      @filter = filter
-    end
-  end
-
-  class PoolShutdownError < Error; end
-  class BackpressureError < Error; end
-
-  class WorkflowContextOwnershipError < Error; end
-
-  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
-
-    def reset_runtime!(timeout: configuration.event_loop_stop_grace_seconds)
-      previous_grace = @configuration&.event_loop_stop_grace_seconds
-      result = Runtime.reset_default!(timeout: timeout)
-
-      new_configuration = Configuration.new
-      if previous_grace
-        new_configuration.event_loop_stop_grace_seconds = previous_grace
-      end
-      @configuration = new_configuration
-      result
-    end
-  end
-end
-
-# Shared Recovery primitives and Workflow Persistence F1 reconciliation.
-# Entity-specific Agent Recovery is loaded from lib/phronomy/agent.rb when the
-# Agent namespace is materialized.
-require_relative "phronomy/recovery"
-require_relative "phronomy/workflow_recovery"
+require_relative "phronomy/persistence/transaction"
+require_relative "phronomy/persistence_composition/stores"
+require_relative "phronomy/tool/tool_error"
+require_relative "phronomy/filter/filter_block_error"
+require_relative "phronomy/output_parser/parse_error"
+require_relative "phronomy/agent/agent_busy_error"
+require_relative "phronomy/agent/agent_purged_error"
+require_relative "phronomy/agent/stream_callback_error"
+require_relative "phronomy/agent/handoff_error"
+require_relative "phronomy/agent/agent_already_exists_error"
+
+require_relative "phronomy/runtime_composition/configuration_defaults"
+require_relative "phronomy/llm_adapter/token_usage"
+require_relative "phronomy/runtime_composition/global_configuration"
+require_relative "phronomy/runtime_composition/global_runtime"
+require_relative "phronomy/runtime_composition/execution_defaults"
+
+# Explicitly install the Agent namespace extensions even if its factory
+# contract was loaded first. Composition owns both concrete binding and the
+# run_once method definition; neither is required from Agent execution files.
+require_relative "phronomy/agent/api/agent"
+require_relative "phronomy/runtime_composition/agent_defaults"
+require_relative "phronomy/runtime_composition/multi_agent_defaults"
+require_relative "phronomy/runtime_composition/workflow_defaults"
+require_relative "phronomy/runtime_composition/generation_defaults"
+require_relative "phronomy/runtime_composition/evaluation_defaults"
+require_relative "phronomy/agent/composition/run_once"
+
+# Preserve ordinary boot loading of the existing recovery rules and comparisons
+# while giving each definition its owning domain.
+require_relative "phronomy/agent/recovery/recovery_rules"
+require_relative "phronomy/persistence/snapshot_comparison"

data/scripts/api_snapshot.rb

@@ -19,31 +19,49 @@ require_relative "../lib/phronomy"
 PUBLIC_API_ENTRIES = [
   # Stable
   Phronomy::Agent::Base,
-  Phronomy::Agent::ContextPolicy,
-  Phronomy::Agent::ContextPolicyInput,
-  Phronomy::Agent::ContextPolicyInput::Provenance,
-  Phronomy::Agent::ContextPolicyInput::InstructionItem,
-  Phronomy::Agent::ContextPolicyInput::KnowledgeItem,
-  Phronomy::Agent::ContextPolicyInput::ToolItem,
-  Phronomy::Agent::ContextPolicyInput::ConversationItem,
-  Phronomy::Agent::ContextPlan,
+  Phronomy::Agent::ReservedExecution,
+  Phronomy::Agent::ExecutionObservation,
+  Phronomy::Agent::KnowledgeItem,
+  Phronomy::Agent::Retention,
+  Phronomy::Agent::ExecutionExtensionState,
+  Phronomy::Agent::ControlRequest,
+  Phronomy::Context::ContextPolicy,
+  Phronomy::Context::ContextPolicyInput,
+  Phronomy::Context::ContextPolicyInput::Provenance,
+  Phronomy::Context::ContextPolicyInput::InstructionItem,
+  Phronomy::Context::ContextPolicyInput::KnowledgeItem,
+  Phronomy::Context::ContextPolicyInput::ToolItem,
+  Phronomy::Context::ContextPolicyInput::ConversationItem,
+  Phronomy::Context::ContextPlan,
   Phronomy::InvocationContext,
-  Phronomy::Agent::Context::Capability::Base,
+  Phronomy::Tool::Base,
   Phronomy::Workflow,
   Phronomy::WorkflowContext,
   Phronomy::Runnable,
-  Phronomy::Agent::Context::Instruction::PromptTemplate,
+  Phronomy::Context::PromptTemplate,
   # Beta
-  Phronomy::Agent::Handoff,
-  Phronomy::Agent::HandoffPolicy,
-  Phronomy::Agent::HandoffRunner,
+  Phronomy::Tool::Schema,
+  Phronomy::Tool::CallRequest,
+  Phronomy::Tool::Operation,
+  Phronomy::LLMAdapter::Base,
+  Phronomy::LLMAdapter::Request,
+  Phronomy::LLMAdapter::Message,
+  Phronomy::LLMAdapter::Response,
+  Phronomy::LLMAdapter::StreamChunk,
+  Phronomy::LLMAdapter::TokenUsage,
+  Phronomy::MultiAgent::Handoff,
+  Phronomy::MultiAgent::HandoffPolicy,
+  Phronomy::MultiAgent::HandoffRunner,
   Phronomy::MultiAgent::Orchestrator,
   Phronomy::MultiAgent::TeamCoordinator,
   Phronomy::Filter::Base,
   Phronomy::Filter::PromptInjectionFilter,
+  Phronomy::Storage::AsyncClient,
   Phronomy::VectorStore::Base,
+  Phronomy::VectorStore::AsyncClient,
   Phronomy::VectorStore::InMemory,
-  Phronomy::VectorStore::Embeddings::Base,
+  Phronomy::Embeddings::Base,
+  Phronomy::Embeddings::AsyncClient,
   Phronomy::Tracing::Base,
   Phronomy::Tracing::NullTracer,
   Phronomy::Tools::Mcp,
@@ -67,13 +85,15 @@ def snapshot_entry(klass)
     {
       "name" => klass.name,
       "type" => "module",
-      "public_instance_methods" => own_methods
+      "public_instance_methods" => own_methods,
+      "public_class_methods" => (klass.public_methods(false) - BASELINE_CLASS_METHODS).sort
     }
   else
     internal_context_methods = (klass == Phronomy::InvocationContext) ?
       %i[__bind_execution __execution_scope] : []
     instance_methods = (klass.public_instance_methods - BASELINE_INSTANCE_METHODS - internal_context_methods).sort
-    class_methods = (klass.public_methods(false) - BASELINE_CLASS_METHODS).sort
+    internal_class_methods = (klass == Phronomy::Storage::AsyncClient) ? %i[submit] : []
+    class_methods = (klass.public_methods(false) - BASELINE_CLASS_METHODS - internal_class_methods).sort
     {
       "name" => klass.name,
       "type" => "class",

data/scripts/storage_spi_snapshot.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require_relative "../lib/phronomy"
+
+# Explicit SPI 2 scope, independent of the Stable/Beta product API snapshot.
+# Private dispatch and domain composition helpers are deliberately excluded.
+surfaces = {
+  Phronomy::Persistence => Phronomy::Persistence.public_instance_methods(false).sort,
+  Phronomy::Storage::Backend => %i[initialize capabilities transaction resources view],
+  Phronomy::Storage::Backends::InMemory => %i[initialize capabilities],
+  Phronomy::Storage::View => %i[records streams blobs check!],
+  Phronomy::Storage::Resource => %i[initialize id kind attributes immutable_attributes indexes unique guard validate_attributes index_values],
+  Phronomy::Storage::Records => %i[resource insert read fetch replace delete scan delete_matching],
+  Phronomy::Storage::Streams => %i[resource append read head delete],
+  Phronomy::Storage::Blobs => %i[resource put_if_absent fetch exist?],
+  Phronomy::Storage::GuardRef => %i[initialize resource key],
+  Phronomy::Storage::Condition::RevisionIs => %i[initialize resource key expected],
+  Phronomy::Storage::Condition::StreamHeadIs => %i[initialize resource stream expected],
+  Phronomy::Storage::Condition::NoRows => %i[initialize resource index equals],
+  Phronomy::Storage::Entry::Record => %i[initialize key revision attributes record],
+  Phronomy::Storage::Entry::Stream => %i[initialize position id record],
+  Phronomy::Storage::Entry::Append => %i[initialize id record],
+  Phronomy::Storage::Entry::Blob => %i[initialize key bytes attributes],
+  Phronomy::Storage::UniqueConstraintError => %i[initialize resource constraint],
+  Phronomy::Storage::ConditionFailedError => %i[initialize condition]
+}
+snapshot = {spi_version: 2, capabilities: Phronomy::Storage::Backend::REQUIRED_CAPABILITIES,
+            surfaces: surfaces.to_h { |type, names| [type.name, names.sort.to_h { |name| [name, type.instance_method(name).parameters] }] }}
+json = JSON.pretty_generate(snapshot) + "\n"
+if ARGV.include?("--write")
+  File.write(File.expand_path("../spec/fixtures/storage_spi_v2_snapshot.json", __dir__), json)
+else
+  puts json
+end

data/sig/_private/phronomy/agent/settings.rbs

@@ -0,0 +1,19 @@
+module Phronomy
+  module Agent
+    class Settings
+      def self.install_provider: () { () -> Settings } -> void
+      def self.current: () -> Settings
+      def initialize: (llm_adapter: LLMAdapter::Base?, authorization_timeout: Numeric?, stream_callback_error_policy: Symbol) -> void
+      attr_accessor default_model: String?
+      attr_accessor before_llm_input: _BeforeLLMInputHook?
+      attr_accessor agent_store: Store?
+      attr_accessor llm_adapter: LLMAdapter::Base?
+      attr_accessor authorization_timeout: Numeric?
+      attr_accessor stream_callback_error_policy: Symbol
+    end
+  end
+
+  class Configuration
+    attr_reader __agent_settings: Agent::Settings
+  end
+end

data/sig/_private/phronomy/configuration/runtime_settings.rbs

@@ -0,0 +1,20 @@
+module Phronomy
+  # Internal Engine-facing settings; application-specific types do not belong here.
+  class RuntimeSettings
+    def self.install_provider: () { () -> RuntimeSettings } -> void
+    def self.current: () -> RuntimeSettings
+    def initialize: () -> void
+    attr_accessor logger: untyped
+    attr_accessor event_loop_stop_grace_seconds: Numeric
+    attr_accessor event_loop_starvation_threshold_seconds: Numeric?
+    attr_accessor event_loop_dispatch_threshold_seconds: Numeric?
+    attr_accessor offload_pool_size: Integer
+    attr_accessor offload_queue_size: Integer
+    attr_accessor authorization_pool_size: Integer
+    attr_accessor authorization_queue_size: Integer
+  end
+
+  class Configuration
+    attr_reader __runtime_settings: RuntimeSettings
+  end
+end

data/sig/_private/phronomy/llm_adapter/async/async_client.rbs

@@ -0,0 +1,10 @@
+# Framework-internal API. Loaded by -I sig; not exported by gem library loading.
+module Phronomy
+  module LLMAdapter
+    class AsyncClient
+      def initialize: (adapter: Base, ?pool: untyped, ?submitter: _ExecutionSubmitter) -> void
+      def complete_async: (Request request, ?cancellation_token: Concurrency::CancellationToken?, ?pool: untyped) -> TaskResult[Response]
+      def stream_async: (Request request, ?cancellation_token: Concurrency::CancellationToken?, ?pool: untyped) { (StreamChunk chunk) -> void } -> TaskResult[Response]
+    end
+  end
+end

data/sig/_private/phronomy/multi_agent/store.rbs

@@ -0,0 +1,8 @@
+module Phronomy
+  module MultiAgent
+    class Store
+      def self.install_configured_provider: () { () -> Store? } -> void
+      def self.configured: () -> Store?
+    end
+  end
+end

data/sig/_private/phronomy/persistence/storage_boundary.rbs

@@ -0,0 +1,7 @@
+module Phronomy
+  class Persistence
+    module StorageBoundary
+      def self.call: [T] () { () -> T } -> T
+    end
+  end
+end

data/sig/_private/phronomy/tool/settings.rbs

@@ -0,0 +1,13 @@
+module Phronomy
+  module Tool
+    class Settings
+      def self.install_provider: () { () -> Settings } -> void
+      def self.current: () -> Settings
+      attr_accessor max_result_size: Integer?
+    end
+  end
+
+  class Configuration
+    attr_reader __tool_settings: Tool::Settings
+  end
+end

data/sig/_private/phronomy/tracing/settings.rbs

@@ -0,0 +1,15 @@
+module Phronomy
+  module Tracing
+    class Settings
+      def self.install_provider: () { () -> Settings } -> void
+      def self.current: () -> Settings
+      def initialize: (tracer: Tracing::Base?) -> void
+      attr_accessor tracer: Tracing::Base?
+      attr_accessor trace_pii: bool
+    end
+  end
+
+  class Configuration
+    attr_reader __tracing_settings: Tracing::Settings
+  end
+end

data/sig/_private/phronomy/workflow/execution/workflow_settings.rbs

@@ -0,0 +1,13 @@
+module Phronomy
+  class WorkflowSettings
+    def self.install_provider: () { () -> WorkflowSettings } -> void
+    def self.current: () -> WorkflowSettings
+    def initialize: (recursion_limit: Integer) -> void
+    attr_accessor recursion_limit: Integer
+    attr_accessor workflow_store: _WorkflowStateRepository?
+  end
+
+  class Configuration
+    attr_reader __workflow_settings: WorkflowSettings
+  end
+end

data/sig/phronomy/agent/admission.rbs

@@ -0,0 +1,19 @@
+module Phronomy
+  module Agent
+    # Coordination owns reservation semantics; Agent owns the acceptance operation.
+    interface _AdmissionOwner
+      def admit: (Admission admission) -> void
+    end
+
+    class Admission
+      attr_reader agent_id: String
+      attr_reader execution_id: String
+      attr_reader correlation: Hash[String, json_value]?
+      def initialize: (persistence: Store, root: untyped, input: String,
+                       config: Hash[Symbol, untyped], preparation_metadata: Hash[String, untyped]) -> void
+      def accept: () -> nil
+      def accept_in: (::Phronomy::Persistence::Transaction scope) -> nil
+      def result: () -> [untyped, untyped]
+    end
+  end
+end

data/sig/phronomy/agent/execution_contract.rbs

@@ -0,0 +1,132 @@
+module Phronomy
+
+  module Agent
+    type execution_wiring = { ?phronomy_execution_participant: _ExecutionParticipant, ?phronomy_control_bindings: Array[_ControlCapability], ?phronomy_transfer_context: TransferContext, ?phronomy_admission: _AdmissionOwner, ?phronomy_reservation: Hash[String, json_value] }
+    type execution_result = { agent_id: String, execution_id: String, status: Symbol, result: String?, output: String?, error: Hash[String, json_value]? }
+
+    class ReservedExecution < Data
+      attr_reader agent_id: String
+      attr_reader execution_id: String
+      attr_reader correlation: Hash[String, json_value]?
+      def self.new: (agent_id: String, execution_id: String, ?correlation: Hash[String, json_value]?) -> instance
+    end
+
+    class ExecutionObservation < Data
+      attr_reader agent_id: String
+      attr_reader execution_id: String
+      attr_reader status: Symbol
+      attr_reader result: String?
+      attr_reader error: Hash[String, json_value]?
+      attr_reader reservation: ReservedExecution?
+      attr_reader transfer_receipt: Hash[String, json_value]?
+      attr_reader cancellation_requested: bool
+      def self.new: (agent_id: String, execution_id: String, status: Symbol, result: String?, error: Hash[String, json_value]?, reservation: ReservedExecution?, transfer_receipt: Hash[String, json_value]?, cancellation_requested: bool) -> instance
+      def self.from_result: (execution_result) -> instance
+      def absent?: () -> bool
+      def terminal?: () -> bool
+      def active?: () -> bool
+      def continuable?: () -> bool
+      def value!: () -> execution_result
+      def to_result: () -> execution_result
+    end
+
+    class ExecutionExtensionState < Data
+      attr_reader binding_key: String
+      attr_reader binding_version: Integer
+      attr_reader state_ref: String?
+      def self.new: (binding_key: String, binding_version: Integer, ?state_ref: String?) -> instance
+      def self.from_h: (Hash[String, json_value]) -> instance
+      def to_h: () -> Hash[String, json_value]
+    end
+
+    class KnowledgeItem < Data
+      attr_reader content: String
+      attr_reader metadata: Hash[String, json_value]
+      def self.new: (content: String, ?metadata: Hash[String, json_value]) -> instance
+    end
+
+    class Retention < Data
+      attr_reader agent_id: String
+      attr_reader execution_id: String?
+      attr_reader owner_key: String
+      def self.new: (agent_id: String, owner_key: String, ?execution_id: String?) -> instance
+      def to_h: () -> Hash[String, json_value]
+    end
+
+    class ControlRequest < Data
+      attr_reader target_agent_id: String
+      attr_reader responsibility: String
+      attr_reader selection: Hash[Symbol, bool]
+      attr_reader llm_call_id: String?
+      attr_reader tool_call_id: String?
+      def self.new: (target_agent_id: String, responsibility: String, selection: Hash[Symbol, bool], ?llm_call_id: String?, ?tool_call_id: String?) -> instance
+    end
+
+    interface _ControlCapability
+      def source_agent_id: () -> String
+      def request: (arguments: Hash[String, json_value], llm_call_id: String?, tool_call_id: String?) -> ControlRequest
+    end
+
+    interface _ExecutionParticipant
+      def binding: () -> ExecutionExtensionState
+      def guard_change: (ExecutionChange change, ::Phronomy::Persistence::Transaction scope) -> void
+      def change_evidence: (ExecutionChange change, ::Phronomy::Persistence::Transaction scope) -> json_value
+      def commit: (ExecutionChange change) -> void
+    end
+
+    class ExecutionChange
+      attr_reader kind: :dispatch | :terminal
+      attr_reader agent_id: String
+      attr_reader execution_id: String
+      attr_reader extension: ExecutionExtensionState?
+      attr_reader operations: Array[Store::AuthorizedOperation]
+      attr_reader control_request: ControlRequest?
+      attr_reader cancel_requested: bool
+      attr_reader recovery_required: bool
+      attr_reader durable_context: Hash[String, json_value]?
+      attr_reader correlation: Hash[String, json_value]?
+      attr_reader coordinator: ::Phronomy::Persistence
+      def finishing?: () -> bool
+      def prepare_in: (::Phronomy::Persistence::Transaction scope) -> nil
+      def commit_in: (::Phronomy::Persistence::Transaction scope, ?state: ExecutionExtensionState?, ?transfer_receipt: Hash[String, json_value]?, ?pending: bool) -> nil
+      def transfer_context: (::Phronomy::Persistence::Transaction scope) -> TransferContext
+    end
+
+    class TransferContext
+      attr_reader responsibility: String
+      attr_reader items: Array[Item]
+      def self.from_h: (Hash[String, json_value]) -> instance
+      def initialize: (responsibility: String, ?items: Array[Item]) -> void
+      def to_h: () -> Hash[String, json_value]
+      class Item < Data
+        attr_reader candidate_category: Symbol
+        attr_reader policy_category: Symbol
+        attr_reader role: Symbol?
+        attr_reader content: json_value
+        attr_reader content_format: Symbol
+        attr_reader tool_call_id: String?
+        attr_reader provenance: Provenance
+        attr_reader metadata: Hash[String, json_value]
+      end
+      class Provenance < Data
+        attr_reader origin_agent_id: String?
+        attr_reader origin_record_id: String?
+        attr_reader origin_execution_id: String?
+        attr_reader origin_llm_call_id: String?
+        attr_reader origin_tool_call_id: String?
+        attr_reader transfer_path: Array[String]
+        def forwarded_to: (String agent_id) -> instance
+        def to_h: () -> Hash[String, json_value]
+      end
+    end
+  end
+
+  class Persistence
+    class SaveOutcome < Data
+      attr_reader disposition: :committed | :not_committed | :unknown
+      attr_reader original_error: Exception?
+      attr_reader read_error: Exception?
+      def self.compare: [V] (before: V, after: V, ?original_error: Exception?) { () -> V } -> instance
+    end
+  end
+end

data/sig/phronomy/agent/execution_environment.rbs

@@ -0,0 +1,20 @@
+module Phronomy
+  module Agent
+    # Private composition port; serial ownership and routing are process-local.
+    class ExecutionEnvironment
+      def self.install_provider: (^() -> ExecutionEnvironment provider) -> untyped
+      def self.current: () -> ExecutionEnvironment
+      def registry: () -> untyped
+      def existing_registry: () -> untyped
+      def ownership: () -> untyped
+      def existing_ownership: () -> untyped
+      def executing?: () -> bool
+      def session_phase: (String id) -> Symbol?
+      def submit: [V] (**untyped options) { () -> V } -> TaskResult[V]
+      def submit_authorization: [V] (timeout: Numeric?, cancellation_token: Concurrency::CancellationToken?) { () -> V } -> TaskResult[V]
+      def build_agent_session: (invocation: untyped, ?resume_event: Symbol?, ?resume_phase: Symbol?) -> untyped
+      def build_tool_session: (invocation: untyped, parent_sink: untyped, ?resume_event: Symbol?, ?resume_phase: Symbol?) -> untyped
+      def register_session: (untyped session, completion: TaskResult[untyped]) -> untyped
+    end
+  end
+end