phronomy 0.23.0 → 0.24.0

data/lib/phronomy/multi_agent/team_execution.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Phronomy
+  module MultiAgent
+    # Immutable current-format semantic record; contains no Runtime handles.
+    # @api private
+    class TeamExecution
+      ATTRIBUTES = %w[team_execution_id team_id execution_revision status phase input_ref coordinator tasks workers assignments result_ref error_ref created_at updated_at metadata].freeze
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(**values)
+        source = values.transform_keys(&:to_s)
+        raise ArgumentError, "TeamExecution 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))) }
+        raise ArgumentError, "missing team_execution_id" if team_execution_id.to_s.empty?
+        raise ArgumentError, "invalid execution_revision" unless execution_revision.is_a?(Integer) && execution_revision >= 0
+        raise ArgumentError, "invalid metadata" unless metadata.is_a?(Hash)
+        raise ArgumentError, "invalid Team status" unless %w[active completed failed cancelled].include?(status)
+        raise ArgumentError, "missing Team owner" if team_id.to_s.empty?
+        raise ArgumentError, "invalid Team collections" unless [tasks, workers, assignments].all? { |v| v.is_a?(Array) } && coordinator.is_a?(Hash)
+        freeze
+      end
+
+      def to_h = ATTRIBUTES.to_h { |key| [key, public_send(key)] }.freeze
+
+      def self.from_h(value)
+        new(**value.transform_keys(&:to_sym))
+      end
+
+      def with(**changes)
+        values = to_h.merge(changes.transform_keys(&:to_s))
+        values["execution_revision"] = execution_revision + 1 unless changes.key?(:execution_revision)
+        values["updated_at"] = Time.now.utc.iso8601(6) unless changes.key?(:updated_at)
+        self.class.from_h(values)
+      end
+
+      def active? = status == "active"
+      def terminal? = %w[completed failed cancelled].include?(status)
+    end
+  end
+end

data/lib/phronomy/multi_agent/team_root.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Phronomy
+  module MultiAgent
+    # Immutable current-format semantic record; contains no Runtime handles.
+    # @api private
+    class TeamRoot
+      ATTRIBUTES = %w[team_id team_definition_id team_definition_version team_revision lifecycle_status created_at updated_at metadata].freeze
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(**values)
+        source = values.transform_keys(&:to_s)
+        raise ArgumentError, "TeamRoot 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))) }
+        raise ArgumentError, "missing team_id" if team_id.to_s.empty?
+        raise ArgumentError, "invalid team_revision" unless team_revision.is_a?(Integer) && team_revision >= 0
+        raise ArgumentError, "invalid metadata" unless metadata.is_a?(Hash)
+        raise ArgumentError, "invalid Team lifecycle" unless %w[idle active closed].include?(lifecycle_status)
+        raise ArgumentError, "missing Team definition" if team_definition_id.to_s.empty?
+        raise ArgumentError, "invalid Team version" unless team_definition_version.is_a?(Integer) && team_definition_version.positive?
+        freeze
+      end
+
+      def to_h = ATTRIBUTES.to_h { |key| [key, public_send(key)] }.freeze
+
+      def self.from_h(value)
+        new(**value.transform_keys(&:to_sym))
+      end
+
+      def with(**changes)
+        values = to_h.merge(changes.transform_keys(&:to_s))
+        values["team_revision"] = team_revision + 1 unless changes.key?(:team_revision)
+        values["updated_at"] = Time.now.utc.iso8601(6) unless changes.key?(:updated_at)
+        self.class.from_h(values)
+      end
+    end
+  end
+end

data/lib/phronomy/persistence/durable_codec.rb

@@ -58,6 +58,66 @@ module Phronomy
 
       module_function
 
