phronomy 0.27.0 → 0.28.0

data/lib/phronomy/workflow/runtime_binding/workflow_phase_machine_builder.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "state_machines"
+require_relative "../execution/workflow_action_rules"
+
+module Phronomy
+  # Builds the anonymous state-machine Class used by WorkflowRunner.
+  #
+  # This class compiles Workflow topology into state_machines declarations.
+  # It intentionally does not await Tasks, register completion callbacks,
+  # cancel external work, or interpret application event payloads.
+  #
+  # @api private
+  class WorkflowPhaseMachineBuilder
+    def initialize(
+      entry_point:,
+      declared_states:,
+      wait_state_names:,
+      external_events:,
+      entry_actions:,
+      auto_transitions:,
+      exit_actions:
+    )
+      @entry_point = entry_point
+      @declared_states = declared_states
+      @wait_state_names = wait_state_names
+      @external_events = external_events.transform_values { |items| items.map { |transition| convert_transition(transition) } }
+      @entry_actions = entry_actions
+      @auto_transitions = auto_transitions.map { |transition| convert_transition(transition) }
+      @exit_actions = exit_actions
+    end
+
+    def build
+      entry = @entry_point
+      all_states = (@declared_states + @wait_state_names + [FSMProtocol::FINISH]).uniq
+      auto_transitions = @auto_transitions
+      external_events = @external_events
+      entry_actions = @entry_actions
+      exit_actions = @exit_actions
+      condition_builder = method(:build_transition_condition)
+      entry_callback_builder = method(:build_entry_callback)
+      exit_callback_builder = method(:build_exit_callback)
+      transition_callback = build_transition_action_callback
+
+      Class.new do
+        attr_accessor(
+          :context,
+          :current_event,
+          :selected_transition_action,
+          :selected_transition_metadata
+        )
+
+        state_machine :phase, initial: entry do
+          all_states.each { |state_name| state state_name }
+
+          event :state_completed do
+            auto_transitions.each do |transition_definition|
+              transition(
+                transition_definition[:from] => transition_definition[:to],
+                :if => condition_builder.call(transition_definition)
+              )
+            end
+          end
+
+          external_events.each do |event_name, transitions|
+            event event_name do
+              transitions.each do |transition_definition|
+                transition(
+                  transition_definition[:from] => transition_definition[:to],
+                  :if => condition_builder.call(transition_definition)
+                )
+              end
+            end
+          end
+
+          entry_actions.each do |state_name, callables|
+            callables.each do |callable|
+              after_transition(
+                to: state_name,
+                &entry_callback_builder.call(callable, state_name)
+              )
+            end
+          end
+
+          # Both source exit callbacks and the transition action are
+          # before_transition callbacks. Register exits first to preserve the
+          # required exit -> transition action -> entry ordering.
+          exit_actions.each do |state_name, callables|
+            callables.each do |callable|
+              before_transition(
+                from: state_name,
+                &exit_callback_builder.call(callable, state_name)
+              )
+            end
+          end
+
+          before_transition(&transition_callback)
+        end
+      end
+    rescue => error
+      raise ArgumentError, "Failed to build phase machine: #{error.message}"
+    end
+
+    private
+
+    def convert_transition(transition)
+      destination = transition[:to]
+      destination = FSMProtocol::FINISH if destination == Workflow::Completion::FINISH
+      transition.merge(to: destination)
+    end
+
+    def build_transition_condition(transition_definition)
+      guard = transition_definition[:guard]
+      action = transition_definition[:action]
+      metadata = {
+        from: transition_definition[:from],
+        event: transition_definition[:event],
+        to: public_destination(transition_definition[:to])
+      }.freeze
+
+      ->(machine) {
+        matched = WorkflowActionRules.allowed?(guard, machine.context, machine.current_event)
+        if matched
+          machine.selected_transition_action = action
+          machine.selected_transition_metadata = metadata
+        end
+        matched
+      }
+    end
+
+    def build_transition_action_callback
+      ->(machine) {
+        machine.context = WorkflowActionRules.transition(
+          machine.selected_transition_action, machine.context, machine.current_event,
+          metadata: machine.selected_transition_metadata || {}
+        )
+      }
+    end
+
+    def build_entry_callback(callable, state_name)
+      ->(machine) {
+        machine.context = WorkflowActionRules.apply_entry(callable, machine.context, state_name)
+      }
+    end
+
+    def build_exit_callback(callable, state_name)
+      ->(machine) { WorkflowActionRules.exit(callable, machine.context, state_name) }
+    end
+
+    def public_destination(destination)
+      return Workflow::Completion::FINISH if destination == FSMProtocol::FINISH
+
+      destination
+    end
+  end
+end

data/lib/phronomy/workflow/{execution → runtime_binding}/workflow_terminal_policy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Interprets durable Workflow results for the shared FSM terminal gate.
+  # Translates classified Workflow outcomes into shared FSM terminal decisions.
   # The session owns pending state; Runner owns persistence and reconciliation.
   # @api private
   class WorkflowTerminalPolicy
@@ -23,14 +23,14 @@ module Phronomy
       result = event.payload
       case result.outcome
       when :success
-        FSMProtocol::TerminalDecision.new(action: :complete, error: nil)
+        Phronomy::TerminalDecision.new(action: :complete, error: nil)
       when :known_failure
-        FSMProtocol::TerminalDecision.new(
+        Phronomy::TerminalDecision.new(
           action: :fail,
           error: result.error || Phronomy::Error.new("Workflow terminal persistence failed")
         )
       when :outcome_unknown
-        FSMProtocol::TerminalDecision.new(action: :retire, error: result.error)
+        Phronomy::TerminalDecision.new(action: :retire, error: result.error)
       else
         raise Phronomy::Error,
           "unknown Workflow terminal persistence outcome: #{result.outcome.inspect}"

data/lib/phronomy.rb

@@ -13,19 +13,29 @@ 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")
 # These responsibility directories do not add a public Ruby namespace.
-%w[common configuration engine generation llm_contract recovery].each do |directory|
+%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[
-  context_contract lifecycle execution tool_execution context_assembly
+  lifecycle execution tool_execution runtime_binding
   journal handoff recovery
 ].each do |directory|
   loader.collapse("#{__dir__}/phronomy/agent/#{directory}")
@@ -36,44 +46,75 @@ end
 # beside the feature they belong to, without aliases or a new partial-load API.
 %w[
   agent/api
-  agent/lifecycle_contract
-  filter/contract
-  output_parser/contract
-  persistence/api
-  tool/contract
   workflow/execution
-  workflow/storage_contract
-  multi_agent/storage_contract
+  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/configuration/global_configuration.rb",
+  "#{__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/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/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_contract/token_usage"
-require_relative "phronomy/configuration/global_configuration"
+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"
 
-# Load the common recovery vocabulary during ordinary application loading.
-require_relative "phronomy/recovery/recovery"
+# 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::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/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