phronomy 0.27.0 → 0.29.0

data/lib/phronomy/agent/execution/{agent_invocation_session_builder.rb → invocation_actions.rb}

@@ -2,105 +2,29 @@
 
 module Phronomy
   module Agent
-    class AgentInvocationSessionBuilder
-      def self.build(
-        agent:,
-        input:,
-        config:,
-        approval_policy: nil,
-        approval_listener: nil,
-        mode: :invoke,
-        on_event: nil,
-        runtime: Phronomy::Runtime.instance
-      )
-        invocation = AgentInvocation.new(
-          agent: agent,
-          input: input,
-          config: config,
-          approval_policy: approval_policy,
-          approval_listener: approval_listener,
-          event_listener: on_event,
-          mode: mode,
-          execution_id: config.fetch(:execution_id)
-        )
-        build_session(
-          agent_invocation: invocation,
-          runtime: runtime,
-          mode: mode
-        )
-      end
-
-      def self.build_for_resume(
-        agent_invocation:,
-        resume_event:,
-        resume_phase:,
-        runtime: Phronomy::Runtime.instance
-      )
-        build_session(
-          agent_invocation: agent_invocation,
-          runtime: runtime,
-          mode: agent_invocation.mode,
-          resume_event: resume_event,
-          resume_phase: resume_phase
-        )
-      end
-
-      def self.build_session(
-        agent_invocation:,
-        runtime:,
-        mode:,
-        resume_event: nil,
-        resume_phase: nil
-      )
-        agent = agent_invocation.agent
-        event_sink = Phronomy::FSMSession::EventSink.new(
-          event_loop: runtime.event_loop
-        )
-        agent_invocation.bind_event_sink!(event_sink)
-        actions = build_entry_actions(
-          agent, runtime, mode: mode, event_sink: event_sink
-        )
-        phase_machine = Agent::PhaseMachineBuilder.new(entry_actions: actions).build
-        iterations = agent.class.max_iterations || 10
-
-        Phronomy::FSMSession.new(
-          context: agent_invocation,
-          event_sink: event_sink,
-          entry_point: InvocationTransitions::ENTRY_POINT,
-          phase_machine_class: phase_machine,
-          entry_actions: {},
-          auto_state_set: InvocationTransitions::AUTO_STATE_SET,
-          declared_states: InvocationTransitions::DECLARED_STATES,
-          wait_state_names: InvocationTransitions::WAIT_STATES,
-          external_events: InvocationTransitions::EXTERNAL_EVENTS,
-          recursion_limit: 12 + (iterations * 8),
-          event_loop: runtime.event_loop,
-          resume_event: resume_event,
-          resume_phase: resume_phase
-        )
-      end
-      private_class_method :build_session
-
-      def self.build_entry_actions(agent, runtime, mode:, event_sink:)
+    # Agent-owned entry operations and external-result delivery.
+    # Session construction and resource selection are supplied by the environment.
+    # @api private
+    class InvocationActions
+      def self.build_entry_actions(agent, environment, mode:, event_sink:)
         calling_action = if mode.to_sym == :stream
-          method(:calling_llm_stream_action).curry.call(agent, runtime, event_sink)
+          method(:calling_llm_stream_action).curry.call(agent, environment, event_sink)
         else
-          method(:calling_llm_action).curry.call(agent, runtime, event_sink)
+          method(:calling_llm_action).curry.call(agent, environment, event_sink)
         end
 
         {
           filtering_input: [method(:apply_prepared_input_action).curry.call(agent)],
-          building_context: [method(:build_runtime_chat_action).curry.call(agent)],
+          building_context: [method(:prepare_runtime_input_action).curry.call(agent)],
           calling_llm: [calling_action],
-          starting_tools: [method(:starting_tools_action).curry.call(runtime, event_sink)],
-          dispatching_tools: [method(:dispatching_tools_action).curry.call(runtime, event_sink)],
+          starting_tools: [method(:starting_tools_action).curry.call(environment, event_sink)],
+          dispatching_tools: [method(:dispatching_tools_action).curry.call(environment, event_sink)],
           recording_tool_results: [method(:recording_tool_results_action)],
           suspended: [method(:suspended_action)],
           output_filtering: [method(:output_filtering_action).curry.call(agent)],
           failed: [method(:failed_action)]
         }
       end
