phronomy 0.27.0 → 0.28.0

data/lib/phronomy/agent/execution_environment.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Process-local execution connection selected by composition. Agent owns
+    # admission, progress, approval, durable outcome and recovery decisions;
+    # this extension supplies serial delivery, session routing and resources.
+    # Environments and session handles are never persistence authority.
+    # @api private
+    class ExecutionEnvironment
+      class << self
+        def install_provider(provider)
+          raise ArgumentError, "Agent execution provider must be callable" unless provider.respond_to?(:call)
+          @provider = provider
+        end
+
+        def current
+          @provider&.call || raise(Phronomy::ConfigurationError, "Agent execution environment has not been configured")
+        end
+      end
+
+      def registry = raise(NotImplementedError)
+      def existing_registry = raise(NotImplementedError)
+      def ownership = raise(NotImplementedError)
+      def existing_ownership = raise(NotImplementedError)
+      def executing? = raise(NotImplementedError)
+      def session_phase(id) = raise(NotImplementedError)
+      def submit(**options, &operation) = raise(NotImplementedError)
+      def submit_authorization(timeout:, cancellation_token:, &operation) = raise(NotImplementedError)
+      def build_llm_client(adapter:) = raise(NotImplementedError)
+      def build_agent_session(invocation:, resume_event: nil, resume_phase: nil) = raise(NotImplementedError)
+      def build_tool_session(invocation:, parent_sink:, resume_event: nil, resume_phase: nil) = raise(NotImplementedError)
+      def register_session(session, completion:) = raise(NotImplementedError)
+    end
+  end
+end

data/lib/phronomy/agent/execution_extension_state.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # An opaque state reference owned and interpreted by its bound participant.
+    # @api public
+    ExecutionExtensionState = Data.define(:binding_key, :binding_version, :state_ref) do
+      def initialize(binding_key:, binding_version:, state_ref: nil)
+        raise ArgumentError, "binding_key is required" if binding_key.to_s.empty?
+        raise ArgumentError, "binding_version must be positive" unless binding_version.is_a?(Integer) && binding_version.positive?
+        super(binding_key: binding_key.to_s.freeze, binding_version: binding_version, state_ref: state_ref&.to_s&.freeze)
+      end
+
+      def to_h
+        {"binding_key" => binding_key, "binding_version" => binding_version, "state_ref" => state_ref}.freeze
+      end
+
+      def self.from_h(value) = new(**value.transform_keys(&:to_sym))
+    end
+  end
+end

data/lib/phronomy/agent/execution_observation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Stable domain observation; does not expose repositories or FSM phases.
+    # @api public
+    ExecutionObservation = Data.define(:agent_id, :execution_id, :status, :result,
+      :error, :reservation, :transfer_receipt, :cancellation_requested) do
+      def initialize(**values)
+        super(**values.transform_values { |value| Phronomy::Values::Immutable.copy(value) })
+      end
+
+      def self.from_result(value)
+        new(agent_id: value.fetch(:agent_id), execution_id: value.fetch(:execution_id), status: value.fetch(:status),
+          result: value[:result], error: value[:error], reservation: nil, transfer_receipt: nil, cancellation_requested: false)
+      end
+
+      def absent? = status == :absent
+      def terminal? = !%i[absent preparing active suspended].include?(status)
+      def continuable? = %i[preparing active].include?(status) && !cancellation_requested
+      def active? = %i[preparing active suspended].include?(status)
+
+      def value!
+        raise Phronomy::Persistence::NotFoundError, "Execution #{execution_id} is absent" if absent?
+        raise RecoverySupport.error_from_failure(error) if error
+        to_result
+      end
+
+      def to_result
+        Phronomy::Values::Immutable.copy(execution_id: execution_id, agent_id: agent_id,
+          status: status, result: result, output: result, error: error)
+      end
+    end
+  end
+end

