phronomy 0.26.0 → 0.28.0

data/lib/phronomy/multi_agent/handoff_participant.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Phronomy
+  module MultiAgent
+    # Routing and Agent terminal state share the same outer transaction. This
+    # participant sees public semantic values only, never Agent records.
+    # @api private
+    class HandoffParticipant
+      def initialize(persistence:, main_agent_id:, expected_revision:)
+        @persistence, @main_agent_id, @expected_revision = persistence, main_agent_id, expected_revision
+      end
+
+      def binding
+        Phronomy::Agent::ExecutionExtensionState.new(binding_key: "phronomy.handoff", binding_version: 1)
+      end
+
+      def guard_change(change, scope)
+        @persistence.participate(scope) { |records| records.handoff_states.load_locked(@main_agent_id) }
+        ids = [@main_agent_id, change.agent_id, change.control_request&.target_agent_id].compact
+        @persistence.agent_store.guard_agents(scope, agent_ids: ids)
+      end
+
+      def change_evidence(change, scope)
+        state = @persistence.participate(scope) { |records| records.handoff_states.load(@main_agent_id) }
+        ids = [@main_agent_id, change.agent_id, change.control_request&.target_agent_id].compact.uniq.sort
+        [state&.to_h, ids.map { |id| @persistence.agent_store.retained_references(agent_id: id, scope: scope).map(&:to_h) }]
+      end
+
+      def commit(change)
+        @persistence.coordinator.atomic do |scope|
+          guard_change(change, scope)
+          change.prepare_in(scope)
+          @persistence.participate(scope) do |records|
+            routing = records.handoff_states.load(@main_agent_id)
+            unless routing && routing.active_agent_id == change.agent_id
+              raise Phronomy::Persistence::StateConflictError, "Handoff no longer owns this execution"
+            end
+            receipt = nil
+            if change.kind == :terminal && change.control_request
+              if Array(routing.metadata["cancelled_execution_ids"]).include?(change.execution_id) || change.cancel_requested
+                raise Phronomy::CancellationError, "Handoff Source turn was cancelled"
+              end
+              unless routing.handoff_revision == @expected_revision
+                raise Phronomy::Persistence::StateConflictError, "Handoff routing changed before Source transfer"
+              end
+              request = change.control_request
+              context = change.transfer_context(scope)
+              ref = records.contents.put_json(context.to_h)
+              target_id = "handoff-target-#{Digest::SHA256.hexdigest([change.execution_id, request.target_agent_id].join("\0"))}"
+              definition = @persistence.agent_store.definition(agent_id: request.target_agent_id, scope: scope)
+              retain(scope, change.agent_id, change.execution_id)
+              retain(scope, request.target_agent_id, target_id)
+              receipt = {"target_agent_id" => request.target_agent_id, "target_execution_id" => target_id,
+                         "context_ref" => ref, "owner_key" => "handoff:#{@main_agent_id}"}.freeze
+              ids = (Array(routing.metadata["retained_agent_ids"]) + [change.agent_id, request.target_agent_id]).uniq.sort
+              transfer = routing.with(active_agent_id: request.target_agent_id, active_handoff_context_ref: ref,
+                phase: "target_pending", pending_source_execution_id: change.execution_id, pending_target_execution_id: target_id,
+                metadata: routing.metadata.merge("target_definition" => definition.transform_keys(&:to_s),
+                  "source_agent_id" => change.agent_id, "retained_agent_ids" => ids))
+              records.handoff_states.save(@main_agent_id, expected_revision: routing.handoff_revision, state: transfer)
+            elsif change.finishing? && routing.phase != "stable" && routing.pending_target_execution_id == change.execution_id
+              records.handoff_states.save(@main_agent_id, expected_revision: routing.handoff_revision, state: routing.with(phase: "stable"))
+            end
+            change.commit_in(scope, transfer_receipt: receipt)
+          end
+        end
+      end
+
+      private
+
+      def retain(scope, id, execution_id)
+        @persistence.agent_store.retain(Phronomy::Agent::Retention.new(agent_id: id, execution_id: execution_id,
+          owner_key: "handoff:#{@main_agent_id}"), scope: scope)
+      end
+    end
+  end
+end

data/lib/phronomy/{agent → multi_agent}/handoff_policy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module MultiAgent
     class HandoffPolicy
       CATEGORIES = %i[current_request history knowledge tool_exchanges].freeze
       MODES = %i[required forbidden selectable].freeze

