phronomy 0.27.0 → 0.28.0

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

@@ -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
@@ -214,8 +214,8 @@ module Phronomy
           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
@@ -247,7 +247,7 @@ module Phronomy
               )
             end
             command.completion.complete(agent)
-          when Phronomy::Recovery::RESUMABLE
+          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
                 )
@@ -311,8 +311,8 @@ 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}")
@@ -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,

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

@@ -9,8 +9,8 @@ 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)
@@ -26,7 +26,7 @@ module Phronomy
           unless current.execution_revision ==
               request.expected_execution_revision
             request.completion.fail(
-              Phronomy::Storage::ConflictError.new(
+              Phronomy::Persistence::StateConflictError.new(
                 "Recovery resolution revision conflict: expected " \
                 "#{request.expected_execution_revision}, actual " \
                 "#{current.execution_revision}"
@@ -38,7 +38,7 @@ module Phronomy
           descriptor =
             coordination_recovery_descriptor(current)
           unless descriptor &&
-              Phronomy::Recovery.subject_equal?(
+              Phronomy::Agent::RecoveryRules.subject_equal?(
                 descriptor.fetch(:subject),
                 request.subject
               )
@@ -69,14 +69,12 @@ module Phronomy
             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
           task.on_complete do |result, error|
@@ -118,7 +116,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 +163,7 @@ module Phronomy
           when :succeeded
             # simplecov:disable
             outcome =
-              Phronomy::Agent::ProviderCallOutcome.from_h(
+              Phronomy::LLMAdapter::Response.from_h(
                 operation.result
               )
             updated = nil
@@ -267,7 +265,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 +278,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 +413,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,27 +472,27 @@ 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
 

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
@@ -189,7 +196,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

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

@@ -15,17 +15,14 @@ module Phronomy
       end
 
       def normalize_provider_outcome(value)
-        return value if value.is_a?(Phronomy::Agent::ProviderCallOutcome)
+        return value if value.is_a?(Phronomy::LLMAdapter::Response)
 
         if value.is_a?(Hash)
-          return Phronomy::Agent::ProviderCallOutcome.from_h(value)
+          return Phronomy::LLMAdapter::Response.from_h(value)
         end
 
-        captured = Phronomy::Agent::ProviderCallOutcome.capture(value)
-        return captured if captured
-
         raise ArgumentError,
-          "LLM Recovery :succeeded requires a Provider result or ProviderCallOutcome-compatible Hash"
+          "LLM Recovery :succeeded requires an LLMAdapter::Response or its canonical Hash"
       end
 
       def resolution_failure(error)
@@ -47,7 +44,7 @@ module Phronomy
           execution_id: execution.execution_id,
           execution_revision: execution.execution_revision,
           reason: descriptor.fetch(:reason),
-          subject: Phronomy::Recovery.normalize_subject(
+          subject: Phronomy::Agent::RecoveryRules.normalize_subject(
             descriptor.fetch(:subject)
           ),
           allowed_outcomes: Array(
@@ -69,7 +66,7 @@ module Phronomy
             type: :llm_call,
             llm_call_id: llm_call_id
           },
-          allowed_outcomes: Phronomy::Recovery::OUTCOMES,
+          allowed_outcomes: Phronomy::Agent::RecoveryRules::OUTCOMES,
           facts: {
             manifest_ref: execution.metadata["manifest_ref"],
             call_sequence: execution.llm_calls.length + 1
@@ -103,7 +100,7 @@ module Phronomy
           allowed_outcomes: Array(
             recovery["allowed_outcomes"] ||
               recovery[:allowed_outcomes] ||
-              Phronomy::Recovery::OUTCOMES
+              Phronomy::Agent::RecoveryRules::OUTCOMES
           ).map(&:to_sym),
           facts: {
             tool_call_id: hash["tool_call_id"],
@@ -145,7 +142,7 @@ module Phronomy
             type: :tool_invocation,
             tool_invocation_id: first.fetch("tool_invocation_id")
           },
-          allowed_outcomes: Phronomy::Recovery::OUTCOMES,
+          allowed_outcomes: Phronomy::Agent::RecoveryRules::OUTCOMES,
           facts: {
             tool_call_id: first["tool_call_id"],
             tool_name: first["tool_name"],
@@ -194,7 +191,7 @@ module Phronomy
         end.freeze
       end
 
-      def build_recovery_hash(subjects, reason: :outcome_unknown, allowed_outcomes: Phronomy::Recovery::OUTCOMES)
+      def build_recovery_hash(subjects, reason: :outcome_unknown, allowed_outcomes: Phronomy::Agent::RecoveryRules::OUTCOMES)
         {
           "version" => ExecutionMetadata::CONTRACT_VERSION,
           "reason" => reason.to_s,

data/lib/phronomy/agent/reserved_execution.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Exact identity reserved by a coordinating domain. Correlation is immutable;
+    # mutable routing fences belong to the coordinator, never to this identity.
+    # @api public
+    ReservedExecution = Data.define(:agent_id, :execution_id, :correlation) do
+      def initialize(agent_id:, execution_id:, correlation: nil)
+        raise ArgumentError, "reserved identities must not be empty" if agent_id.to_s.empty? || execution_id.to_s.empty?
+        super(agent_id: agent_id.to_s.freeze, execution_id: execution_id.to_s.freeze,
+              correlation: Phronomy::Values::Immutable.copy(correlation))
+      end
+    end
+  end
+end

data/lib/phronomy/agent/retention.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # A durable reference prevents whole-Agent purge. The referencing domain
+    # decides when its opaque owner key can be released.
+    # @api public
+    Retention = Data.define(:agent_id, :execution_id, :owner_key) do
+      def initialize(agent_id:, owner_key:, execution_id: nil)
+        raise ArgumentError, "retention identities must not be empty" if agent_id.to_s.empty? || owner_key.to_s.empty?
+        super(agent_id: agent_id.to_s.freeze, execution_id: execution_id&.to_s&.freeze, owner_key: owner_key.to_s.freeze)
+      end
+
+      def to_h = {"agent_id" => agent_id, "execution_id" => execution_id, "owner_key" => owner_key}.freeze
+    end
+  end
+end