phronomy 0.25.0 → 0.27.0

data/lib/phronomy/generation/generator_verifier/pipeline_state.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    class PipelineState
+      include Phronomy::WorkflowContext
+
+      field :input, type: :replace, default: -> { "" }
+      field :draft, type: :replace, default: -> { {} }
+      field :self_score, type: :replace, default: -> { 0.0 }
+      field :review_score, type: :replace, default: -> { 0.0 }
+      field :citations, type: :replace, default: -> { [] }
+      field :review_notes, type: :append, default: -> { [] }
+      field :iteration, type: :replace, default: -> { 0 }
+      field :approved, type: :replace, default: -> { false }
+      field :output, type: :replace, default: -> { {} }
+      field :draft_request_id, type: :replace, default: nil
+      field :review_request_id, type: :replace, default: nil
+      field :pipeline_error, type: :replace, default: nil
+
+      # Application-level event interpretation. Correlation IDs belong to this
+      # Pipeline rather than to the generic FSMSession.
+      def handle_fsm_event(event)
+        case event.type
+        when :draft_completed
+          return :consume unless event.payload[:request_id] == draft_request_id
+
+          self.draft = event.payload[:draft]
+          self.self_score = event.payload[:self_score]
+          self.citations = event.payload[:citations]
+          self.iteration = iteration + 1
+          self.draft_request_id = nil
+          self.pipeline_error = nil
+        when :review_completed
+          return :consume unless event.payload[:request_id] == review_request_id
+
+          self.review_score = event.payload[:review_score]
+          self.approved = event.payload[:approved]
+          self.review_notes = review_notes + [event.payload[:feedback]]
+          self.review_request_id = nil
+          self.pipeline_error = nil
+        when :draft_failed
+          return :consume unless event.payload[:request_id] == draft_request_id
+
+          self.pipeline_error = event.payload[:error]
+          self.draft_request_id = nil
+        when :review_failed
+          return :consume unless event.payload[:request_id] == review_request_id
+
+          self.pipeline_error = event.payload[:error]
+          self.review_request_id = nil
+        end
+        false
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/workflow_builder.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Phronomy
+  class GeneratorVerifier
+    # Builds the generation/review loop; result reception does not mutate state.
+    class WorkflowBuilder
+      def initialize(
+        draft_agent:, review_agent:,
+        draft_prompt_builder:, review_prompt_builder:,
+        draft_result_parser:, review_result_parser:,
+        threshold:, max_iterations:
+      )
+        @draft_agent = draft_agent
+        @review_agent = review_agent
+        @draft_prompt_builder = draft_prompt_builder
+        @review_prompt_builder = review_prompt_builder
+        @threshold = threshold
+        @max_iterations = max_iterations
+        @result_receiver = AgentResultReceiver.new(
+          draft_result_parser: draft_result_parser,
+          review_result_parser: review_result_parser
+        )
+      end
+
+      def build
+        # The entry closures see the Workflow assigned after definition.
+        workflow = nil
+        draft_entry = ->(state) { start_draft(state, workflow) }
+        review_entry = ->(state) { start_review(state, workflow) }
+        finalize_entry = method(:finalize)
+        failed_entry = method(:fail_pipeline)
+        ready_to_finalize = method(:ready_to_finalize?)
+
+        workflow = Phronomy::Workflow.define(PipelineState) do
+          initial :draft
+
+          state :draft
+          state :review
+          state :finalize
+          state :failed
+
+          entry :draft, draft_entry
+          entry :review, review_entry
+          entry :finalize, finalize_entry
+          entry :failed, failed_entry
+
+          transition from: :draft, on: :draft_completed, to: :review
+          transition from: :draft, on: :draft_failed, to: :failed
+          transition from: :review,
+            on: :review_completed,
+            guard: ready_to_finalize,
+            to: :finalize
+          transition from: :review, on: :review_completed, to: :draft
+          transition from: :review, on: :review_failed, to: :failed
+
+          transition from: :finalize, to: :__finish__
+        end
+      end
+
+      private
+
+      def start_draft(state, workflow)
+        request_id = SecureRandom.uuid
+        next_state = state.merge(draft_request_id: request_id)
+        feedback = next_state.review_notes.last
+        prompt = @draft_prompt_builder.call(next_state.input, feedback)
+        listener = @result_receiver.draft_listener(
+          workflow: workflow,
+          workflow_instance_id: next_state.workflow_instance_id,
+          request_id: request_id
+        )
+        @draft_agent.send(:__invoke_async_with_event_sink, prompt, on_event: listener)
+        next_state
+      end
+
+      def start_review(state, workflow)
+        request_id = SecureRandom.uuid
+        next_state = state.merge(review_request_id: request_id)
+        prompt = @review_prompt_builder.call(
+          next_state.input, next_state.draft, next_state.citations
+        )
+        listener = @result_receiver.review_listener(
+          workflow: workflow,
+          workflow_instance_id: next_state.workflow_instance_id,
+          request_id: request_id
+        )
+        @review_agent.send(:__invoke_async_with_event_sink, prompt, on_event: listener)
+        next_state
+      end
+
+      def ready_to_finalize?(state)
+        confidence = [state.self_score || 0.0, state.review_score || 0.0].min
+        (confidence >= @threshold && state.approved) ||
+          state.iteration >= @max_iterations
+      end
+
+      def finalize(state)
+        state.output = state.draft
+        state
+      end
+
+      def fail_pipeline(state)
+        raise(
+          state.pipeline_error ||
+          Phronomy::Error.new("GeneratorVerifier Agent operation failed")
+        )
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Implements the Generator-Verifier multi-agent coordination pattern.
+  #
+  # Agent completion is integrated through application-defined Workflow events;
+  # Workflow entry actions do not return or await Agent Tasks.
+  class GeneratorVerifier
+    DEFAULT_CONFIDENCE_THRESHOLD = 0.7
+    DEFAULT_MAX_ITERATIONS = 3
+
+    Result = Struct.new(
+      :output,
+      :confidence,
+      :citations,
+      :iterations,
+      :review_notes,
+      :trusted
+    ) do
+      alias_method :trusted?, :trusted
+    end
+
+    private_constant :PipelineState, :WorkflowBuilder, :AgentResultReceiver
+
+    def initialize(
+      draft_agent:,
+      review_agent:,
+      draft_prompt_builder:,
+      review_prompt_builder:,
+      draft_result_parser: nil,
+      review_result_parser: nil,
+      confidence_threshold: DEFAULT_CONFIDENCE_THRESHOLD,
+      max_iterations: DEFAULT_MAX_ITERATIONS,
+      raise_if_untrusted: false
+    )
+      @draft_agent_class = draft_agent
+      @review_agent_class = review_agent
+      @draft_prompt_builder = draft_prompt_builder
+      @review_prompt_builder = review_prompt_builder
+      @draft_result_parser =
+        draft_result_parser || method(:default_parse_draft)
+      @review_result_parser =
+        review_result_parser || method(:default_parse_review)
+      @threshold = confidence_threshold.to_f
+      @max_iterations = max_iterations.to_i
+      @raise_if_untrusted = raise_if_untrusted
+      @compiled_workflow = nil
+    end
+
+    def invoke(input, config: {})
+      state = compiled_workflow.invoke({input: input}, config: config)
+      confidence = combined_confidence(state)
+      trusted = confidence >= @threshold
+      result = Result.new(
+        output: state.output || state.draft.to_s,
+        confidence: confidence,
+        citations: state.citations,
+        iterations: state.iteration,
+        review_notes: state.review_notes,
+        trusted: trusted
+      )
+      if @raise_if_untrusted && !trusted
+        raise LowConfidenceError.new(result)
+      end
+      result
+    end
+
+    private
+
+    def combined_confidence(state)
+      [
+        (state.self_score || 0.0).to_f,
+        (state.review_score || 0.0).to_f
+      ].min
+    end
+
+    def compiled_workflow
+      @compiled_workflow ||= build_workflow
+    end
+
+    def build_workflow
+      WorkflowBuilder.new(
+        draft_agent: @draft_agent_class.new,
+        review_agent: @review_agent_class.new,
+        draft_prompt_builder: @draft_prompt_builder,
+        review_prompt_builder: @review_prompt_builder,
+        draft_result_parser: @draft_result_parser,
+        review_result_parser: @review_result_parser,
+        threshold: @threshold,
+        max_iterations: @max_iterations
+      ).build
+    end
+
+    def default_parse_draft(text)
+      json_parser.parse(text)
+    rescue Phronomy::ParseError
+      {
+        answer: text.to_s,
+        confidence: 0.0,
+        citations: []
+      }
+    end
+
+    def default_parse_review(text)
+      json_parser.parse(text)
+    rescue Phronomy::ParseError
+      {
+        approved: false,
+        score: 0.0,
+        feedback: "Review output could not be parsed: #{text}"
+      }
+    end
+
+    def json_parser
+      @json_parser ||= Phronomy::OutputParser::JsonParser.new
+    end
+  end
+end