data/lib/phronomy/multi_agent/handoff_runner.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Phronomy
+  module MultiAgent
+    # Durable turn coordination using Agent's public exact-execution operations.
+    # @api public
+    class HandoffRunner
+      MAX_HANDOFFS = 20
+      attr_reader :main_agent, :handoffs
+
+      def initialize(main_agent:, persistence:, handoffs: [])
+        @main_agent, @persistence, @handoffs = main_agent, persistence, Array(handoffs).freeze
+        raise ArgumentError, "handoffs must contain MultiAgent::Handoff" unless @handoffs.all? { |edge| edge.is_a?(Handoff) }
+        @agents = ([main_agent] + @handoffs.flat_map { |edge| [edge.source_agent, edge.target_agent] }).uniq.to_h { |agent| [agent.agent_id, agent] }.freeze
+        unless @agents.values.all? { |agent| agent.persistence.equal?(@persistence.agent_store) }
+          raise Phronomy::ConfigurationError, "Handoff graph and coordination store must share the same Agent store"
+        end
+        if @handoffs.group_by { |edge| [edge.source_agent.agent_id, edge.target_agent.agent_id] }.any? { |_, edges| edges.size > 1 }
+          raise ArgumentError, "Duplicate Source/Target Handoff edges"
+        end
+        @bindings = @handoffs.group_by { |edge| edge.source_agent.agent_id }.transform_values { |edges| edges.map { |edge| HandoffCapabilityFactory.build(edge) }.freeze }.freeze
+        @environment = ExecutionEnvironment.current
+        @admissions = @environment.admissions
+      end
+
+      def invoke(input, config: {})
+        raise Phronomy::EventLoopReentrancyError, "HandoffRunner#invoke cannot block EventLoop" if Phronomy::WaitPolicy.blocking_forbidden?
+        raise Phronomy::RuntimeShutdownError, "HandoffRunner belongs to a previous Runtime" unless @environment.current?
+        trace = Phronomy::Tracing::Automatic.start("multi_agent.turn", input: input, main_agent_id: main_agent.agent_id)
+        error = result = nil
+        config = config.merge(cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new)
+        @admissions.admit!(main_agent)
+        admitted = true
+        state = load_state
+        count = 0
+        loop do
+          active = @agents.fetch(state.active_agent_id) { raise Phronomy::ExecutionRehydrationRequiredError, "Handoff graph lacks active Agent #{state.active_agent_id}" }
+          context = state.active_handoff_context_ref && Phronomy::Agent::TransferContext.from_h(@persistence.contents.fetch_json(state.active_handoff_context_ref))
+          owner = {"kind" => "handoff", "main_agent_id" => main_agent.agent_id}.freeze
+          wiring = config.merge(phronomy_control_bindings: @bindings.fetch(active.agent_id, []), phronomy_transfer_context: context,
+            phronomy_execution_participant: HandoffParticipant.new(persistence: @persistence, main_agent_id: main_agent.agent_id, expected_revision: state.handoff_revision),
+            phronomy_reservation: owner, phronomy_admission: ReservedChildAdmission.new(persistence: @persistence, owner: owner))
+          result = if state.phase == "stable"
+            unfinished = @persistence.agent_store.active_executions(agent_id: active.agent_id)
+            if unfinished.empty?
+              active.invoke(input, config: wiring)
+            else
+              exact = unfinished.fetch(0)
+              unless unfinished.size == 1 && exact.reservation&.correlation == owner
+                raise Phronomy::Persistence::StateConflictError, "Active execution belongs to another turn"
+              end
+              wiring[:cancellation_token].cancel! if Array(state.metadata["cancelled_execution_ids"]).include?(exact.execution_id)
+              active.resume_async(exact.execution_id, config: wiring).wait_result
+            end
+          else
+            source = @persistence.agent_store.execution_identity(state.pending_source_execution_id)
+            unless @handoffs.any? { |edge| edge.source_agent.agent_id == source.agent_id && edge.target_agent.agent_id == state.active_agent_id }
+              raise Phronomy::ExecutionRehydrationRequiredError, "Handoff graph lacks committed Source/Target edge"
+            end
+            unless active.class.agent_definition == state.metadata.fetch("target_definition").transform_keys(&:to_sym)
+              raise Phronomy::ConfigurationError, "Handoff Target definition mismatch"
+            end
+            wiring[:cancellation_token].cancel! if Array(state.metadata["cancelled_execution_ids"]).include?(state.pending_target_execution_id)
+            reservation = Phronomy::Agent::ReservedExecution.new(agent_id: active.agent_id, execution_id: state.pending_target_execution_id, correlation: owner)
+            active.start_reserved_async(reservation: reservation, input: context.responsibility, config: wiring).wait_result
+          end
+          observed = @persistence.agent_store.observe_execution(agent_id: active.agent_id, execution_id: result.fetch(:execution_id))
+          if observed.status == :handed_off
+            count += 1
+            raise Phronomy::HandoffError, "Exceeded maximum Handoffs in one turn" if count > MAX_HANDOFFS
+            state = @persistence.handoff_states.load(main_agent.agent_id)
+            next
+          end
+          raise Phronomy::ExecutionRehydrationRequiredError, "Handoff requires approval or recovery" if observed.active?
+          observed.value!
+          return result.reject { |key, _| key.to_s.start_with?("_phronomy_") || key == :handoff_request }.merge(agent: active)
+        end
+      rescue Phronomy::CancellationError => caught
+        error = caught
+        cancel(state.pending_source_execution_id) if state && state.phase != "stable"
+        raise
+      rescue => caught
+        error = caught
+        raise
+      ensure
+        @admissions.release!(main_agent) if admitted
+        Phronomy::Tracing::Automatic.finish(trace, output: result && result[:output], error: error) if trace
+      end
+
+      def cancel(execution_id)
+        raise Phronomy::EventLoopReentrancyError, "HandoffRunner#cancel cannot block EventLoop" if Phronomy::WaitPolicy.blocking_forbidden?
+        leaf = intended = nil
+        begin
+          @persistence.transaction do |records, scope|
+            routing = records.handoff_states.load_locked(main_agent.agent_id)
+            # All leaf reads occur after the same guard used by target admission.
+            leaf = @persistence.handoff_leaf(execution_id, main_agent_id: main_agent.agent_id, scope: scope)
+            next if leaf.terminal?
+            unless routing && (leaf.absent? ? routing.pending_target_execution_id == leaf.execution_id : routing.active_agent_id == leaf.agent_id)
+              raise Phronomy::Persistence::StateConflictError, "Handoff no longer owns the requested turn"
+            end
+            @persistence.agent_store.guard_agents(scope, agent_ids: [main_agent.agent_id, leaf.agent_id])
+            @persistence.agent_store.request_cancellation(agent_id: leaf.agent_id, execution_id: leaf.execution_id, scope: scope) unless leaf.absent?
+            ids = (Array(routing.metadata["cancelled_execution_ids"]) + [leaf.execution_id]).uniq
+            intended = routing.with(phase: leaf.absent? ? "stable" : routing.phase, metadata: routing.metadata.merge("cancelled_execution_ids" => ids))
+            records.handoff_states.save(main_agent.agent_id, expected_revision: routing.handoff_revision, state: intended)
+          end
+        rescue => failure
+          raise unless intended
+          proof = Phronomy::Persistence::SaveOutcome.compare(before: nil, after: [intended.to_h, true], original_error: failure) do
+            @persistence.transaction do |records, scope|
+              current = records.handoff_states.load_locked(main_agent.agent_id)
+              cancelled = leaf.absent? || @persistence.agent_store.cancellation_requested?(agent_id: leaf.agent_id, execution_id: leaf.execution_id, scope: scope)
+              [current&.to_h, cancelled]
+            end
+          end
+          raise failure unless proof.disposition == :committed
+        end
+        return leaf.to_result if leaf.terminal?
+        @agents[leaf.agent_id]&.cancel_async(leaf.execution_id)&.wait_result if leaf.active?
+        {execution_id: leaf.execution_id, cancellation_requested: true}.freeze
+      end
+
+      def result(execution_id)
+        @persistence.handoff_result(execution_id, main_agent_id: main_agent.agent_id)
+      end
+
+      # Explicit history removal releases references before Agent purge is allowed.
+      def forget_history!
+        @persistence.forget_handoff(main_agent.agent_id)
+      end
+
+      private
+
+      def load_state
+        state = @persistence.handoff_states.load(main_agent.agent_id)
+        return state if state
+        now = Time.now.utc.iso8601(6)
+        initial = HandoffState.new(main_agent_id: main_agent.agent_id, handoff_revision: 1,
+          active_agent_id: main_agent.agent_id, active_handoff_context_ref: nil, phase: "stable",
+          pending_source_execution_id: nil, pending_target_execution_id: nil,
+          created_at: now, updated_at: now, metadata: {"retained_agent_ids" => [main_agent.agent_id]})
+        @persistence.transaction do |records, scope|
+          @persistence.agent_store.retain(Phronomy::Agent::Retention.new(agent_id: main_agent.agent_id, owner_key: "handoff:#{main_agent.agent_id}"), scope: scope)
+          records.handoff_states.save(main_agent.agent_id, expected_revision: nil, state: initial)
+        end
+      rescue => error
+        confirmed = @persistence.handoff_states.load(main_agent.agent_id)
+        raise error unless confirmed
+        confirmed
+      end
+    end
+  end
+end

