phronomy 0.27.0 → 0.29.0

data/lib/phronomy/agent/recovery/recovery_coordinator/installation.rb

@@ -38,7 +38,7 @@ module Phronomy
         end
 
         def prepare_plan(execution)
-          root = agent.agent_root
+          root = agent.send(:__root_for_operation)
           manifest_ref = execution.metadata["manifest_ref"]
           base_ref = execution.metadata["base_manifest_ref"] ||
             manifest_ref
@@ -70,7 +70,7 @@ module Phronomy
 
         def classify(execution)
           if framework_batch?(execution)
-            return Phronomy::Recovery::Classification.new(disposition: Phronomy::Recovery::RESUMABLE, reason: :framework_tools)
+            return Phronomy::Agent::RecoveryRules::Classification.new(disposition: Phronomy::Agent::RecoveryRules::RESUMABLE, reason: :framework_tools)
           end
           if execution.status == :preparing &&
               execution.phase.to_sym == :preparing
@@ -79,16 +79,16 @@ module Phronomy
                 "execution #{execution.execution_id} is :preparing but replay safety " \
                   "was not durably established"
             end
-            return Phronomy::Recovery::Classification.new(
-              disposition: Phronomy::Recovery::RESUMABLE,
+            return Phronomy::Agent::RecoveryRules::Classification.new(
+              disposition: Phronomy::Agent::RecoveryRules::RESUMABLE,
               reason: :initial_preparation
             )
           end
 
           if execution.status == :suspended &&
               execution.phase.to_sym == :approval
-            return Phronomy::Recovery::Classification.new(
-              disposition: Phronomy::Recovery::RESUMABLE,
+            return Phronomy::Agent::RecoveryRules::Classification.new(
+              disposition: Phronomy::Agent::RecoveryRules::RESUMABLE,
               reason: :approval_wait,
               facts: {
                 approval_request_id:
@@ -105,8 +105,8 @@ module Phronomy
           when :recovery_provider_completed,
             :recovery_tools_completed,
             :recovery_resolved_failed
-            return Phronomy::Recovery::Classification.new(
-              disposition: Phronomy::Recovery::RESUMABLE,
+            return Phronomy::Agent::RecoveryRules::Classification.new(
+              disposition: Phronomy::Agent::RecoveryRules::RESUMABLE,
               reason: execution.phase
             )
           when :resuming
@@ -116,8 +116,8 @@ module Phronomy
                 execution.approval_request[:approved]
               )
             unless approved
-              return Phronomy::Recovery::Classification.new(
-                disposition: Phronomy::Recovery::RESUMABLE,
+              return Phronomy::Agent::RecoveryRules::Classification.new(
+                disposition: Phronomy::Agent::RecoveryRules::RESUMABLE,
                 reason: :approval_rejection_committed
               )
             end
@@ -127,8 +127,8 @@ module Phronomy
             execution
           )
           if descriptor
-            return Phronomy::Recovery::Classification.new(
-              disposition: Phronomy::Recovery::RESOLUTION_REQUIRED,
+            return Phronomy::Agent::RecoveryRules::Classification.new(
+              disposition: Phronomy::Agent::RecoveryRules::RESOLUTION_REQUIRED,
               reason: descriptor.fetch(:reason),
               subject: descriptor.fetch(:subject),
               allowed_outcomes:
@@ -143,20 +143,20 @@ module Phronomy
         end
 
         def install_on_event_loop(command)
-          event_loop = @runtime.event_loop
+          environment = @environment
           plan = command.plan
           execution = plan.execution
-          main = agent.send(:execution_coordinator_for, agent.__coordination_config)
+          main = agent.send(:execution_coordinator_for, agent.__execution_wiring)
           admitted = false
           bound = false
           installed = false
 
-          Phronomy::Agent::ExecutionRegistry.for(event_loop).admit_agent_execution(
+          environment.registry.admit_agent_execution(
             agent.agent_id,
             owner_token: command.owner_token
           )
           admitted = true
-          Phronomy::Agent::ExecutionRegistry.for(event_loop).bind_agent_execution_admission(
+          environment.registry.bind_agent_execution_admission(
             agent.agent_id,
             owner_token: command.owner_token,
             execution_id: execution.execution_id
@@ -167,11 +167,11 @@ module Phronomy
           if execution.status == :suspended || execution.phase.to_sym == :resuming
             invocation = InvocationRestorer.build_invocation_for_suspended(
               agent, execution, plan.projection, main, agent.send(:_phronomy_event_listener),
-              assistant_message: plan.material.assistant_message
+              assistant_message: plan.material.assistant_message, cancellation_requested: plan.material.cancellation_requested
             )
           end
 
-          Phronomy::Agent::ExecutionRegistry.for(event_loop).install_agent_execution(
+          environment.registry.install_agent_execution(
             execution_id: execution.execution_id,
             agent: agent,
             coordinator: main,
@@ -184,7 +184,7 @@ module Phronomy
           installed = true
 
           if execution.status == :suspended
-            Phronomy::Agent::ExecutionRegistry.for(event_loop).mark_agent_execution_admission(
+            environment.registry.mark_agent_execution_admission(
               agent.agent_id,
               execution_id: execution.execution_id,
               state: :suspended
@@ -209,13 +209,13 @@ module Phronomy
                 }
               )
             end
-            command.completion.complete(agent)
+            agent.send(:_complete_result_task, command.completion, agent)
             return
           end
 
           case plan.classification.disposition
-          when Phronomy::Recovery::RESOLUTION_REQUIRED
-            Phronomy::Agent::ExecutionRegistry.for(event_loop).mark_agent_execution_admission(
+          when Phronomy::Agent::RecoveryRules::RESOLUTION_REQUIRED
+            environment.registry.mark_agent_execution_admission(
               agent.agent_id,
               execution_id: execution.execution_id,
               state: :recovery_required
@@ -246,8 +246,8 @@ module Phronomy
                 result: payload
               )
             end
-            command.completion.complete(agent)
-          when Phronomy::Recovery::RESUMABLE
+            agent.send(:_complete_result_task, command.completion, agent)
+          when Phronomy::Agent::RecoveryRules::RESUMABLE
             continue_resumable_on_event_loop(
               execution,
               completion: command.completion, material: plan.material
@@ -260,7 +260,7 @@ module Phronomy
           # simplecov:disable
           if installed
             begin
-              Phronomy::Agent::ExecutionRegistry.for(event_loop).release_agent_execution(
+              environment.registry.release_agent_execution(
               execution.execution_id
             )
             rescue
@@ -270,7 +270,7 @@ module Phronomy
           if admitted
             if bound
               begin
-                Phronomy::Agent::ExecutionRegistry.for(event_loop).release_agent_execution_admission(
+                environment.registry.release_agent_execution_admission(
                   agent.agent_id,
                   execution_id: execution&.execution_id
                 )
@@ -279,7 +279,7 @@ module Phronomy
               end
             else
               begin
-                Phronomy::Agent::ExecutionRegistry.for(event_loop).release_agent_execution_admission(
+                environment.registry.release_agent_execution_admission(
                   agent.agent_id,
                   owner_token: command.owner_token
                 )
@@ -288,7 +288,7 @@ module Phronomy
               end
             end
           end
-          command.completion.fail(caught)
+          agent.send(:_fail_result_task, command.completion, caught)
           # simplecov:enable
         end
 
@@ -311,13 +311,13 @@ module Phronomy
           completion:, material:
         )
           # simplecov:disable
-          event_loop = @runtime.event_loop
-          main = agent.send(:execution_coordinator_for, agent.__coordination_config)
+          environment = @environment
+          main = agent.send(:execution_coordinator_for, agent.__execution_wiring)
 
           if framework_batch?(execution)
             internal = Phronomy::TaskResult.deferred(name: "framework-tool-recovery:#{execution.execution_id}")
             continue_recovery_on_event_loop(execution, internal, material: material)
-            completion.complete(agent)
+            agent.send(:_complete_result_task, completion, agent)
             return
           end
 
@@ -348,7 +348,7 @@ module Phronomy
               name: "agent-recovery-auto:#{execution.execution_id}"
             )
             observe_recovery_execution(internal_task, execution)
-            state = ExecutionRegistry.for(event_loop).agent_execution_state(execution.execution_id)
+            state = environment.registry.agent_execution_state(execution.execution_id)
             main.deliver_on_event_loop(ExecutionCoordinator::ContinueRecoveredCommand.new(
               coordinator: main,
               execution_id: execution.execution_id,
@@ -359,11 +359,11 @@ module Phronomy
               result_task: internal_task,
               error: nil
             ))
-            completion.complete(agent)
+            agent.send(:_complete_result_task, completion, agent)
           when :recovery_tools_completed, :recovery_provider_completed, :recovery_resolved_failed
             internal_task = Phronomy::TaskResult.deferred(name: "agent-recovery-auto:#{execution.execution_id}")
             continue_recovery_on_event_loop(execution, internal_task, material: material)
-            completion.complete(agent)
+            agent.send(:_complete_result_task, completion, agent)
           else
             raise Phronomy::ExecutionRehydrationRequiredError,
               "no automatic continuation for #{execution.phase.inspect}"

data/lib/phronomy/agent/recovery/recovery_coordinator/resolution.rb

@@ -9,76 +9,71 @@ module Phronomy
         private
 
         def begin_resolve_on_event_loop(request)
-          event_loop = @runtime.event_loop
-          state = Phronomy::Agent::ExecutionRegistry.for(event_loop).agent_execution_state(
+          environment = @environment
+          state = environment.registry.agent_execution_state(
             request.execution_id
           )
           unless state && state.agent.equal?(agent)
-            request.completion.fail(
+            agent.send(:_fail_result_task, request.completion,
               Phronomy::ExecutionRehydrationRequiredError.new(
                 "no live recovered execution #{request.execution_id}"
-              )
-            )
+              ))
             return
           end
 
           current = state.execution
           unless current.execution_revision ==
               request.expected_execution_revision
-            request.completion.fail(
-              Phronomy::Storage::ConflictError.new(
+            agent.send(:_fail_result_task, request.completion,
+              Phronomy::Persistence::StateConflictError.new(
                 "Recovery resolution revision conflict: expected " \
                 "#{request.expected_execution_revision}, actual " \
                 "#{current.execution_revision}"
-              )
-            )
+              ))
             return
           end
 
           descriptor =
             coordination_recovery_descriptor(current)
           unless descriptor &&
-              Phronomy::Recovery.subject_equal?(
+              Phronomy::Agent::RecoveryRules.subject_equal?(
                 descriptor.fetch(:subject),
                 request.subject
               )
-            request.completion.fail(
+            agent.send(:_fail_result_task, request.completion,
               ArgumentError.new(
                 "Recovery subject is not current for execution #{request.execution_id}"
-              )
-            )
+              ))
             return
           end
 
           unless Array(
             descriptor.fetch(:allowed_outcomes)
           ).map(&:to_sym).include?(request.outcome)
-            request.completion.fail(
+            agent.send(:_fail_result_task, request.completion,
               ArgumentError.new(
                 "Recovery outcome #{request.outcome.inspect} is not allowed for the current subject"
-              )
-            )
+              ))
             return
           end
 
           operation = ResolutionOperation.new(
             execution: current,
-            root: agent.agent_root,
+            root: agent.send(:__root_for_operation),
             subject: request.subject,
             outcome: request.outcome,
             result: request.result,
             failure: request.failure
           )
-          Phronomy::Agent::ExecutionRegistry.for(event_loop).mark_agent_execution_admission(
+          environment.registry.mark_agent_execution_admission(
             agent.agent_id,
             execution_id: current.execution_id,
             state: :recovery_required
           )
-          task = @runtime.offload.submit(
-            on_full: :raise
-          ) do
+          task = @environment.submit(on_full: :raise) do
             prepare_resolution(operation)
           end
+          request.completion.track(task) if request.completion.respond_to?(:track)
           task.on_complete do |result, error|
             ready = ResolveReady.new(
               coordinator: self,
@@ -88,15 +83,14 @@ module Phronomy
               error: error
             )
             unless post_control(ready)
-              request.completion.fail(
+              agent.send(:_fail_result_task, request.completion,
                 Phronomy::RuntimeShutdownError.new(
                   "EventLoop rejected Recovery resolution apply"
-                )
-              )
+                ))
             end
           end
         rescue => caught
-          request.completion.fail(caught)
+          agent.send(:_fail_result_task, request.completion, caught)
         end
 
         def perform_resolution(operation)
@@ -118,7 +112,7 @@ module Phronomy
           unless current.metadata[
             ExecutionMetadata::PENDING_LLM_ID_KEY
           ].to_s == llm_call_id
-            raise Phronomy::Storage::ConflictError,
+            raise Phronomy::Persistence::StateConflictError,
               "LLM Recovery subject is no longer pending"
           end
 
@@ -165,7 +159,7 @@ module Phronomy
           when :succeeded
             # simplecov:disable
             outcome =
-              Phronomy::Agent::ProviderCallOutcome.from_h(
+              Phronomy::LLMAdapter::Response.from_h(
                 operation.result
               )
             updated = nil
@@ -267,7 +261,7 @@ module Phronomy
             recovery = RecoverySupport.build_recovery_hash(subjects)
           end
           unless recovery
-            raise Phronomy::Storage::ConflictError,
+            raise Phronomy::Persistence::StateConflictError,
               "Tool Recovery state is missing"
           end
 
@@ -280,7 +274,7 @@ module Phronomy
               hash.fetch("state", "unresolved") == "unresolved"
           end
           unless subject_entry
-            raise Phronomy::Storage::ConflictError,
+            raise Phronomy::Persistence::StateConflictError,
               "Tool Recovery subject is no longer unresolved"
           end
           subject_entry =
@@ -415,10 +409,10 @@ module Phronomy
         # simplecov:enable
 
         def known_non_f1_error?(error)
-          error.is_a?(Phronomy::Storage::ConflictError) ||
-            error.is_a?(Phronomy::Storage::NotFoundError) ||
-            error.is_a?(Phronomy::Storage::SerializationError) ||
-            error.is_a?(Phronomy::Storage::UnsupportedBackendError) ||
+          error.is_a?(Phronomy::Persistence::ConflictError) ||
+            error.is_a?(Phronomy::Persistence::NotFoundError) ||
+            error.is_a?(Phronomy::Persistence::SerializationError) ||
+            error.is_a?(Phronomy::Persistence::UnsupportedBackendError) ||
             error.is_a?(ArgumentError) ||
             error.is_a?(Phronomy::ConfigurationError)
         end
@@ -474,33 +468,33 @@ module Phronomy
           if current.to_h == operation.execution.to_h
             raise(error.is_a?(ResolutionOutcomeUnknownError) ? error.original_error : error)
           end
-          raise Phronomy::Storage::ConflictError,
+          raise Phronomy::Persistence::StateConflictError,
             "Recovery resolution durable outcome conflicts with both expected pre-state and intended post-state"
         end
 
         def apply_resolve_on_event_loop(ready)
           request = ready.request
-          event_loop = @runtime.event_loop
-          state = Phronomy::Agent::ExecutionRegistry.for(event_loop).agent_execution_state(request.execution_id)
+          environment = @environment
+          state = environment.registry.agent_execution_state(request.execution_id)
           unless state && state.agent.equal?(agent)
             raise Phronomy::ExecutionRehydrationRequiredError,
               "recovered execution disappeared before resolution apply"
           end
           unless state.execution.equal?(ready.operation.execution) && state.fsm_session_id.nil?
-            raise Phronomy::Storage::ConflictError,
+            raise Phronomy::Persistence::StateConflictError,
               "Recovery execution changed before resolution apply"
           end
           raise ready.error if ready.error
 
           result = ready.result
           if result.execution
-            Phronomy::Agent::ExecutionRegistry.for(event_loop).replace_agent_execution(request.execution_id, execution: result.execution)
+            environment.registry.replace_agent_execution(request.execution_id, execution: result.execution)
           end
           raise result.error if result.error
 
           continue_recovery_on_event_loop(result.execution, request.completion, material: result.material)
         rescue => caught
-          request.completion.fail(caught)
+          agent.send(:_fail_result_task, request.completion, caught)
         end
       end
     end

data/lib/phronomy/agent/recovery/recovery_coordinator.rb

@@ -7,7 +7,7 @@ module Phronomy
     # Durable Agent Recovery owner/resolver.
     #
     # This class owns Agent-specific restart hydration and factual resolution.
-    # Shared Recovery semantics remain in Phronomy::Recovery.
+    # Agent recovery semantics remain in RecoveryRules.
     # @api private
     class RecoveryCoordinator
       class ResolutionOutcomeUnknownError < Phronomy::Error
@@ -39,7 +39,7 @@ module Phronomy
       )
       ResolutionResult = Data.define(:execution)
       ResolutionPreparation = Data.define(:execution, :material, :error)
-      RecoveryMaterial = Data.define(:projection, :messages, :assistant_message, :output, :usage)
+      RecoveryMaterial = Data.define(:projection, :messages, :assistant_message, :output, :usage, :cancellation_requested)
       RecoveryPlan = Data.define(
         :execution, :root, :manifest, :base_manifest,
         :projection, :classification, :material
@@ -49,7 +49,7 @@ module Phronomy
 
       def initialize(agent)
         @agent = agent
-        @runtime = Phronomy::Runtime.instance
+        @environment = agent.__execution_environment
       end
 
       def recover_on_load!
@@ -57,26 +57,33 @@ module Phronomy
           Array(tx.executions.list_active(agent.agent_id))
         end
         if active.length > 1
-          raise Phronomy::Storage::ConflictError,
+          raise Phronomy::Persistence::StateConflictError,
             "multiple active AgentExecutions exist for #{agent.agent_id}"
         end
         return agent if active.empty?
 
         execution = active.first
         unless execution.agent_id.to_s == agent.agent_id.to_s
-          raise Phronomy::Storage::ConflictError,
+          raise Phronomy::Persistence::StateConflictError,
             "active AgentExecution belongs to another Agent: #{execution.agent_id}"
         end
 
-        coordination = execution.metadata["coordination"]
-        if coordination && agent.__coordination_config.empty?
+        coordination = execution.metadata["reservation"] || execution.metadata["execution_extension"]
+        if coordination && agent.__execution_wiring.empty?
           return agent
         end
 
+        if (raw = execution.metadata["execution_extension"])
+          extension = ExecutionExtensionState.from_h(raw)
+          binding = agent.__execution_wiring[:phronomy_execution_participant]&.binding
+          unless binding && binding.binding_key == extension.binding_key && binding.binding_version == extension.binding_version
+            raise Phronomy::ExecutionRehydrationRequiredError, "Execution #{execution.execution_id} needs its current participant binding"
+          end
+        end
         plan = prepare_plan(execution)
         classification = plan.classification
         if classification.disposition ==
-            Phronomy::Recovery::RESOLUTION_REQUIRED &&
+            Phronomy::Agent::RecoveryRules::RESOLUTION_REQUIRED &&
             !agent.send(:_phronomy_event_listener)
           raise Phronomy::ConfigurationError,
             "Agent #{agent.agent_id.inspect} requires Recovery resolution; " \
@@ -114,21 +121,21 @@ module Phronomy
         expected_execution_revision:,
         subject:,
         outcome:,
-        result: Phronomy::Recovery::MISSING,
-        error: Phronomy::Recovery::MISSING
+        result: Phronomy::Agent::RecoveryRules::MISSING,
+        error: Phronomy::Agent::RecoveryRules::MISSING
       )
         agent.send(:__assert_live_agent!)
-        normalized_outcome = Phronomy::Recovery.normalize_outcome(outcome)
-        result_present = !result.equal?(Phronomy::Recovery::MISSING)
-        error_present = !error.equal?(Phronomy::Recovery::MISSING)
-        Phronomy::Recovery.validate_resolution_material!(
+        normalized_outcome = Phronomy::Agent::RecoveryRules.normalize_outcome(outcome)
+        result_present = !result.equal?(Phronomy::Agent::RecoveryRules::MISSING)
+        error_present = !error.equal?(Phronomy::Agent::RecoveryRules::MISSING)
+        Phronomy::Agent::RecoveryRules.validate_resolution_material!(
           outcome: normalized_outcome,
           result_present: result_present,
           error_present: error_present
         )
 
         normalized_subject =
-          Phronomy::Recovery.normalize_subject(subject)
+          Phronomy::Agent::RecoveryRules.normalize_subject(subject)
         canonical_result = if result_present
           if normalized_subject[:type] == :llm_call &&
               normalized_outcome == :succeeded
@@ -140,9 +147,8 @@ module Phronomy
         failure = error_present ?
           RecoverySupport.resolution_failure(error) : nil
 
-        completion = Phronomy::TaskResult.deferred(
-          name: "agent-recovery-resolve:#{execution_id}"
-        )
+        completion = OperationResult.new(agent: agent,
+          name: "agent-recovery-resolve:#{execution_id}")
         command = ResolveCommand.new(
           coordinator: self,
           execution_id: execution_id.to_s.freeze,
@@ -155,18 +161,15 @@ module Phronomy
           completion: completion
         )
         unless post_control(command)
-          completion.fail(
-            Phronomy::RuntimeShutdownError.new(
-              "EventLoop rejected Agent Recovery resolution"
-            )
-          )
+          agent.send(:_fail_result_task, completion,
+            Phronomy::RuntimeShutdownError.new("EventLoop rejected Agent Recovery resolution"))
         end
         completion
       rescue => caught
         completion ||= Phronomy::TaskResult.deferred(
           name: "agent-recovery-resolve:#{execution_id}"
         )
-        completion.fail(caught)
+        agent.send(:_fail_result_task, completion, caught)
         completion
       end
 
@@ -189,7 +192,7 @@ module Phronomy
       def post_control(command)
         admission = command.is_a?(InstallCommand) || command.is_a?(ResolveCommand)
         completion = admission ? command.completion : command.request.completion
-        ExecutionRegistry.for(@runtime.event_loop).post(command,
+        @environment.registry.post(command,
           admission: admission, completion: completion)
       rescue Phronomy::RuntimeShutdownError
         false

data/lib/phronomy/agent/recovery/recovery_rules.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Agent recovery subjects, factual resolutions and resumption classifications.
+    # Persistence evidence comparison belongs to Persistence::SnapshotComparison.
+    # @api private
+    module RecoveryRules
+      RESUMABLE = :resumable
+      RECONCILABLE = :reconcilable
+      RESOLUTION_REQUIRED = :resolution_required
+      DISPOSITIONS = [RESUMABLE, RECONCILABLE, RESOLUTION_REQUIRED].freeze
+
+      ALLOWED_OUTCOMES = %i[succeeded failed not_performed].freeze
+      # Internal shorthand used by the Agent Recovery implementation. This is not
+      # a public API constant; both names refer to the same frozen value.
+      OUTCOMES = ALLOWED_OUTCOMES
+
+      MISSING = Object.new.freeze
+
+      Classification = Data.define(
+        :disposition, :reason, :subject, :allowed_outcomes, :facts
+      ) do
+        def initialize(
+          disposition:,
+          reason:,
+          subject: nil,
+          allowed_outcomes: [],
+          facts: {}
+        )
+          normalized = disposition.to_sym
+          unless Phronomy::Agent::RecoveryRules::DISPOSITIONS.include?(normalized)
+            raise ArgumentError, "unknown Recovery disposition: #{disposition.inspect}"
+          end
+          super(
+            disposition: normalized,
+            reason: reason.to_sym,
+            subject: subject && Phronomy::Agent::RecoveryRules.normalize_subject(subject),
+            allowed_outcomes: Array(allowed_outcomes).map(&:to_sym).freeze,
+            facts: Phronomy::Values::Immutable.copy(facts || {})
+          )
+        end
+      end
+
+      module_function
+
+      def normalize_outcome(outcome)
+        normalized = outcome.to_sym
+        unless OUTCOMES.include?(normalized)
+          raise ArgumentError, "unsupported Recovery outcome: #{outcome.inspect}"
+        end
+        normalized
+      end
+
+      def validate_resolution_material!(outcome:, result_present:, error_present:)
+        normalized = normalize_outcome(outcome)
+        case normalized
+        when :succeeded
+          raise ArgumentError, "Recovery :succeeded requires result:" unless result_present
+          raise ArgumentError, "Recovery :succeeded forbids error:" if error_present
+        when :failed
+          raise ArgumentError, "Recovery :failed requires error:" unless error_present
+          raise ArgumentError, "Recovery :failed forbids result:" if result_present
+        when :not_performed
+          if result_present || error_present
+            raise ArgumentError, "Recovery :not_performed accepts neither result: nor error:"
+          end
+        end
+        true
+      end
+
+      def normalize_subject(subject)
+        hash = subject.to_h.transform_keys(&:to_sym)
+        type = hash.fetch(:type).to_sym
+        normalized = {type: type}
+        case type
+        when :llm_call
+          normalized[:llm_call_id] = required_id(hash, :llm_call_id)
+        when :tool_invocation
+          normalized[:tool_invocation_id] = required_id(hash, :tool_invocation_id)
+        when :persistence_operation
+          # Persistence operation references are structural only. Do not introduce
+          # a generic durable operation/recovery identity here.
+          normalized[:entity] = hash.fetch(:entity).to_sym
+        else
+          raise ArgumentError, "unsupported Recovery subject type: #{type.inspect}"
+        end
+        normalized.freeze
+      end
+
+      def subject_key(subject)
+        normalized = normalize_subject(subject)
+        case normalized.fetch(:type)
+        when :llm_call
+          "llm_call:#{normalized.fetch(:llm_call_id)}"
+        when :tool_invocation
+          "tool_invocation:#{normalized.fetch(:tool_invocation_id)}"
+        when :persistence_operation
+          "persistence_operation:#{normalized.fetch(:entity)}"
+        end
+      end
+
+      def subject_equal?(left, right)
+        normalize_subject(left) == normalize_subject(right)
+      rescue ArgumentError, KeyError
+        false
+      end
+
+      def required_id(hash, key)
+        value = hash.fetch(key)
+        text = value.to_s
+        raise ArgumentError, "#{key} must not be empty" if text.empty?
+
+        text.freeze
+      end
+      private_class_method :required_id
+    end
+  end
+end