data/lib/phronomy/generation/low_confidence_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class LowConfidenceError < Error
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+      super("Answer confidence #{result.confidence} is below the required threshold")
+    end
+  end
+end

data/lib/phronomy/llm_adapter/base.rb

@@ -52,7 +52,7 @@ module Phronomy
       # Transport timeout and retry remain the responsibility of the adapter or
       # provider client; Phronomy does not attach an additional operation timeout.
       #
-      # @return [Phronomy::Task] caller-facing completion handle
+      # @return [Phronomy::TaskResult] caller-facing completion handle
       # @api private
       def complete_async(chat, message, config: {}, pool: default_pool)
         token = config[:cancellation_token]
@@ -68,7 +68,7 @@ module Phronomy
       # application callbacks must never be passed directly to this method.
       #
       # @yield [chunk] streaming chunk on the worker thread
-      # @return [Phronomy::Task] caller-facing completion handle
+      # @return [Phronomy::TaskResult] caller-facing completion handle
       # @api private
       def stream_async(chat, message, config: {}, pool: default_pool, &block)
         raise ArgumentError, "stream_async requires a block" unless block

data/lib/phronomy/llm_context_window/token_budget.rb

@@ -2,20 +2,19 @@
 
 module Phronomy
   module LlmContextWindow
-    # Immutable arithmetic value for one resolved model context budget.
-    # Model-registry lookup belongs to Agent::TokenBudgetResolver.
+    # Immutable input-budget arithmetic. RubyLLM owns model capabilities.
     class TokenBudget