data/lib/phronomy/{agent → multi_agent}/handoff_state.rb

@@ -3,7 +3,7 @@
 require "time"
 
 module Phronomy
-  module Agent
+  module MultiAgent
     # Immutable current-format semantic record; contains no Runtime handles.
     # @api private
     class HandoffState
@@ -14,7 +14,7 @@ module Phronomy
         source = values.transform_keys(&:to_s)
         raise ArgumentError, "HandoffState schema mismatch" unless source.keys.sort == ATTRIBUTES.sort
         canonical = Phronomy::CanonicalJSON.load(Phronomy::CanonicalJSON.dump(source))
-        ATTRIBUTES.each { |key| instance_variable_set("@#{key}", Phronomy::Agent::Immutable.copy(canonical.fetch(key))) }
+        ATTRIBUTES.each { |key| instance_variable_set("@#{key}", Phronomy::Values::Immutable.copy(canonical.fetch(key))) }
         raise ArgumentError, "missing main_agent_id" if main_agent_id.to_s.empty?
         raise ArgumentError, "invalid handoff_revision" unless handoff_revision.is_a?(Integer) && handoff_revision >= 0
         raise ArgumentError, "invalid metadata" unless metadata.is_a?(Hash)

data/lib/phronomy/multi_agent/orchestrator.rb