-      private_class_method :build_entry_actions
 
       def self.apply_prepared_input_action(_agent, invocation)
         invocation.input = invocation.config.fetch(:phronomy_filtered_input)
@@ -108,66 +32,25 @@ module Phronomy
       end
       private_class_method :apply_prepared_input_action
 
-      def self.build_runtime_chat_action(agent, invocation)
+      def self.prepare_runtime_input_action(agent, invocation)
         projection = invocation.config.fetch(:phronomy_runtime_projection)
-        invocation.chat = agent.send(:build_chat, model_config: projection.model_config)
-        agent.send(
-          :_apply_runtime_projection_to_chat,
-          invocation.chat,
-          projection,
-          invocation: invocation
-        )
-        invocation
-      end
-      private_class_method :build_runtime_chat_action
-
-      def self.install_tool_interceptors(chat, llm_call_id:)
-        # RubyLLM 2 records the complete assistant message before this callback,
-        # and checks its own approval gate afterwards. Capture here so Phronomy
-        # owns authorization and dispatch for the entire Tool batch.
-        chat.after_message do |message|
-          next unless message.tool_call?
-
-          raise build_tool_interception(chat, [], llm_call_id)
-        end
-      end
-      private_class_method :install_tool_interceptors
-
-      def self.build_tool_interception(chat, fallback_tool_calls, llm_call_id)
-        assistant_message = chat.messages.last
-        unless assistant_message&.respond_to?(:role) &&
-            assistant_message.role.to_sym == :assistant &&
-            assistant_message.respond_to?(:tool_calls)
-          raise Phronomy::Error,
-            "RubyLLM Tool callback fired before the complete assistant message was observable"
-        end
-
-        message_tool_calls = assistant_message.tool_calls
-        tool_calls = message_tool_calls.respond_to?(:values) ? message_tool_calls.values : Array(message_tool_calls)
-        tool_calls = Array(fallback_tool_calls) if tool_calls.empty?
-
-        ToolCallIntercepted.new(
-          tool_calls,
-          assistant_message: assistant_message,
-          assistant_outcome: ProviderCallOutcome.capture(assistant_message),
-          llm_call_id: llm_call_id
-        )
+        agent.send(:prepare_runtime_input, projection, invocation: invocation)
       end
-      private_class_method :build_tool_interception
+      private_class_method :prepare_runtime_input_action
 
-      def self.calling_llm_action(agent, runtime, event_sink, invocation)
-        prepare_and_start_llm_call(agent, runtime, event_sink, invocation, streaming: false)
+      def self.calling_llm_action(agent, environment, event_sink, invocation)
+        prepare_and_start_llm_call(agent, environment, event_sink, invocation, streaming: false)
         invocation
       end
       private_class_method :calling_llm_action
 
-      def self.calling_llm_stream_action(agent, runtime, event_sink, invocation)
-        prepare_and_start_llm_call(agent, runtime, event_sink, invocation, streaming: true)
+      def self.calling_llm_stream_action(agent, environment, event_sink, invocation)
+        prepare_and_start_llm_call(agent, environment, event_sink, invocation, streaming: true)
         invocation
       end
       private_class_method :calling_llm_stream_action
 
-      def self.prepare_and_start_llm_call(agent, runtime, event_sink, invocation, streaming:)
+      def self.prepare_and_start_llm_call(agent, environment, event_sink, invocation, streaming:)
         # Callback failure is recorded synchronously on EventLoop before its
         # explicit failure event is queued. Do not start a competing durable
         # follow-up operation from the same execution revision while that failure