-      attr_reader :context_window, :max_output_tokens
+      attr_reader :max_input_tokens
 
       # @api private
-      def initialize(context_window:, max_output_tokens:)
-        @context_window = Integer(context_window)
-        @max_output_tokens = Integer(max_output_tokens)
+      def initialize(max_input_tokens:)
+        @max_input_tokens = Integer(max_input_tokens)
+        raise ArgumentError, "max_input_tokens must be positive" unless @max_input_tokens.positive?
       end
 
       # @api private
       def effective_input_limit
-        [@context_window - @max_output_tokens, 0].max
+        @max_input_tokens
       end
 
       # @api private

data/lib/phronomy/llm_contract/authentication_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "transport_error"
+
+module Phronomy
+  class AuthenticationError < TransportError; end
+end

data/lib/phronomy/{context_budget_exceeded_error.rb → llm_contract/context_budget_exceeded_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../common/error"
+
 module Phronomy
   # Raised when mandatory context content (system instructions, tool definitions,
   # current input) exhausts the model's context window, leaving no room for

data/lib/phronomy/llm_contract/context_length_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class ContextLengthError < Error; end
+end

data/lib/phronomy/llm_contract/rate_limit_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "transport_error"
+
+module Phronomy
+  class RateLimitError < TransportError; end
+end

data/lib/phronomy/{token_usage.rb → llm_contract/token_usage.rb}

@@ -43,8 +43,8 @@ module Phronomy
       new(
         input: tokens.input || 0,
         output: tokens.output || 0,
-        cached: tokens.cached || 0,
-        cache_creation: tokens.cache_creation || 0
+        cached: tokens.cache_read || 0,
+        cache_creation: tokens.cache_write || 0
       )
     end
 

data/lib/phronomy/llm_contract/transport_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class TransportError < Error; end
+end

data/lib/phronomy/multi_agent/admission_registry.rb

@@ -2,18 +2,32 @@
 
 module Phronomy
   module MultiAgent
-    # Runtime-local admission for one user-facing coordination turn per main Agent.
-    # This owns exclusion only; active-agent mutation still belongs to EventLoop.
+    # Runtime-local admission for one synchronous coordination call per owner
+    # (a Handoff main Agent or TeamCoordinator). This does not own durable runs
+    # or active-agent mutation; those remain in their existing domains.
+    # @api private
     class AdmissionRegistry
+      # Construction has no side effects. Runtime returns the registered instance
+      # when callers concurrently supply candidates for the same key.
+      # @api private
+      def self.for(runtime)
+        runtime.__register_shutdown_participant(key: self, participant: new)
+      end
+
       def initialize
         @mutex = Mutex.new
         @cond = ConditionVariable.new
         @owners = {}
+        @draining = false
       end
 
       def admit!(coordinator)
         key = coordinator.object_id
         @mutex.synchronize do
+          if @draining
+            raise Phronomy::RuntimeShutdownError,
+              "Runtime is shutting down or failed; new Multi-Agent turns are not accepted"
+          end
           if @owners.key?(key)
             raise Phronomy::HandoffError,
               "a Multi-Agent turn is already active for this main Agent instance"
@@ -36,6 +50,12 @@ module Phronomy
         @mutex.synchronize { @owners.empty? }
       end
 
+      # Close admission atomically with respect to admit!, without waiting for
+      # admitted callers or calling back into Runtime. Repeated closure is safe.
+      def begin_draining
+        @mutex.synchronize { @draining = true }
+      end
+
       def wait_until_idle(deadline)
         @mutex.synchronize do
           until @owners.empty?

data/lib/phronomy/multi_agent/durable_subagent_coordinator.rb

@@ -4,7 +4,7 @@ require "securerandom"
 
 module Phronomy
   module MultiAgent
-    # Agent-owned transactions reserve child work; Task callbacks only wake observers.
+    # Agent-owned transactions reserve child work; TaskResult callbacks only wake observers.
     # @api private
     class DurableSubagentCoordinator
       KEY = "multi_agent_coordination_ref"
@@ -16,13 +16,13 @@ module Phronomy
         children.each do |child|
           begin
             exact = tx.executions.load(child.fetch("execution_id"))
-          rescue Phronomy::Persistence::NotFoundError
+          rescue Phronomy::Storage::NotFoundError
             next
           end
-          raise Phronomy::Persistence::ConflictError, "Child owner mismatch" unless exact.agent_id == child.fetch("agent_id")
+          raise Phronomy::Storage::ConflictError, "Child owner mismatch" unless exact.agent_id == child.fetch("agent_id")
           child.merge!("state" => exact.status.to_s, "result_ref" => exact.result_ref, "error_ref" => exact.error_ref)
         end
-        Array(execution.metadata[Phronomy::Agent::RecoverySupport::TOOL_BATCH_METADATA_KEY]).each do |tool|
+        Array(execution.metadata[Phronomy::Agent::ExecutionMetadata::TOOL_BATCH_METADATA_KEY]).each do |tool|
           registration = parent.class.registered_subagents.find { |name, _| "dispatch_to_#{name}" == tool.fetch("tool_name") }
           next unless registration
           next if children.any? { |child| child.fetch("slot") == tool.fetch("tool_invocation_id") }
@@ -47,10 +47,10 @@ module Phronomy
 
       def self.start(parent:, tool_invocation_id:, parent_execution_id:, config:)
         runtime = Phronomy::Runtime.instance
-        completion = Phronomy::Task.deferred(name: "durable-subagent:#{tool_invocation_id}")
+        completion = Phronomy::TaskResult.deferred(name: "durable-subagent:#{tool_invocation_id}")
         preparation = runtime.offload.submit(on_full: :raise) do
           current = parent.persistence.executions.load(parent_execution_id)
-          raise Phronomy::Persistence::ConflictError, "Parent owner mismatch" unless current.agent_id == parent.agent_id
+          raise Phronomy::Storage::ConflictError, "Parent owner mismatch" unless current.agent_id == parent.agent_id
           snapshot = parent.persistence.contents.fetch_json(current.metadata.fetch(KEY))
           child = snapshot.fetch("children").find { |entry| entry.fetch("slot") == tool_invocation_id }
           raise Phronomy::ExecutionRehydrationRequiredError, "Missing reserved child slot" unless child
@@ -65,7 +65,7 @@ module Phronomy
             begin
               parent.persistence.agents.load(id)
               exists = true
-            rescue Phronomy::Persistence::NotFoundError
+            rescue Phronomy::Storage::NotFoundError
               exists = false
             end
             listener = parent.send(:_phronomy_event_listener)
@@ -125,7 +125,7 @@ module Phronomy
         end
         completion
       rescue => error
-        completion ||= Phronomy::Task.deferred(name: "durable-subagent")
+        completion ||= Phronomy::TaskResult.deferred(name: "durable-subagent")
         completion.fail(error)
         completion
       end

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

@@ -3,8 +3,8 @@
 require "time"
 
 module Phronomy
-  module Agent
-    # Durable Agent-domain responsibility routing within one Persistence instance.
+  module MultiAgent
+    # Coordinates durable handoffs across Agents using one Persistence instance.
     # @api public
     class HandoffRunner
       MAX_HANDOFFS = 20
@@ -16,7 +16,7 @@ module Phronomy
       def initialize(main_agent:, handoffs: [])
         @main_agent, @handoffs = main_agent, Array(handoffs).freeze
         @persistence = main_agent.persistence
-        raise ArgumentError, "handoffs must contain Agent::Handoff" unless @handoffs.all? { |h| h.is_a?(Handoff) }
+        raise ArgumentError, "handoffs must contain Agent::Handoff" unless @handoffs.all? { |h| h.is_a?(Phronomy::Agent::Handoff) }
         @agents = ([main_agent] + @handoffs.flat_map { |edge| [edge.source_agent, edge.target_agent] }).uniq.to_h { |a| [a.agent_id, a] }.freeze
         unless @agents.values.all? { |a| a.persistence.equal?(@persistence) }
           raise Phronomy::ConfigurationError, "Durable Handoff graph requires one Persistence instance"
@@ -24,8 +24,9 @@ module Phronomy
         if @handoffs.group_by { |h| [h.source_agent.agent_id, h.target_agent.agent_id] }.any? { |_, edges| edges.size > 1 }
           raise ArgumentError, "Duplicate Source/Target Handoff edges"
         end
-        @bindings = @handoffs.group_by { |h| h.source_agent.agent_id }.transform_values { |edges| edges.map { |h| HandoffCapabilityFactory.build(h) }.freeze }.freeze
+        @bindings = @handoffs.group_by { |h| h.source_agent.agent_id }.transform_values { |edges| edges.map { |h| Phronomy::Agent::HandoffCapabilityFactory.build(h) }.freeze }.freeze
         @runtime = Phronomy::Runtime.instance
+        @admissions = Phronomy::MultiAgent::AdmissionRegistry.for(@runtime)
       end
 
       # @api public
@@ -41,7 +42,7 @@ module Phronomy
           raise Phronomy::RuntimeShutdownError, "HandoffRunner belongs to a previous Runtime"
         end
         config = config.merge(cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new)
-        @runtime.__admit_multi_agent(main_agent)
+        @admissions.admit!(main_agent)
         admitted = true
         state = load_state
         count = 0
@@ -49,7 +50,7 @@ module Phronomy
           active = @agents.fetch(state.active_agent_id) do
             raise Phronomy::ExecutionRehydrationRequiredError, "Handoff graph lacks active Agent #{state.active_agent_id}"
           end
-          context = state.active_handoff_context_ref && HandoffContext.from_h(@persistence.contents.fetch_json(state.active_handoff_context_ref))
+          context = state.active_handoff_context_ref && Phronomy::Agent::HandoffContext.from_h(@persistence.contents.fetch_json(state.active_handoff_context_ref))
           wiring = config.merge(phronomy_handoff_bindings: @bindings.fetch(active.agent_id, []),
             phronomy_handoff_context: context,
             phronomy_coordination: {"kind" => "handoff", "main_agent_id" => main_agent.agent_id, "handoff_revision" => state.handoff_revision}).freeze
@@ -61,11 +62,11 @@ module Phronomy
             else
               exact = unfinished.fetch(0)
               unless unfinished.size == 1 && exact.metadata.dig("coordination", "main_agent_id") == main_agent.agent_id
-                raise Phronomy::Persistence::ConflictError, "Active Agent execution belongs to another coordination turn"
+                raise Phronomy::Storage::ConflictError, "Active Agent execution belongs to another coordination turn"
               end
               wiring[:cancellation_token].cancel! if Array(state.metadata["cancelled_execution_ids"]).include?(exact.execution_id)
               stored_input = @persistence.contents.fetch_text(exact.metadata.fetch("current_input_ref"))
-              ExactExecution.start(agent: active, execution_id: exact.execution_id, input: stored_input, config: wiring).wait_result
+              Phronomy::Agent::ExactExecution.start(agent: active, execution_id: exact.execution_id, input: stored_input, config: wiring).wait_result
             end
           else
             source = @persistence.executions.load(state.pending_source_execution_id)
@@ -77,7 +78,7 @@ module Phronomy
               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)