@@ -9,32 +9,42 @@ module Phronomy
       ParallelChild = Data.define(:index, :agent, :input, :config)
       private_constant :ParallelChild
 
-      # Own one live cancellation token shared with this invocation's static
-      # children, including when Recovery reconstructs the invocation.
-      # @api private
-      def __invocation_config(config)
-        config.merge(cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new)
+      attr_reader :coordination_store
+
+      def self.create(coordination_store: nil, **options, &block)
+        new(coordination_store: coordination_store, **options, &block)
       end
 
-      # Resumes retained static child coordination with current class wiring.
-      # @api public
-      def resume(execution_id, config: {})
-        if Phronomy::Runtime.in_event_loop_context?
-          raise Phronomy::EventLoopReentrancyError, "Orchestrator#resume cannot block EventLoop"
+      def self.load(agent_id, persistence:, coordination_store:, **options, &block)
+        participant = DurableSubagentCoordinator.new(agent_class: self, persistence: coordination_store)
+        super(agent_id, persistence: persistence, execution_wiring: {phronomy_execution_participant: participant}, **options, &block)
+      end
+
+      def initialize(coordination_store: nil, execution_wiring: {}, **options, &block)
+        @coordination_store = coordination_store || execution_wiring[:phronomy_execution_participant]&.persistence || Phronomy::MultiAgent::Store.configured
+        super(execution_wiring: execution_wiring, **options, &block)
+        if @coordination_store && !@coordination_store.agent_store.equal?(persistence)
+          raise Phronomy::ConfigurationError, "Orchestrator stores must share the same Agent store"
         end
-        execution = persistence.executions.load(execution_id)
-        raise Phronomy::Persistence::ConflictError, "Parent execution owner mismatch" unless execution.agent_id == agent_id
-        input = persistence.contents.fetch_text(execution.metadata.fetch("current_input_ref"))
-        result = Phronomy::Agent::ExactExecution.start(agent: self, execution_id: execution_id, input: input, config: config).wait_result
-        raise Phronomy::Agent::RecoverySupport.error_from_failure(result[:error]) if result[:error]
-        result
+        @participant = @coordination_store && DurableSubagentCoordinator.new(agent_class: self.class, persistence: @coordination_store)
+      end
+
+      # Current composition, never serialized in an execution record.
+      def __invocation_config(config)
+        if !self.class.registered_subagents.empty? && !@participant
+          raise Phronomy::ConfigurationError, "Durable subagents require coordination_store:"
+        end
+        config.merge(cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new,
+          phronomy_execution_participant: @participant).compact
       end
 
       def self.subagent(name, agent_class, on_error: :raise, inherit_knowledge: true)
         # A subagent Tool is logically asynchronous: ToolInvocation starts the
         # child Agent and resumes when its completion TaskResult settles. It must not
         # occupy an OffloadPool worker while waiting for the child.