@@ -183,7 +66,7 @@ module Phronomy
         else
           start_provider_call(
             agent,
-            runtime,
+            environment,
             event_sink,
             invocation,
             invocation.config.fetch(:phronomy_runtime_projection),
@@ -201,7 +84,7 @@ module Phronomy
       # @api private
       def self.start_prepared_provider_call(
         agent:,
-        runtime:,
+        environment:,
         event_sink:,
         invocation:,
         projection:,
@@ -209,7 +92,7 @@ module Phronomy
       )
         start_provider_call(
           agent,
-          runtime,
+          environment,
           event_sink,
           invocation,
           projection,
@@ -219,30 +102,22 @@ module Phronomy
       end
 
       def self.start_provider_call(
-        agent, runtime, event_sink, invocation, projection,
+        agent, environment, event_sink, invocation, projection,
         streaming:, replace_messages:
       )
         call_context = trace_handle = nil
         config = invocation.config
         agent.send(:check_cancellation!, config, "invocation cancelled before LLM call")
         if replace_messages
-          invocation.chat = agent.send(:build_chat, model_config: projection.model_config)
-          agent.send(
-            :_apply_runtime_projection_to_chat,
-            invocation.chat,
-            projection,
-            invocation: invocation
-          )
+          agent.send(:prepare_runtime_input, projection, invocation: invocation)
           invocation.config[:phronomy_runtime_projection] = projection
         end
 
-        call_context = invocation.begin_llm_call!(projection)
-        install_tool_interceptors(
-          invocation.chat,
-          llm_call_id: call_context.fetch(:llm_call_id)
-        )
-        message = projection.ask_message
-        chat = invocation.chat
+        request = agent.send(:build_llm_request, projection, invocation: invocation)
+        state = environment.registry.agent_execution_state(invocation.execution_id)
+        call_context = invocation.begin_llm_call!(projection,
+          llm_call_id: state&.execution&.metadata&.fetch(ExecutionMetadata::PENDING_LLM_ID_KEY, nil))
+        message = request.message
         trace_handle = Phronomy::Tracing::Automatic.start(
           "llm.call",
           input: message,
@@ -254,24 +129,26 @@ module Phronomy
           **agent.send(:_build_caller_meta, config)
         )
 
+        client = environment.build_llm_client(adapter: Phronomy::Agent::Settings.current.llm_adapter)
+        token = config[:cancellation_token]
+        llm_call_id = call_context.fetch(:llm_call_id)
         operation = if streaming
-          Phronomy.configuration.llm_adapter.stream_async(
-            chat, message, config: config
+          client.stream_async(
+            request, cancellation_token: config[:cancellation_token]
           ) do |chunk|
-            token = config[:cancellation_token]
             token&.raise_if_cancelled!("invocation cancelled during streaming")
             post_stream_chunk(
               event_sink,
-              call_context.fetch(:llm_call_id),
+              llm_call_id,
               chunk.content
             )
           end
         else
-          Phronomy.configuration.llm_adapter.complete_async(
-            chat, message, config: config
+          client.complete_async(
+            request, cancellation_token: config[:cancellation_token]
           )
         end
-        Phronomy::Agent::ExecutionRegistry.for(runtime.event_loop).supervise_agent_operation(
+        environment.registry.supervise_agent_operation(
           invocation.execution_id,
           operation
         )
@@ -319,20 +196,8 @@ module Phronomy
       private_class_method :observe_manifest_call
 
       def self.finish_provider_trace(trace_handle, response, error)
-        control_transfer = error.is_a?(ToolCallIntercepted)
-        trace_output = control_transfer ?
-          (error.assistant_outcome || error.assistant_message) : response
-        trace_error = control_transfer ? nil : error
-        usage_source = control_transfer ? error.assistant_message : response
-        usage = if usage_source&.respond_to?(:tokens)
-          Phronomy::TokenUsage.from_tokens(usage_source.tokens)
-        end
-        Phronomy::Tracing::Automatic.finish(
-          trace_handle,
-          output: trace_output,
-          usage: usage,
-          error: trace_error
-        )
+        Phronomy::Tracing::Automatic.finish(trace_handle,
+          output: response, usage: response&.usage, error: error)
       end
       private_class_method :finish_provider_trace
 
@@ -343,7 +208,7 @@ module Phronomy
           error: error,
           streaming: streaming
         )
-        event_type = if error && !error.is_a?(ToolCallIntercepted)
+        event_type = if error
           :llm_failed
         else
           :llm_completed
@@ -369,16 +234,16 @@ module Phronomy
       def self.post_session_event!(event_sink, event_type, payload)
         return if event_sink.post(event_type, payload)
 
-        Phronomy.configuration.logger&.warn(
+        Phronomy::RuntimeSettings.current.logger&.warn(
           "[Phronomy] Dropped late #{event_type.inspect} for " \
           "FSMSession #{event_sink.fsm_session_id}"
         )
       end
       private_class_method :post_session_event!
 
-      def self.starting_tools_action(runtime, parent_event_sink, invocation)
+      def self.starting_tools_action(environment, parent_event_sink, invocation)
         children = invocation.pending_tool_calls.map do |tool_call|
-          tool = invocation.chat.tools[tool_call.name.to_sym]
+          tool = invocation.tools[tool_call.name.to_sym]
           tool_invocation_id =
             ToolInvocation.semantic_id(
               execution_id: invocation.execution_id,
@@ -413,13 +278,9 @@ module Phronomy
         invocation.tool_invocations = children
 
         children.reject(&:terminal?).each do |child|
-          session = ToolInvocationSessionBuilder.build(
-            tool_invocation: child,
-            parent_event_sink: parent_event_sink,
-            runtime: runtime
-          )
+          session = environment.build_tool_session(invocation: child, parent_sink: parent_event_sink)
           register_child_session(
-            runtime,
+            environment,
             child,
             session,
             parent_event_sink
@@ -429,7 +290,7 @@ module Phronomy
       end
       private_class_method :starting_tools_action
 
-      def self.dispatching_tools_action(_runtime, parent_event_sink, invocation)
+      def self.dispatching_tools_action(_environment, parent_event_sink, invocation)
         invocation.config.fetch(:phronomy_execution_coordinator).prepare_tool_dispatch(
           invocation,
           event_sink: parent_event_sink
@@ -442,20 +303,19 @@ module Phronomy
       # preparation has been confirmed and applied by ExecutionCoordinator.
       # @api private
       def self.start_prepared_tool_dispatch(
-        runtime:,
+        environment:,
         event_sink:,
         invocation:
       )
         invocation.tool_invocations.select(&:authorized?).each do |child|
-          session = ToolInvocationSessionBuilder.build_for_resume(
-            tool_invocation: child,
-            parent_event_sink: event_sink,
+          session = environment.build_tool_session(
+            invocation: child,
+            parent_sink: event_sink,
             resume_event: :dispatch,
-            resume_phase: :authorized,
-            runtime: runtime
+            resume_phase: :authorized
           )
           begin
-            register_child_session(runtime, child, session, event_sink)
+            register_child_session(environment, child, session, event_sink)
           rescue => error
             child.mark_framework_failed!(error)
             event_sink.post(:tool_failed, {tool_invocation_id: child.id})
@@ -465,7 +325,7 @@ module Phronomy
         invocation
       end
 
-      def self.register_child_session(runtime, child, session, parent_event_sink)
+      def self.register_child_session(environment, child, session, parent_event_sink)
         completion = Phronomy::TaskResult.deferred(name: "tool-session:#{child.id}")
         completion.on_complete do |_result, error|
           next unless error
@@ -475,7 +335,7 @@ module Phronomy
           child.mark_framework_failed!(error)
           parent_event_sink.post(:tool_failed, {tool_invocation_id: child.id})
         end
-        runtime.event_loop.register(session, completion: completion)
+        environment.register_session(session, completion: completion)
       end
       private_class_method :register_child_session
 

data/lib/phronomy/agent/execution/invocation_transitions.rb

@@ -4,7 +4,7 @@ module Phronomy
   module Agent
     # Agent phase vocabulary and ordered external transitions. Both the phase
     # machine and FSMSession read this definition; Engine has no Agent policy.
-    # Automatic transition behavior and entry actions retain their own owners.
+    # Automatic and external transition priority belongs to this Agent contract.
     # @api private
     module InvocationTransitions
       ENTRY_POINT = :idle
@@ -81,6 +81,44 @@ module Phronomy
         end
         events.freeze
       end
+
+      AUTOMATIC_EVENTS = {
+        state_completed: [
+          {from: :idle, to: :filtering_input, guard: nil},
+          {from: :filtering_input, to: :building_context, guard: ->(ctx) { ctx.input_passed? }},
+          {from: :filtering_input, to: :blocked, guard: ->(ctx) { ctx.input_blocked? }},
+          {from: :building_context, to: :calling_llm, guard: nil},
+          {from: :starting_tools, to: :evaluating_tools, guard: nil},
+          {from: :evaluating_tools, to: :failed, guard: ->(ctx) { ctx.tool_batch_failed? }},
+          {from: :evaluating_tools, to: :blocked, guard: ->(ctx) { ctx.tool_batch_rejected? }},
+          {from: :evaluating_tools, to: :recording_tool_results, guard: ->(ctx) { ctx.tool_batch_completed? }},
+          {from: :evaluating_tools, to: :suspended, guard: ->(ctx) { ctx.approval_required? }},
+          {from: :evaluating_tools, to: :dispatching_tools, guard: ->(ctx) { ctx.ready_to_dispatch? }},
+          {from: :evaluating_tools, to: :waiting_for_tools, guard: nil},
+          {from: :recording_tool_results, to: :calling_llm, guard: nil},
+          {from: :output_filtering, to: :completed, guard: ->(ctx) { ctx.output_passed? }},
+          {from: :output_filtering, to: :blocked, guard: ->(ctx) { ctx.output_blocked? }}
+        ].each(&:freeze).freeze
+      }.freeze
+
+      EVENTS = AUTOMATIC_EVENTS.merge(EXTERNAL_EVENTS).freeze
+
+      def self.next_phase(phase, event, context)
+        definition = EVENTS.fetch(event.to_sym, []).find do |candidate|
+          candidate[:from] == phase.to_sym &&
+            allowed?(candidate, context)
+        end
+        definition&.fetch(:to)
+      end
+
+      def self.allowed?(definition, context)
+        guard = definition[:guard]
+        !guard || !!(context && guard.call(context))
+      end
+
+      def self.recursion_limit(max_iterations)
+        12 + ((max_iterations || 10) * 8)
+      end
     end
   end
 end

data/lib/phronomy/agent/execution/runtime_record_encoder.rb

@@ -24,18 +24,15 @@ module Phronomy
           outcome = item[:response]
           error = item[:error]
           llm_call_id = item.fetch(:llm_call_id).to_s
-          intercepted = error.is_a?(ToolCallIntercepted)
-          call_error = intercepted ? nil : error
+          tools_requested = outcome&.tool_call? || false
+          call_error = error
           output_ref = assistant_output_ref(tx, outcome)
           assistant_ref = assistant_message_ref(tx, outcome)
           error_ref = if call_error
-            tx.contents.put_json(
-              "class" => call_error.class.name,
-              "message" => call_error.message
-            )
+            tx.contents.put_json(Phronomy::Error.diagnostic(call_error))
           end
-          usage_ref = if outcome && !outcome.usage.empty?
-            tx.contents.put_json(json_value(outcome.usage))
+          usage_ref = if outcome && outcome.usage.to_h.values.any? { |value| !value.nil? }
+            tx.contents.put_json(json_value(outcome.usage.to_h))
           end
           call = LLMCallRecord.new(
             llm_call_id: llm_call_id,
@@ -50,7 +47,7 @@ module Phronomy
             completed_at: Time.now.utc.iso8601(6),
             metadata: {
               "streaming" => item[:streaming],
-              "tool_call_intercepted" => intercepted,
+              "tools_requested" => tools_requested,
               "assistant_outcome_captured" => !outcome.nil?,
               "tool_call_count" => outcome ? outcome.tool_calls.length : 0
             }
@@ -180,8 +177,8 @@ module Phronomy
       def assistant_message_metadata(outcome)
         calls = Array(outcome&.tool_calls)
         {
-          "tool_call_ids" => calls.map { |call| call.fetch("id").to_s },
-          "tool_names" => calls.map { |call| call.fetch("name").to_s }
+          "tool_call_ids" => calls.map(&:id),
+          "tool_names" => calls.map(&:name)
         }
       end
 

data/lib/phronomy/agent/execution_change.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Limited synchronous participant SPI. Agent owns all record mutations,
+    # revision checks and outcome publication. A participant owns its own
+    # transaction and passes only an opaque extension and a transfer receipt.
+    # @api public
+    class ExecutionChange
+      attr_reader :kind, :agent_id, :execution_id, :extension, :operations,
+        :control_request, :cancel_requested, :recovery_required, :durable_context,
+        :correlation, :coordinator
+
+      # Agent execution constructs changes; applications implement participants.
+      # @api private
+      def initialize(agent:, current:, root:, kind:, updated: nil, terminal: nil, config: {}, &write)
+        @agent, @store, @current, @root = agent, agent.persistence, current, root
+        @coordinator = @store.coordinator
+        @kind, @updated, @write = kind, updated, write
+        @agent_id, @execution_id = current.agent_id, current.execution_id
+        @extension = current.metadata["execution_extension"] && ExecutionExtensionState.from_h(current.metadata["execution_extension"])
+        @correlation = Phronomy::Values::Immutable.copy(current.metadata["reservation"])
+        @control_request = terminal&.handoff
+        @cancel_requested = terminal&.cancel_requested || false
+        error = terminal && (terminal.callback_failure&.to_stream_callback_error || terminal.source_error || terminal.block_error || terminal.invocation_error)
+        @control_request = nil if error || terminal&.phase == :suspended
+        @recovery_required = error.is_a?(Phronomy::ExecutionRehydrationRequiredError)
+        @finishing = kind == :terminal && !@recovery_required && (error || terminal.phase != :suspended)
+        @operations = Array(updated&.metadata&.fetch(ExecutionMetadata::TOOL_BATCH_METADATA_KEY, nil)).filter_map do |entry|
+          next unless entry.fetch("status") == "authorized"
+          Store::AuthorizedOperation.new(invocation_id: entry.fetch("tool_invocation_id"), name: entry.fetch("tool_name"),
+            arguments: Phronomy::Values::Immutable.copy(entry.fetch("arguments").compact))
+        end.freeze
+        ref = current.metadata["durable_context_ref"]
+        @durable_context = ref && Phronomy::Values::Immutable.copy(@store.contents.fetch_json(ref))
+        @participant = config[:phronomy_execution_participant]
+        @thread = Thread.current
+        validate_binding!
+      end
+
+      def finishing? = !!@finishing
+
+      # Runs current wiring and proves the complete captured change after an
+      # ambiguous response. A savepoint never grants publication permission.
+      # @api private
+      def perform
+        raise Phronomy::ConfigurationError, "Execution change is single-use" if @performed
+        @performed = true
+        perform_once
+      end
+
+      # @api private
+      def perform_once
+        if @participant
+          @participant.commit(self)
+        else
+          coordinator.atomic { |scope|
+            prepare_in(scope)
+            commit_in(scope)
+          }
+        end
+        unless @scope&.committed? && @result
+          raise Phronomy::Persistence::TransactionError, "Execution change has not committed its outer scope"
+        end
+        @result
+      rescue => error
+        raise unless @after && @scope&.outermost?
+        outcome = Phronomy::Persistence::SaveOutcome.compare(before: @before, after: @after, original_error: error) do
+          coordinator.atomic do |scope|
+            @participant&.guard_change(self, scope)
+            @store.guard_agents(scope, agent_ids: [agent_id])
+            snapshot(scope)
+          end
+        end
+        return @result if outcome.disposition == :committed
+        raise error if outcome.disposition == :not_committed
+        raise Phronomy::ExecutionRehydrationRequiredError, "Execution change outcome is unknown: #{(outcome.read_error || error).message}"
+      end
+
+      private :perform_once
+
+      # Capture the complete pre-state after the participant has acquired its
+      # ordered guards, before it changes its own records.
+      def prepare_in(scope)
+        raise Phronomy::Persistence::TransactionError, "Execution change belongs to another thread" unless @thread.equal?(Thread.current)
+        raise Phronomy::ConfigurationError, "Execution change is single-use" if @scope
+        @store.guard_agents(scope, agent_ids: [agent_id])
+        @before = snapshot(scope)
+        @cancel_requested ||= @store.cancellation_requested?(agent_id: agent_id, execution_id: execution_id, scope: scope)
+        @scope = scope
+        nil
+      end
+
+      # Must be called once in the participant's original synchronous context.
+      # No arbitrary execution setter or callback is exposed to the participant.
+      def commit_in(scope, state: extension, transfer_receipt: nil, pending: false)
+        raise Phronomy::Persistence::TransactionError, "Execution change belongs to another thread" unless @thread.equal?(Thread.current)
+        raise Phronomy::ConfigurationError, "Execution change must use its prepared scope exactly once" unless @scope.equal?(scope) && !@used
+        @used = true
+        if state && (!extension || state.binding_key != extension.binding_key || state.binding_version != extension.binding_version)
+          raise Phronomy::ConfigurationError, "Execution extension identity cannot change"
+        end
+        raise ArgumentError, "dispatch cannot choose a terminal outcome" if kind == :dispatch && (transfer_receipt || pending)
+        raise ArgumentError, "only a control request can transfer responsibility" if transfer_receipt && !control_request
+        raise ArgumentError, "pending work requires cancellation or recovery" if pending && !(cancel_requested || recovery_required)
+        @store.participate(scope) do |records|
+          records.assert_agent_watermark!(agent_id: agent_id, agent_revision: @root.agent_revision, journal_position: @root.journal_position)
+          observed = records.executions.load(execution_id)
+          unless observed.agent_id == agent_id && observed.execution_revision == @current.execution_revision
+            raise Phronomy::Persistence::StateConflictError, "Execution changed before participation"
+          end
+          if kind == :dispatch
+            updated = attach_state(@updated, state)
+            records.executions.save(execution_id, expected_revision: @current.execution_revision, execution: updated)
+            @result = updated
+          else
+            @result = @write.call(records, state, transfer_receipt, pending)
+          end
+        end
+        @after = snapshot(scope)
+        nil
+      end
+
+      # Finalized input material; policies are interpreted by the participant.
+      def transfer_context(scope)
+        raise ArgumentError, "there is no control request" unless control_request
+        @store.participate(scope) do |records|
+          manifest = SavedContextReader.manifest_from_ref(@agent, @current.metadata.fetch("manifest_ref"))
+          TransferProjection.new.build(request: control_request, manifest: manifest, persistence: records, source_agent: @agent)
+        end
+      end
+
+      private
+
+      def validate_binding!
+        return unless extension
+        binding = @participant&.binding
+        unless binding && binding.binding_key == extension.binding_key && binding.binding_version == extension.binding_version
+          raise Phronomy::ExecutionRehydrationRequiredError, "Execution #{execution_id} needs participant #{extension.binding_key}@#{extension.binding_version}"
+        end
+      end
+
+      def attach_state(execution, state)
+        execution.with(execution_revision: execution.execution_revision,
+          metadata: execution.metadata.merge("execution_extension" => state&.to_h).compact)
+      end
+
+      def snapshot(scope)
+        agent_state = @store.participate(scope) do |records|
+          root = records.agents.load(agent_id)
+          execution = records.executions.load(execution_id)
+          journal = records.journals.read(agent_id, after: @root.journal_position,
+            limit: [root.journal_position - @root.journal_position, 1].max)
+          ref = execution.metadata.dig("execution_extension", "state_ref")
+          [root.to_h, execution.to_h, journal.map(&:to_h), ref && records.contents.fetch_json(ref), records.cancellations.requested?(agent_id, execution_id)]
+        end
+        [agent_state, @participant&.change_evidence(self, scope)]
+      end
+    end
+  end
+end