+      def encode_handoff_state(value)
+        payload = value.to_h
+        Phronomy::Agent::HandoffState.from_h(payload)
+        build_record("phronomy.handoff_state", "0.1", payload)
+      rescue Phronomy::Persistence::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.1", keys: Phronomy::Agent::HandoffState::ATTRIBUTES, label: "HandoffState")
+        Phronomy::Agent::HandoffState.from_h(payload)
+      rescue Phronomy::Persistence::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::Persistence::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::Persistence::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::Persistence::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::Persistence::SerializationError
+        raise
+      rescue => error
+        serialization_error("cannot decode TeamExecution", error)
+      end
+
       def encode_agent_root(root)
         payload = top_level_string_keys(root.to_h, label: "AgentRoot payload")
         payload["lifecycle_status"] = root.lifecycle_status.to_s

data/lib/phronomy/persistence/in_memory.rb

@@ -257,6 +257,15 @@ module Phronomy
           end
         end
 
+        def list(agent_id, after: nil, limit: 100)
+          @owner.synchronize do
+            ids = @owner.state[:execution_metadata].filter_map do |id, metadata|
+              id if metadata.fetch(:agent_id) == agent_id.to_s && (!after || id > after.to_s)
+            end.sort.first(limit)
+            ids.map { |id| @owner.state[:executions].fetch(id).copy }.freeze
+          end
+        end
+
         def delete(execution_id)
           @owner.synchronize do
             key = execution_id.to_s
@@ -292,6 +301,255 @@ module Phronomy
         end
       end
 