-        tool_class = Class.new(Phronomy::Tools::Agent) do
+        tool_class = Class.new(Phronomy::Tool::Base) do
+          execution_mode :cooperative
+          param :input, type: :string, desc: "The input to forward to the wrapped Agent"
           def self.__framework_owned_operation? = true
           tool_name "dispatch_to_#{name}"
           description "Dispatch work to the #{name} subagent (#{agent_class.name})"
@@ -53,14 +63,17 @@ module Phronomy
           # cancelled: an already admitted child must be settled, not forgotten.
           define_method(:call_async) do |args, cancellation_token: nil, config: {}|
             if @_orchestrator_context&.fetch(:parent, nil) && config[:phronomy_tool_invocation_id]
-              validated, schema_error = send(:validate_and_coerce, args)
+              validated, schema_error = validate_arguments(args)
               raise Phronomy::ToolError, schema_error if schema_error
               execute_async(**validated, cancellation_token: cancellation_token, config: config)
             else
-              super(args, cancellation_token: cancellation_token, config: config)
+              call_async_operation(args, cancellation_token: cancellation_token,
+                operation_name: "agent-tool-#{self.name}") do |validated_args|
+                execute_async(**validated_args, cancellation_token: cancellation_token, config: config || {})
+              end
             end
           rescue => error
-            Phronomy::TaskResult.deferred(name: "subagent-dispatch-failed").tap { |task| task.fail(error) }
+            Phronomy::TaskResult.failed(error, name: "subagent-dispatch-failed")
           end
 
           define_method(:execute_async) do |input:, cancellation_token: nil, config: {}|
@@ -86,29 +99,25 @@ module Phronomy
             agent = agent_class.new
             if inherit_knowledge
               Array(ctx[:knowledge]).each do |entry|
-                agent.add_knowledge(entry.fetch(:content), metadata: entry.fetch(:metadata, {}))
+                agent.add_knowledge(entry.content, metadata: entry.metadata)
               end
             end
-            source = agent.invoke_async(input, config: task_config)
-            result_task = Phronomy::TaskResult.deferred(
-              name: "subagent-tool-#{name}"
-            )
-            source.on_complete do |result, error|
-              if error
-                (on_error == :raise) ? result_task.fail(error) : result_task.complete(nil)
-              else
-                result_task.complete(result[:output])
-              end
+            Phronomy::AsyncOperation.call(name: "subagent-tool-#{name}",
+              on_error: ->(error) { raise error if on_error == :raise },
+              transform: ->(result) { result[:output] }) do
+              agent.invoke_async(input, config: task_config)
             end
-            result_task
           rescue => error
-            result_task ||= Phronomy::TaskResult.deferred(
-              name: "subagent-tool-#{name}"
-            )
-            (on_error == :raise) ? result_task.fail(error) : result_task.complete(nil)
-            result_task
+            Phronomy::AsyncOperation.capture(name: "subagent-tool-#{name}",
+              on_error: ->(failure) { raise failure if on_error == :raise }) { raise error }
           end
-          private :execute_async
+          # Recovery requirements retain their Agent meaning across delegation.
+          def async_error_value(error)
+            raise error if error.is_a?(Phronomy::ExecutionRehydrationRequiredError)
+
+            super
+          end
+          private :execute_async, :async_error_value
         end
 
         @_subagent_tool_classes = (@_subagent_tool_classes || []) + [tool_class]
@@ -138,7 +147,7 @@ module Phronomy
         invocation_context: nil,
         inherit_knowledge: true
       )
-        if Phronomy::Runtime.in_event_loop_context?
+        if Phronomy::WaitPolicy.blocking_forbidden?
           raise Phronomy::EventLoopReentrancyError,
             "dispatch_parallel cannot block the EventLoop; use dispatch_parallel_async"
         end