-            ExactExecution.start(agent: active, execution_id: state.pending_target_execution_id,
+            Phronomy::Agent::ExactExecution.start(agent: active, execution_id: state.pending_target_execution_id,
               input: context.responsibility, config: wiring).wait_result
           end
           execution = @persistence.executions.load(result.fetch(:execution_id))
@@ -90,7 +91,7 @@ module Phronomy
           if execution.active?
             raise Phronomy::ExecutionRehydrationRequiredError, "Handoff execution requires approval or recovery"
           end
-          raise RecoverySupport.error_from_failure(result[:error]) if result[:error]
+          raise Phronomy::Agent::RecoverySupport.error_from_failure(result[:error]) if result[:error]
           return result.reject { |key, _| key.to_s.start_with?("_phronomy_") || key == :handoff_request }.merge(agent: active)
         end
       rescue Phronomy::CancellationError => error
@@ -101,7 +102,7 @@ module Phronomy
         operation_error = error
         raise
       ensure
-        @runtime.__release_multi_agent(main_agent) if admitted
+        @admissions.release!(main_agent) if admitted
         Phronomy::Tracing::Automatic.finish(trace_handle, output: result && result[:output], error: operation_error)
       end
 
@@ -117,25 +118,25 @@ module Phronomy
           @persistence.transaction do |tx|
             first = tx.executions.load(execution_id)
             unless first.metadata.dig("coordination", "main_agent_id") == main_agent.agent_id
-              raise Phronomy::Persistence::ConflictError, "Execution does not belong to this Handoff anchor"
+              raise Phronomy::Storage::ConflictError, "Execution does not belong to this Handoff anchor"
             end
             leaf = first
             leaf_id = first.execution_id
             seen = {}
             while leaf&.status == :handed_off
-              raise Phronomy::Persistence::SerializationError, "Cyclic Handoff chain" if seen[leaf_id]
+              raise Phronomy::Storage::SerializationError, "Cyclic Handoff chain" if seen[leaf_id]
               seen[leaf_id] = true
               leaf_id = leaf.metadata.fetch("handoff_target_execution_id")
               begin
                 leaf = tx.executions.load(leaf_id)
-              rescue Phronomy::Persistence::NotFoundError
+              rescue Phronomy::Storage::NotFoundError
                 leaf = nil
               end
             end
             next if leaf&.terminal?
             routing = tx.handoff_states.load(main_agent.agent_id)
             unless routing && (leaf ? routing.active_agent_id == leaf.agent_id : routing.pending_target_execution_id == leaf_id)
-              raise Phronomy::Persistence::ConflictError, "Handoff routing no longer owns the requested turn"
+              raise Phronomy::Storage::ConflictError, "Handoff routing no longer owns the requested turn"
             end
             ids = (Array(routing.metadata["cancelled_execution_ids"]) + [leaf_id]).uniq
             intended = routing.with(phase: leaf ? routing.phase : "stable",
@@ -147,7 +148,7 @@ module Phronomy
           raise error unless intended && confirmed && Array(confirmed.metadata["cancelled_execution_ids"]).include?(leaf_id)
         end
         return @persistence.execution_result(leaf_id) if leaf&.terminal?
-        ExecutionCancellation.signal(leaf_id, leaf.agent_id) if leaf&.active?
+        Phronomy::Agent::ExecutionCancellation.signal(leaf_id, leaf.agent_id) if leaf&.active?
         {execution_id: leaf_id, cancellation_requested: !leaf&.terminal?}.freeze
       end
 
@@ -163,7 +164,7 @@ module Phronomy
         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,
+        initial = Phronomy::Agent::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: {})