+      class Teams
+        def initialize(owner) = @owner = owner
+
+        def create(team_id:, team_revision:, record:)
+          record = @owner.require_durable_record!(record)
+          key = team_id.to_s
+          revision = Integer(team_revision)
+          raise ConflictError, "team_id must not be empty" if key.empty?
+          raise ConflictError, "team_revision must be non-negative" if revision.negative?
+
+          @owner.synchronize do
+            raise ConflictError, "agent already exists: #{key}" if @owner.state[:teams].key?(key)
+            @owner.state[:teams][key] = record.copy
+            @owner.state[:team_revisions][key] = revision
+          end
+          record.copy
+        end
+
+        def load(team_id)
+          @owner.synchronize do
+            @owner.state[:teams].fetch(team_id.to_s) do
+              raise NotFoundError, "agent not found: #{team_id}"
+            end.copy
+          end
+        end
+
+        def save(team_id, expected_revision:, next_revision:, record:)
+          record = @owner.require_durable_record!(record)
+          key = team_id.to_s
+          expected = Integer(expected_revision)
+          next_value = Integer(next_revision)
+          @owner.synchronize do
+            unless @owner.state[:teams].key?(key)
+              raise NotFoundError, "agent not found: #{team_id}"
+            end
+            actual_revision = @owner.state[:team_revisions].fetch(key)
+            unless actual_revision == expected
+              raise ConflictError,
+                "agent revision conflict: expected #{expected}, actual #{actual_revision}"
+            end
+            unless next_value == expected + 1
+              raise ConflictError,
+                "agent save must advance revision exactly once: " \
+                "expected #{expected + 1}, got #{next_value}"
+            end
+            @owner.state[:teams][key] = record.copy
+            @owner.state[:team_revisions][key] = next_value
+          end
+          record.copy
+        end
+
+        def delete(team_id)
+          @owner.synchronize do
+            key = team_id.to_s
+            @owner.state[:team_revisions].delete(key)
+            @owner.state[:teams].delete(key)
+          end
+        end
+      end
+
+      class TeamExecutions
+        def initialize(owner) = @owner = owner
+
+        def create_active(team_execution_id:, team_id:, execution_revision:, record:)
+          record = @owner.require_durable_record!(record)
+          execution_key = team_execution_id.to_s
+          agent_key = team_id.to_s
+          revision = Integer(execution_revision)
+          raise ConflictError, "team_execution_id must not be empty" if execution_key.empty?
+          raise ConflictError, "team_id must not be empty" if agent_key.empty?
+          raise ConflictError, "execution_revision must be non-negative" if revision.negative?
+
+          @owner.synchronize do
+            if @owner.state[:team_executions].key?(execution_key)
+              raise ConflictError, "execution already exists: #{execution_key}"
+            end
+            active = @owner.state[:team_execution_metadata].values.find do |metadata|
+              metadata.fetch(:team_id) == agent_key && metadata.fetch(:active)
+            end
+            raise Phronomy::AgentBusyError, "agent is busy: #{agent_key}" if active
+
+            @owner.state[:team_executions][execution_key] = record.copy
+            @owner.state[:team_execution_metadata][execution_key] = {
+              team_id: agent_key,
+              revision: revision,
+              active: true
+            }.freeze
+          end
+          record.copy
+        end
+
+        def load(team_execution_id)
+          @owner.synchronize do
+            @owner.state[:team_executions].fetch(team_execution_id.to_s) do
+              raise NotFoundError, "execution not found: #{team_execution_id}"
+            end.copy
+          end
+        end
+
+        def save(team_execution_id, expected_revision:, next_revision:, team_id:, active:, record:)
+          record = @owner.require_durable_record!(record)
+          execution_key = team_execution_id.to_s
+          agent_key = team_id.to_s
+          expected = Integer(expected_revision)
+          next_value = Integer(next_revision)
+          unless active.equal?(true) || active.equal?(false)
+            raise ConflictError, "execution active metadata must be true or false"
+          end
+
+          @owner.synchronize do
+            unless @owner.state[:team_executions].key?(execution_key)
+              raise NotFoundError, "execution not found: #{team_execution_id}"
+            end
+            current = @owner.state[:team_execution_metadata].fetch(execution_key)
+            actual_revision = current.fetch(:revision)
+            unless actual_revision == expected
+              raise ConflictError,
+                "execution revision conflict: expected #{expected}, actual #{actual_revision}"
+            end
+            unless current.fetch(:team_id) == agent_key
+              raise ConflictError,
+                "Execution Team identity mismatch: #{agent_key} != #{current.fetch(:team_id)}"
+            end
+            if active && !current.fetch(:active)
+              raise ConflictError, "A terminal Team execution cannot become active"
+            end
+            unless next_value == expected + 1
+              raise ConflictError,
+                "execution save must advance revision exactly once: " \
+                "expected #{expected + 1}, got #{next_value}"
+            end
+
+            @owner.state[:team_executions][execution_key] = record.copy
+            @owner.state[:team_execution_metadata][execution_key] = {
+              team_id: agent_key,
+              revision: next_value,
+              active: active
+            }.freeze
+          end
+          record.copy
+        end
+
+        def list_active(team_id)
+          @owner.synchronize do
+            agent_key = team_id.to_s
+            ids = @owner.state[:team_execution_metadata].filter_map do |team_execution_id, metadata|
+              team_execution_id if metadata.fetch(:team_id) == agent_key && metadata.fetch(:active)
+            end
+            ids.map { |team_execution_id| @owner.state[:team_executions].fetch(team_execution_id).copy }.freeze
+          end
+        end
+
+        def list(team_id, after: nil, limit: 100)
+          @owner.synchronize do
+            ids = @owner.state[:team_execution_metadata].filter_map do |id, metadata|
+              id if metadata.fetch(:team_id) == team_id.to_s && (!after || id > after.to_s)
+            end.sort.first(limit)
+            ids.map { |id| @owner.state[:team_executions].fetch(id).copy }.freeze
+          end
+        end
+
+        def delete(team_execution_id)
+          @owner.synchronize do
+            key = team_execution_id.to_s
+            @owner.state[:team_execution_metadata].delete(key)
+            @owner.state[:team_executions].delete(key)
+          end
+        end
+
+        def delete_for_team(team_id)
+          @owner.synchronize do
+            agent_key = team_id.to_s
+            ids = @owner.state[:team_execution_metadata].filter_map do |team_execution_id, metadata|
+              team_execution_id if metadata.fetch(:team_id) == agent_key
+            end
+            ids.each do |team_execution_id|
+              @owner.state[:team_execution_metadata].delete(team_execution_id)
+              @owner.state[:team_executions].delete(team_execution_id)
+            end
+          end
+        end
+
+        def assert_idle!(team_id)
+          @owner.synchronize do
+            active = @owner.state[:team_execution_metadata].values.find do |metadata|
+              metadata.fetch(:team_id) == team_id.to_s && metadata.fetch(:active)
+            end
+            if active
+              raise Phronomy::AgentBusyError,
+                "agent has an active or suspended execution: #{team_id}"
+            end
+          end
+          true
+        end
+      end
+
+      class HandoffStates
+        def initialize(owner) = @owner = owner
+
+        def load(main_agent_id)
+          @owner.synchronize do
+            record = @owner.state[:handoff_states][main_agent_id.to_s]
+            record&.copy
+          end
+        end
+
+        def save(main_agent_id, expected_revision:, next_revision:, active_agent_id:, record:)
+          record = @owner.require_durable_record!(record)
+          raise ArgumentError, "active_agent_id is required" if active_agent_id.to_s.empty?
+          key = main_agent_id.to_s
+          expected = expected_revision.nil? ? nil : Integer(expected_revision)
+          next_value = Integer(next_revision)
+          @owner.synchronize do
+            actual_revision = @owner.state[:handoff_revisions][key]
+            unless actual_revision == expected
+              raise ConflictError,
+                "workflow state revision conflict for #{key}: " \
+                "expected #{expected.inspect}, actual #{actual_revision.inspect}"
+            end
+            expected_next = expected.nil? ? 1 : expected + 1
+            unless next_value == expected_next
+              raise ConflictError,
+                "workflow state save must advance revision exactly once: " \
+                "expected #{expected_next}, got #{next_value}"
+            end
+
+            @owner.state[:handoff_states][key] = record.copy
+            @owner.state[:handoff_revisions][key] = next_value
+          end
+          record.copy
+        end
+
+        def delete(main_agent_id, expected_revision:)
+          @owner.synchronize do
+            key = main_agent_id.to_s
+            expected = Integer(expected_revision)
+            actual_revision = @owner.state[:handoff_revisions][key]
+            unless actual_revision == expected
+              raise ConflictError,
+                "workflow state revision conflict for #{key}: " \
+                "expected #{expected.inspect}, actual #{actual_revision.inspect}"
+            end
+            @owner.state[:handoff_revisions].delete(key)
+            @owner.state[:handoff_states].delete(key)
+          end
+          nil
+        end
+      end
+
       class WorkflowStates
         def initialize(owner) = @owner = owner
 