@@ -169,25 +178,17 @@ module Phronomy
           invocation_context: nil,
           inherit_knowledge: inherit_knowledge
         )
-        Phronomy::Execution.send(:__run_async, children,
+        Phronomy::Execution.run_async(children,
           timeout: timeout, cancellation_token: cancellation_token,
-          invocation_context: invocation_context, concurrency_limit: max_concurrency) do |child, execution|
-          # Preserve a child-specific context as well as this dispatch's controls.
-          # Agent admission adds that context's constraints to the supplied token.
-          binding = Phronomy::Execution.__operation_binding(
-            invocation_context: execution.invocation_context,
-            cancellation_token: child.config[:cancellation_token]
-          )
-          child_context = child.config[:invocation_context] ||
-            execution.invocation_context.merge(parent_task_id: invocation_context&.task_id)
-          begin
-            source = child.agent.invoke_async(child.input,
-              config: child.config.merge(cancellation_token: binding.token),
+          invocation_context: invocation_context, max_concurrency: max_concurrency) do |child, execution|
+          execution.start_child(
+            invocation_context: child.config[:invocation_context],
+            cancellation_token: child.config[:cancellation_token],
+            parent_task_id: invocation_context&.task_id
+          ) do |child_context, token|
+            child.agent.invoke_async(child.input,
+              config: child.config.merge(cancellation_token: token),
               invocation_context: child_context)
-            binding.track(source)
-          rescue
-            binding.close
-            raise
           end
         end.map do |outcomes|
           failure = outcomes.find { |outcome| outcome.status != :completed }
@@ -203,7 +204,7 @@ module Phronomy
         config: nil,
         inherit_knowledge: true
       )
-        if Phronomy::Runtime.in_event_loop_context?
+        if Phronomy::WaitPolicy.blocking_forbidden?
           raise Phronomy::EventLoopReentrancyError,
             "subagent cannot block the EventLoop; use the async Agent API"
         end
@@ -221,12 +222,6 @@ module Phronomy
         self.class.registered_subagents.keys.any? { |key| "dispatch_to_#{key}" == name.to_s }
       end
 
-      # Reserve child identity/input/knowledge in the parent's existing Agent transaction.
-      # @api private
-      def __prepare_coordination_record(execution, tx:)
-        DurableSubagentCoordinator.prepare(self, execution, tx: tx)
-      end
-
       private
 
       def prepare_tool_class(tool_class, invocation: nil)
@@ -263,16 +258,7 @@ module Phronomy
         end
       end
 
-      def active_knowledge_snapshot
-        journal_projection.context_records.filter_map do |record|
-          next unless record.kind == :knowledge
-
-          {
-            content: persistence.contents.fetch_text(record.content_ref),
-            metadata: (record.metadata || {}).dup.freeze
-          }.freeze
-        end.freeze
-      end
+      def active_knowledge_snapshot = knowledge_snapshot
 
       def build_subagent(agent_class, inherit_knowledge: true, knowledge_snapshot: nil)
         agent = agent_class.new
@@ -281,8 +267,8 @@ module Phronomy
         snapshot = knowledge_snapshot || active_knowledge_snapshot
         snapshot.each do |entry|
           agent.add_knowledge(
-            entry.fetch(:content),
-            metadata: entry.fetch(:metadata, {})
+            entry.content,
+            metadata: entry.metadata
           )
         end
         agent