data/lib/phronomy/agent/filterable.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Adds input, output, and tool-result filter support to an agent.
+    #
+    # Filters transform (or block) values at three call sites:
+    #   - *input*       — the raw user input string, before the LLM is called
+    #   - *output*      — the final LLM output string, before it is returned
+    #   - *tool result* — the return value of each tool call
+    #
+    # Each filter in the chain receives the value returned by the previous one.
+    # A {Phronomy::FilterBlockError} raised inside any filter propagates to the
+    # caller.
+    #
+    # @api private
+    module Filterable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class-level DSL mixed into the including agent class.
+      module ClassMethods
+        # Registers a filter applied to every invocation's user input.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [void]
+        # @api public
+        def input_filter(filter)
+          @_class_input_filters ||= []
+          @_class_input_filters << _resolve_filter(filter)
+        end
+
+        # Registers a filter applied to every invocation's final LLM output.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [void]
+        # @api public
+        def output_filter(filter)
+          @_class_output_filters ||= []
+          @_class_output_filters << _resolve_filter(filter)
+        end
+
+        # Registers a filter applied to every tool result for all tools.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [void]
+        # @api public
+        def tool_result_filter(filter)
+          @_class_tool_result_filters ||= []
+          @_class_tool_result_filters << _resolve_filter(filter)
+        end
+
+        # @return [Array<Phronomy::Filter::Base>]
+        # @api private
+        def _class_input_filters
+          @_class_input_filters || []
+        end
+
+        # @return [Array<Phronomy::Filter::Base>]
+        # @api private
+        def _class_output_filters
+          @_class_output_filters || []
+        end
+
+        # @return [Array<Phronomy::Filter::Base>]
+        # @api private
+        def _class_tool_result_filters
+          @_class_tool_result_filters || []
+        end
+
+        private
+
+        # Coerce +filter+ to an instance: if a Class is passed, call +.new+;
+        # otherwise return the object as-is.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [Phronomy::Filter::Base]
+        # @api private
+        def _resolve_filter(filter)
+          filter.is_a?(Class) ? filter.new : filter
+        end
+      end
+
+      # Registers an input filter on this instance.
+      # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+      # when a class is given it is instantiated with +.new+.
+      # Runs in addition to any class-level input filters.
+      # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+      # @return [self]
+      # @api public
+      def add_input_filter(filter)
+        @_instance_input_filters ||= []
+        @_instance_input_filters << _resolve_filter(filter)
+        self
+      end
+
+      # Registers an output filter on this instance.
+      # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+      # when a class is given it is instantiated with +.new+.
+      # Runs in addition to any class-level output filters.
+      # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+      # @return [self]
+      # @api public
+      def add_output_filter(filter)
+        @_instance_output_filters ||= []
+        @_instance_output_filters << _resolve_filter(filter)
+        self
+      end
+
+      # Registers a tool result filter on this instance.
+      #
+      # When called with two arguments, the filter is scoped to the given tool
+      # class only.  When called with one argument, it applies to all tools.
+      # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+      # when a class is given it is instantiated with +.new+.
+      #
+      # @overload add_tool_result_filter(filter)
+      #   @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>] applied to every tool
+      # @overload add_tool_result_filter(tool_class, filter)
+      #   @param tool_class [Class] scope the filter to this tool
+      #   @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+      # @return [self]
+      # @api public
+      def add_tool_result_filter(tool_class_or_filter, filter = nil)
+        if filter.nil?
+          # Single-argument form: apply to all tools.
+          @_instance_tool_result_filters ||= []
+          @_instance_tool_result_filters << _resolve_filter(tool_class_or_filter)
+        else
+          # Two-argument form: scoped to one tool class.
+          @_scoped_tool_result_filters ||= {}
+          (@_scoped_tool_result_filters[tool_class_or_filter] ||= []) << _resolve_filter(filter)
+        end
+        self
+      end
+
+      private
+
+      # Run input filters (class-level then instance-level).
+      # @param input [String, Hash] the raw user input
+      # @return [String, Hash] the (possibly transformed) input
+      # @api private
+      def run_input_filters!(input)
+        class_filters = self.class._class_input_filters
+        inst_filters = @_instance_input_filters || []
+        (class_filters + inst_filters).inject(input) { |val, f| f.call(val) }
+      end
+
+      # Run output filters (class-level then instance-level).
+      # @param output [String] the LLM output
+      # @return [String] the (possibly transformed) output
+      # @api private
+      def run_output_filters!(output)
+        class_filters = self.class._class_output_filters
+        inst_filters = @_instance_output_filters || []
+        (class_filters + inst_filters).inject(output) { |val, f| f.call(val) }
+      end
+
+      # Collect all tool-result filters (global + scoped) for a given tool class.
+      # @param tool_class [Class]
+      # @return [Array<Phronomy::Filter::Base>]
+      # @api private
+      def _tool_result_filters_for(tool_class)
+        global = self.class._class_tool_result_filters + (@_instance_tool_result_filters || [])
+        scoped = (@_scoped_tool_result_filters || {})[tool_class] || []
+        global + scoped
+      end
+
+      # Coerce +filter+ to an instance: if a Class is passed, call +.new+;
+      # otherwise return the object as-is.
+      # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+      # @return [Phronomy::Filter::Base]
+      # @api private
+      def _resolve_filter(filter)
+        filter.is_a?(Class) ? filter.new : filter
+      end
+    end
+  end
+end