@@ -357,7 +615,9 @@ module Phronomy
           executions: {},
           execution_metadata: {},
           workflow_states: {},
-          workflow_revisions: {}
+          workflow_revisions: {},
+          handoff_states: {}, handoff_revisions: {},
+          teams: {}, team_revisions: {}, team_executions: {}, team_execution_metadata: {}
         }
         @contents_backend = Contents.new(self)
         @agents_backend = Agents.new(self)
@@ -369,7 +629,9 @@ module Phronomy
           agents: @agents_backend,
           journals: @journals_backend,
           executions: @executions_backend,
-          workflow_states: @workflow_states_backend
+          workflow_states: @workflow_states_backend,
+          handoff_states: HandoffStates.new(self),
+          teams: Teams.new(self), team_executions: TeamExecutions.new(self)
         )
       end
 

data/lib/phronomy/persistence/repository_facades.rb

@@ -204,6 +204,13 @@ module Phronomy
           end.freeze
         end
 
+        def list(agent_id, after: nil, limit: 100)
+          raise ArgumentError, "limit must be a positive Integer" unless limit.is_a?(Integer) && limit.positive?
+          Array(@backend_repository.list(agent_id.to_s, after: after&.to_s, limit: limit)).map do |record|
+            decode_for_execution(record, nil, agent_id: agent_id)
+          end.freeze
+        end
+
         def delete(execution_id)
           @backend_repository.delete(execution_id.to_s)
         end
@@ -240,6 +247,215 @@ module Phronomy
         end
       end
 