data/lib/phronomy/multi_agent/persistence/codec.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Current-format record schemas and conversion for this domain.
+      # @api private
+      module Codec
+        extend Phronomy::Storage::RecordCodec
+
+        module_function
+
+        def encode_handoff_state(value)
+          payload = value.to_h
+          Phronomy::MultiAgent::HandoffState.from_h(payload)
+          build_record("phronomy.handoff_state", "0.2", payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode HandoffState", error)
+        end
+
+        def decode_handoff_state(record)
+          payload = current_payload!(record, record_type: "phronomy.handoff_state",
+            format_version: "0.2", keys: Phronomy::MultiAgent::HandoffState::ATTRIBUTES, label: "HandoffState")
+          Phronomy::MultiAgent::HandoffState.from_h(payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode HandoffState", error)
+        end
+
+        def encode_team_root(value)
+          payload = value.to_h
+          Phronomy::MultiAgent::TeamRoot.from_h(payload)
+          build_record("phronomy.team_root", "0.1", payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode TeamRoot", error)
+        end
+
+        def decode_team_root(record)
+          payload = current_payload!(record, record_type: "phronomy.team_root",
+            format_version: "0.1", keys: Phronomy::MultiAgent::TeamRoot::ATTRIBUTES, label: "TeamRoot")
+          Phronomy::MultiAgent::TeamRoot.from_h(payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode TeamRoot", error)
+        end
+
+        def encode_team_execution(value)
+          payload = value.to_h
+          Phronomy::MultiAgent::TeamExecution.from_h(payload)
+          build_record("phronomy.team_execution", "0.1", payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode TeamExecution", error)
+        end
+
+        def decode_team_execution(record)
+          payload = current_payload!(record, record_type: "phronomy.team_execution",
+            format_version: "0.1", keys: Phronomy::MultiAgent::TeamExecution::ATTRIBUTES, label: "TeamExecution")
+          Phronomy::MultiAgent::TeamExecution.from_h(payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode TeamExecution", error)
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/persistence/handoff_state_repository.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Owns Handoff state encoding and the initial revision.
+      # @api private
+      class HandoffStateRepository
+        def initialize(view) = @view = view
+
+        def load(main_agent_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.atomic do |bound|
+              entry = bound.records(StorageSchema::HANDOFF_STATES).read(main_agent_id.to_s)
+              entry && decode(entry, main_agent_id)
+            end
+          end
+        end
+
+        # Lock before inspecting child existence so cancellation cannot decide
+        # that a child is absent using a snapshot from before its admission.
+        def load_locked(main_agent_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.atomic do |bound|
+              bound.check!(guards: [Phronomy::Storage::GuardRef.new(
+                resource: StorageSchema::HANDOFF_STATES, key: main_agent_id.to_s
+              )], conditions: [])
+              self.class.new(bound).load(main_agent_id)
+            end
+          end
+        end
+
+        def save(main_agent_id, expected_revision:, state:)
+          Phronomy::Persistence::StorageBoundary.call do
+            expected = expected_revision.nil? ? nil : Integer(expected_revision)
+            revision = expected.nil? ? 1 : expected + 1
+            unless state.main_agent_id == main_agent_id.to_s && state.handoff_revision == revision
+              raise Phronomy::Storage::SerializationError, "Handoff identity/revision mismatch"
+            end
+            record = Codec.encode_handoff_state(state)
+            @view.atomic do |bound|
+              records = bound.records(StorageSchema::HANDOFF_STATES)
+              values = {key: main_agent_id.to_s, attributes: {active_agent_id: state.active_agent_id}, record: record}
+              entry = if expected.nil?
+                records.insert(**values, revision: revision)
+              else
+                records.replace(**values, expected_revision: expected, next_revision: revision)
+              end
+              decode(entry, main_agent_id, revision: revision)
+            end
+          rescue Phronomy::Storage::NotFoundError => error
+            raise Phronomy::Storage::ConflictError, error.message
+          end
+        end
+
+        def delete(main_agent_id, expected_revision:)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.records(StorageSchema::HANDOFF_STATES).delete(key: main_agent_id.to_s, expected_revision: Integer(expected_revision))
+          end
+        end
+
+        private
+
+        def decode(entry, main_agent_id, revision: nil)
+          state = Codec.decode_handoff_state(entry.record)
+          valid = entry.key == main_agent_id.to_s && state.main_agent_id == entry.key &&
+            state.handoff_revision == entry.revision && (!revision || revision == entry.revision) &&
+            entry.attributes == {active_agent_id: state.active_agent_id}
+          unless valid
+            raise Phronomy::Storage::SerializationError, "backend returned another Handoff identity/revision"
+          end
+          state
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/persistence/records.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Storage implementation of Team's own record operations.
+      # @api private
+      class Records
+        attr_reader :contents, :teams, :team_executions, :handoff_states
+
+        def initialize(view)
+          @view = view
+          @contents = Phronomy::Persistence::ContentRepository.new(Phronomy::ContentStore::StoredContents.new(view))
+          @teams = TeamRepository.new(view)
+          @team_executions = TeamExecutionRepository.new(view)
+          @handoff_states = HandoffStateRepository.new(view)
+        end
+
+        def guard_team!(team_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.check!(guards: [Phronomy::Storage::GuardRef.new(resource: Phronomy::MultiAgent::Persistence::StorageSchema::ROOTS, key: team_id)], conditions: [])
+          end
+        end
+      end
+    end
+  end
+end