data/lib/phronomy/agent/handoff/{handoff_context.rb → transfer_context.rb}

@@ -2,7 +2,7 @@
 
 module Phronomy
   module Agent
-    class HandoffContext
+    class TransferContext
       Provenance = Data.define(
         :origin_agent_id,
         :origin_record_id,
@@ -59,7 +59,7 @@ module Phronomy
         def initialize(**values)
           provenance = values.fetch(:provenance)
           unless provenance.is_a?(Provenance)
-            raise ArgumentError, "HandoffContext::Item provenance must be Provenance"
+            raise ArgumentError, "TransferContext::Item provenance must be Provenance"
           end
           format = (values[:content_format] || :text).to_sym
           unless %i[text json].include?(format)
@@ -96,7 +96,7 @@ module Phronomy
 
       def self.from_h(value)
         source = value.transform_keys(&:to_s)
-        raise ArgumentError, "HandoffContext schema mismatch" unless source.keys.sort == %w[items responsibility]
+        raise ArgumentError, "TransferContext schema mismatch" unless source.keys.sort == %w[items responsibility]
         new(responsibility: source.fetch("responsibility"), items: source.fetch("items").map do |raw|
           values = raw.transform_keys(&:to_sym)
           values[:provenance] = Provenance.new(**values.fetch(:provenance).transform_keys(&:to_sym))
@@ -111,7 +111,7 @@ module Phronomy
         @items = Array(items).freeze
         raise ArgumentError, "Handoff Context responsibility must not be empty" if @responsibility.strip.empty?
         unless @items.all? { |item| item.is_a?(Item) }
-          raise ArgumentError, "Handoff Context items must be HandoffContext::Item values"
+          raise ArgumentError, "Handoff Context items must be TransferContext::Item values"
         end
         freeze
       end

data/lib/phronomy/agent/handoff/{handoff_projection.rb → transfer_projection.rb}

@@ -2,32 +2,19 @@
 
 module Phronomy
   module Agent
-    class HandoffProjection
+    class TransferProjection
       CONTROL_CATEGORIES = %i[instruction handoff_responsibility].freeze
       JSON_CATEGORIES = %i[assistant_message tool_message].freeze
 
       Identity = Data.define(:agent_id)
-      Edge = Data.define(:policy, :target_agent)
-      Snapshot = Data.define(:handoff, :responsibility, :selection_intent)
-      private_constant :Identity, :Edge, :Snapshot
-
-      # A terminal command contains values only, captured on EventLoop.
-      def build_terminal(view:, manifest:, persistence:, source_agent_id:)
-        request = Snapshot.new(
-          handoff: Edge.new(policy: HandoffPolicy.from_h(view.policy), target_agent: Identity.new(agent_id: view.target_agent_id)),
-          responsibility: view.responsibility,
-          selection_intent: view.selection_intent.transform_keys(&:to_sym)
-        )
-        build(request: request, manifest: manifest, persistence: persistence,
-          source_agent: Identity.new(agent_id: source_agent_id))
-      end
+      private_constant :Identity
 
       def build(request:, manifest:, persistence:, source_agent:)
-        unless request.is_a?(HandoffRequest) || request.is_a?(Snapshot)
-          raise ArgumentError, "request must be a HandoffRequest"
+        unless request.is_a?(ControlRequest)
+          raise ArgumentError, "request must be an Agent::ControlRequest"
         end
-        unless manifest.is_a?(Phronomy::Agent::LLMInputManifest)
-          raise ArgumentError, "manifest must be an LLMInputManifest"
+        unless manifest.is_a?(Phronomy::Context::LLMInputManifest)
+          raise ArgumentError, "manifest must be an Phronomy::Context::LLMInputManifest"
         end
 
         groups = project_visible_groups(manifest)
@@ -42,12 +29,12 @@ module Phronomy
               policy_category: group.fetch(:policy_category),
               persistence: persistence,
               source_agent: source_agent,
-              target_agent: request.handoff.target_agent
+              target_agent: Identity.new(agent_id: request.target_agent_id)
             )
           end
         end
 
-        HandoffContext.new(
+        TransferContext.new(
           responsibility: request.responsibility,
           items: items
         )
@@ -116,7 +103,7 @@ module Phronomy
         end
 
         # Compatibility for finalized pre-ACS-04 manifests. New manifests use
-        # context_policy_conversation_group_id and do not recreate Selection::Unit.
+        # context_policy_conversation_group_id and do not recreate Phronomy::Context::Unit.
         unit_id = segment.metadata["selection_unit_id"] ||
           segment.metadata[:selection_unit_id]
         return "unit:#{unit_id}" if unit_id
@@ -125,13 +112,7 @@ module Phronomy
       end
 
       def include_group?(request, category)
-        policy = request.handoff.policy
-        return true if policy.required?(category)
-        return false if policy.forbidden?(category)
-
-        request.selection_intent.fetch(category) do
-          policy.default_include?(category)
-        end
+        request.selection.fetch(category, false)
       end
 
       def materialize_item(segment, policy_category:, persistence:, source_agent:, target_agent:)
@@ -147,7 +128,7 @@ module Phronomy
           target_agent: target_agent
         )
 
-        HandoffContext::Item.new(
+        TransferContext::Item.new(
           candidate_category: category,
           policy_category: policy_category,
           role: segment.role,
@@ -169,7 +150,7 @@ module Phronomy
           metadata[:context_policy_content_format]
         if explicit
           format = explicit.to_sym
-          unless Phronomy::Agent::ContextPolicyInput::CONTENT_FORMATS.include?(format)
+          unless Phronomy::Context::ContextPolicyInput::CONTENT_FORMATS.include?(format)
             raise Phronomy::HandoffError,
               "unsupported Context content format in Manifest: #{explicit.inspect}"
           end
@@ -182,7 +163,7 @@ module Phronomy
       def provenance_for(metadata, segment:, source_agent:, target_agent:)
         inherited = metadata["handoff_provenance"]
         if inherited
-          base = HandoffContext::Provenance.new(
+          base = TransferContext::Provenance.new(
             origin_agent_id: inherited["origin_agent_id"] || inherited[:origin_agent_id],
             origin_record_id: inherited["origin_record_id"] || inherited[:origin_record_id],
             origin_execution_id: inherited["origin_execution_id"] || inherited[:origin_execution_id],
@@ -193,7 +174,7 @@ module Phronomy
           return base.forwarded_to(target_agent.agent_id)
         end
 
-        HandoffContext::Provenance.new(
+        TransferContext::Provenance.new(
           origin_agent_id: metadata["source_agent_id"] || source_agent.agent_id,
           origin_record_id: metadata["journal_record_id"],
           origin_execution_id: metadata["source_execution_id"],

data/lib/phronomy/{llm_contract/transport_error.rb → agent/handoff_error.rb}

@@ -3,5 +3,5 @@
 require_relative "../common/error"
 
 module Phronomy
-  class TransportError < Error; end
+  class HandoffError < Error; end
 end

data/lib/phronomy/agent/journal/journal_projection.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../engine/concurrency/worker_input_restricted"
+require_relative "../../execution/concurrency/worker_input_restricted"
 
 module Phronomy
   module Agent

data/lib/phronomy/agent/knowledge_item.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Materialized knowledge accepted by create(knowledge:) without internal DTOs.
+    # @api public
+    KnowledgeItem = Data.define(:content, :metadata) do
+      def initialize(content:, metadata: {})
+        super(content: String(content).dup.freeze, metadata: Phronomy::Values::Immutable.copy(metadata))
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/agent_root.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../engine/concurrency/worker_input_restricted"
+require_relative "../../execution/concurrency/worker_input_restricted"
 
 require "time"
 

data/lib/phronomy/agent/lifecycle/ownership_registry.rb

@@ -12,21 +12,16 @@ module Phronomy
       # Candidates have no side effects. Runtime retains the first registration.
       # Existing instances remain available for lookup and transition completion
       # after admission closes; their own gate rejects new ownership changes.
-      def self.for(runtime)
-        existing_for(runtime) || runtime.__register_shutdown_participant(
-          key: self, participant: new(runtime: runtime)
-        )
-      end
-
-      def self.existing_for(runtime)
-        runtime.__shutdown_participant(key: self)
-      end
+      def self.current = ExecutionEnvironment.current.ownership
+      def self.existing_current = ExecutionEnvironment.current.existing_ownership
+      def self.for(environment) = environment.ownership
+      def self.existing_for(environment) = environment.existing_ownership
 
       Entry = Data.define(:state, :agent, :token)
       private_constant :Entry
 
-      def initialize(runtime:)
-        @runtime = runtime
+      def initialize(environment:)
+        @environment = environment
         @mutex = Mutex.new
         @condition = ConditionVariable.new
         @entries = {}
@@ -38,11 +33,11 @@ module Phronomy
         token = reserve_create!(key)
 
         begin
-          agent = yield(@runtime)
+          agent = yield(@environment)
         rescue Phronomy::AgentAlreadyExistsError,
-          Phronomy::Storage::ConflictError,
-          Phronomy::Storage::NotFoundError,
-          Phronomy::Storage::SerializationError,
+          Phronomy::Persistence::ConflictError,
+          Phronomy::Persistence::NotFoundError,
+          Phronomy::Persistence::SerializationError,
           ArgumentError,
           Phronomy::ConfigurationError
           release_construction!(key, token)
@@ -98,7 +93,7 @@ module Phronomy
         end
 
         begin
-          agent = yield(@runtime)
+          agent = yield(@environment)
           publish_constructed!(
             key,
             token,
@@ -161,7 +156,7 @@ module Phronomy
           end
           @entries[key] = Entry.new(state: :purging, agent: agent, token: token)
         end
-        agent.send(:__mark_purging!, @runtime)
+        agent.send(:__mark_purging!, @environment)
         token
       end
 
@@ -170,7 +165,7 @@ module Phronomy
         @mutex.synchronize do
           entry = @entries[key]
           validate_purge_entry!(entry, agent, token, key)
-          agent.send(:__mark_purged!, @runtime)
+          agent.send(:__mark_purged!, @environment)
           @entries.delete(key)
           @condition.broadcast
         end
@@ -183,7 +178,7 @@ module Phronomy
         @mutex.synchronize do
           entry = @entries[key]
           validate_purge_entry!(entry, agent, token, key)
-          agent.send(:__restore_live_after_purge_abort!, @runtime)
+          agent.send(:__restore_live_after_purge_abort!, @environment)
           @entries[key] = Entry.new(state: :live, agent: agent, token: nil)
           @condition.broadcast
         end
@@ -197,7 +192,7 @@ module Phronomy
         key = normalize_agent_id(agent.agent_id)
         @mutex.synchronize do
           validate_purge_entry!(@entries[key], agent, token, key)
-          agent.send(:__mark_ownership_recovery_required!, @runtime)
+          agent.send(:__mark_ownership_recovery_required!, @environment)
           @entries[key] = Entry.new(
             state: :recovery_required,
             agent: agent,
@@ -239,7 +234,7 @@ module Phronomy
           @condition.broadcast
           owned
         end
-        agents.each { |agent| agent.send(:__release_runtime_owner!, @runtime) }
+        agents.each { |agent| agent.send(:__release_runtime_owner!, @environment) }
         true
       end
 
@@ -267,7 +262,7 @@ module Phronomy
             "constructed Agent identity mismatch: reserved #{key.inspect}, got #{agent.agent_id.inspect}"
         end
 
-        agent.send(:__bind_runtime_owner!, @runtime)
+        agent.send(:__bind_runtime_owner!, @environment)
         @mutex.synchronize do
           entry = @entries[key]
           unless entry&.state == :constructing && entry.token.equal?(token)
@@ -282,7 +277,7 @@ module Phronomy
         # :nocov:
         if fail_closed
           fail_construction_closed!(key, token, agent: agent)
-          agent&.send(:__mark_ownership_recovery_required!, @runtime)
+          agent&.send(:__mark_ownership_recovery_required!, @environment)
         else
           release_construction!(key, token)
         end

data/lib/phronomy/agent/persistence/agent_repository.rb

@@ -9,39 +9,47 @@ module Phronomy
         def initialize(view) = @view = view
 
         def create(root)
-          record = Codec.encode_agent_root(root)
-          @view.atomic do |bound|
-            entry = bound.records(StorageSchema::ROOTS).insert(key: root.agent_id.to_s,
-              revision: Integer(root.agent_revision), attributes: {}, record: record)
-            decode(entry, root.agent_id, revision: root.agent_revision)
+          Phronomy::Persistence::StorageBoundary.call do
+            record = Codec.encode_agent_root(root)
+            @view.atomic do |bound|
+              entry = bound.records(StorageSchema::ROOTS).insert(key: root.agent_id.to_s,
+                revision: Integer(root.agent_revision), attributes: {}, record: record)
+              decode(entry, root.agent_id, revision: root.agent_revision)
+            end
           end
         end
 
         def load(agent_id)
-          value = @view.atomic do |bound|
-            entry = bound.records(StorageSchema::ROOTS).read(agent_id.to_s)
-            entry && decode(entry, agent_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            value = @view.atomic do |bound|
+              entry = bound.records(StorageSchema::ROOTS).read(agent_id.to_s)
+              entry && decode(entry, agent_id)
+            end
+            value || raise(Phronomy::Storage::NotFoundError, "Agent not found: #{agent_id}")
           end
-          value || raise(Phronomy::Storage::NotFoundError, "Agent not found: #{agent_id}")
         end
 
         def save(agent_id, expected_revision:, root:)
-          expected = Integer(expected_revision)
-          revision = Integer(root.agent_revision)
-          raise Phronomy::Storage::ConflictError, "root save must advance revision exactly once" unless revision == expected + 1
-          unless root.agent_id.to_s == agent_id.to_s
-            raise Phronomy::Storage::SerializationError, "Agent root identity mismatch"
-          end
-          record = Codec.encode_agent_root(root)
-          @view.atomic do |bound|
-            entry = bound.records(StorageSchema::ROOTS).replace(key: agent_id.to_s,
-              expected_revision: expected, next_revision: revision, attributes: {}, record: record)
-            decode(entry, agent_id, revision: revision)
+          Phronomy::Persistence::StorageBoundary.call do
+            expected = Integer(expected_revision)
+            revision = Integer(root.agent_revision)
+            raise Phronomy::Storage::ConflictError, "root save must advance revision exactly once" unless revision == expected + 1
+            unless root.agent_id.to_s == agent_id.to_s
+              raise Phronomy::Storage::SerializationError, "Agent root identity mismatch"
+            end
+            record = Codec.encode_agent_root(root)
+            @view.atomic do |bound|
+              entry = bound.records(StorageSchema::ROOTS).replace(key: agent_id.to_s,
+                expected_revision: expected, next_revision: revision, attributes: {}, record: record)
+              decode(entry, agent_id, revision: revision)
+            end
           end
         end
 
         def delete(agent_id)
-          @view.records(StorageSchema::ROOTS).delete(key: agent_id.to_s)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.records(StorageSchema::ROOTS).delete(key: agent_id.to_s)
+          end
         end
 
         private