+      class Teams
+        def initialize(backend_repository)
+          @backend_repository = backend_repository
+        end
+
+        def create(root)
+          record = DurableCodec.encode_team_root(root)
+          stored = @backend_repository.create(
+            team_id: root.team_id.to_s,
+            team_revision: Integer(root.team_revision),
+            record: record
+          )
+          decode_for_team(stored, root.team_id, revision: root.team_revision)
+        end
+
+        def load(team_id)
+          decode_for_team(@backend_repository.load(team_id.to_s), team_id)
+        end
+
+        def save(team_id, expected_revision:, root:)
+          expected = Integer(expected_revision)
+          next_revision = Integer(root.team_revision)
+          unless next_revision == expected + 1
+            raise Phronomy::Persistence::ConflictError,
+              "agent save must advance revision exactly once: " \
+              "expected #{expected + 1}, got #{next_revision}"
+          end
+          unless root.team_id.to_s == team_id.to_s
+            raise Phronomy::Persistence::SerializationError,
+              "Team root identity mismatch: #{root.team_id} != #{team_id}"
+          end
+
+          record = DurableCodec.encode_team_root(root)
+          stored = @backend_repository.save(
+            team_id.to_s,
+            expected_revision: expected,
+            next_revision: next_revision,
+            record: record
+          )
+          decode_for_team(stored, team_id, revision: next_revision)
+        end
+
+        def delete(team_id)
+          @backend_repository.delete(team_id.to_s)
+        end
+
+        private
+
+        def decode_for_team(record, team_id, revision: nil)
+          root = DurableCodec.decode_team_root(record)
+          unless root.team_id == team_id.to_s
+            raise Phronomy::Persistence::SerializationError,
+              "backend returned Team root for #{root.team_id.inspect}; expected #{team_id.to_s.inspect}"
+          end
+          if revision && root.team_revision != revision
+            raise Phronomy::Persistence::SerializationError,
+              "backend returned Team revision #{root.team_revision}; expected #{revision}"
+          end
+          root
+        end
+      end
+
+      class TeamExecutions
+        def initialize(backend_repository)
+          @backend_repository = backend_repository
+        end
+
+        def create_active(execution)
+          unless execution.active?
+            raise Phronomy::Persistence::SerializationError,
+              "create_active requires an active TeamExecution"
+          end
+          record = DurableCodec.encode_team_execution(execution)
+          stored = @backend_repository.create_active(
+            team_execution_id: execution.team_execution_id.to_s,
+            team_id: execution.team_id.to_s,
+            execution_revision: Integer(execution.execution_revision),
+            record: record
+          )
+          decode_for_execution(
+            stored,
+            execution.team_execution_id,
+            team_id: execution.team_id,
+            revision: execution.execution_revision,
+            active: true
+          )
+        end
+
+        def load(team_execution_id)
+          decode_for_execution(@backend_repository.load(team_execution_id.to_s), team_execution_id)
+        end
+
+        def save(team_execution_id, expected_revision:, execution:)
+          expected = Integer(expected_revision)
+          next_revision = Integer(execution.execution_revision)
+          unless next_revision == expected + 1
+            raise Phronomy::Persistence::ConflictError,
+              "execution save must advance revision exactly once: " \
+              "expected #{expected + 1}, got #{next_revision}"
+          end
+          unless execution.team_execution_id.to_s == team_execution_id.to_s
+            raise Phronomy::Persistence::SerializationError,
+              "Execution identity mismatch: #{execution.team_execution_id} != #{team_execution_id}"
+          end
+
+          record = DurableCodec.encode_team_execution(execution)
+          stored = @backend_repository.save(
+            team_execution_id.to_s,
+            expected_revision: expected,
+            next_revision: next_revision,
+            team_id: execution.team_id.to_s,
+            active: execution.active?,
+            record: record
+          )
+          decode_for_execution(
+            stored,
+            team_execution_id,
+            team_id: execution.team_id,
+            revision: next_revision,
+            active: execution.active?
+          )
+        end
+
+        def list_active(team_id)
+          Array(@backend_repository.list_active(team_id.to_s)).map do |record|
+            decode_for_execution(record, nil, team_id: team_id, active: true)
+          end.freeze
+        end
+
+        def list(team_id, after: nil, limit: 100)
+          raise ArgumentError, "limit must be a positive Integer" unless limit.is_a?(Integer) && limit.positive?
+          Array(@backend_repository.list(team_id.to_s, after: after&.to_s, limit: limit)).map do |record|
+            decode_for_execution(record, nil, team_id: team_id)
+          end.freeze
+        end
+
+        def delete(team_execution_id)
+          @backend_repository.delete(team_execution_id.to_s)
+        end
+
+        def delete_for_team(team_id)
+          @backend_repository.delete_for_team(team_id.to_s)
+        end
+
+        def assert_idle!(team_id)
+          @backend_repository.assert_idle!(team_id.to_s)
+        end
+
+        private
+
+        def decode_for_execution(record, team_execution_id, team_id: nil, revision: nil, active: nil)
+          execution = DurableCodec.decode_team_execution(record)
+          if team_execution_id && execution.team_execution_id != team_execution_id.to_s
+            raise Phronomy::Persistence::SerializationError,
+              "backend returned Execution #{execution.team_execution_id.inspect}; expected #{team_execution_id.to_s.inspect}"
+          end
+          if team_id && execution.team_id != team_id.to_s
+            raise Phronomy::Persistence::SerializationError,
+              "backend returned Execution for Agent #{execution.team_id.inspect}; expected #{team_id.to_s.inspect}"
+          end
+          if revision && execution.execution_revision != revision
+            raise Phronomy::Persistence::SerializationError,
+              "backend returned Execution revision #{execution.execution_revision}; expected #{revision}"
+          end
+          if !active.nil? && execution.active? != active
+            raise Phronomy::Persistence::SerializationError,
+              "backend returned Execution active=#{execution.active?}; expected #{active}"
+          end
+          execution
+        end
+      end
+
+      class HandoffStates
+        def initialize(backend_repository) = @backend_repository = backend_repository
+
+        def load(main_agent_id)
+          record = @backend_repository.load(main_agent_id.to_s)
+          record && decode(record, main_agent_id)
+        end
+
+        def save(main_agent_id, expected_revision:, state:)
+          expected = expected_revision.nil? ? nil : Integer(expected_revision)
+          next_revision = expected.nil? ? 1 : expected + 1
+          unless state.main_agent_id == main_agent_id.to_s && state.handoff_revision == next_revision
+            raise Phronomy::Persistence::SerializationError, "Handoff identity/revision mismatch"
+          end
+          record = @backend_repository.save(main_agent_id.to_s,
+            expected_revision: expected, next_revision: next_revision,
+            active_agent_id: state.active_agent_id, record: DurableCodec.encode_handoff_state(state))
+          decode(record, main_agent_id, revision: next_revision)
+        end
+
+        def delete(main_agent_id, expected_revision:)
+          @backend_repository.delete(main_agent_id.to_s, expected_revision: Integer(expected_revision))
+        end
+
+        private
+
+        def decode(record, main_agent_id, revision: nil)
+          state = DurableCodec.decode_handoff_state(record)
+          identity_matches = state.main_agent_id == main_agent_id.to_s
+          revision_matches = revision.nil? || state.handoff_revision == revision
+          unless identity_matches && revision_matches
+            raise Phronomy::Persistence::SerializationError, "Backend returned another Handoff identity/revision"
+          end
+          state
+        end
+      end
+
       class WorkflowStates
         def initialize(backend_repository)
           @backend_repository = backend_repository
@@ -292,14 +508,17 @@ module Phronomy
       # repositories. Backend implementations can use this through
       # Persistence#build_transaction_view without duplicating facade logic.
       class View
-        attr_reader :contents, :agents, :journals, :executions, :workflow_states
+        attr_reader :contents, :agents, :journals, :executions, :workflow_states, :handoff_states, :teams, :team_executions
 
-        def initialize(contents:, agents:, journals:, executions:, workflow_states:, watermark:)
+        def initialize(contents:, agents:, journals:, executions:, workflow_states:, handoff_states:, teams:, team_executions:, watermark:)
           @contents = contents
           @agents = Agents.new(agents)
           @journals = Journals.new(journals)
           @executions = Executions.new(executions)
           @workflow_states = WorkflowStates.new(workflow_states)
+          @handoff_states = HandoffStates.new(handoff_states)
+          @teams = Teams.new(teams)
+          @team_executions = TeamExecutions.new(team_executions)
           @watermark = watermark
         end