phronomy 0.26.0 → 0.28.0

data/lib/phronomy/agent/{recovery_coordinator → 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 = 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::Persistence::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
           )
-          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|
@@ -116,9 +114,9 @@ module Phronomy
           llm_call_id =
             operation.subject.fetch(:llm_call_id).to_s
           unless current.metadata[
-            RecoverySupport::PENDING_LLM_ID_KEY
+            ExecutionMetadata::PENDING_LLM_ID_KEY
           ].to_s == llm_call_id
-            raise Phronomy::Persistence::ConflictError,
+            raise Phronomy::Persistence::StateConflictError,
               "LLM Recovery subject is no longer pending"
           end
 
@@ -136,27 +134,27 @@ module Phronomy
                 "automatic semantic redispatch is unavailable without a replay contract"
             }.freeze
             recovery = {
-              "version" => RecoverySupport::CONTRACT_VERSION,
+              "version" => ExecutionMetadata::CONTRACT_VERSION,
               "resolution_outcome" => "not_performed",
               "failure" => failure
             }.freeze
             updated = current.with(
               phase: :recovery_resolved_failed,
               metadata: current.metadata.merge(
-                RecoverySupport::RECOVERY_METADATA_KEY => recovery
+                ExecutionMetadata::RECOVERY_METADATA_KEY => recovery
               )
             )
             intended = ResolutionResult.new(execution: updated)
             save_resolution_result(current, intended)
           when :failed
             recovery = {
-              "version" => RecoverySupport::CONTRACT_VERSION,
+              "version" => ExecutionMetadata::CONTRACT_VERSION,
               "failure" => operation.failure
             }
             updated = current.with(
               phase: :recovery_resolved_failed,
               metadata: current.metadata.merge(
-                RecoverySupport::RECOVERY_METADATA_KEY =>
+                ExecutionMetadata::RECOVERY_METADATA_KEY =>
                   recovery
               )
             )
@@ -165,12 +163,11 @@ module Phronomy
           when :succeeded
             # simplecov:disable
             outcome =
-              Phronomy::Agent::ProviderCallOutcome.from_h(
+              Phronomy::LLMAdapter::Response.from_h(
                 operation.result
               )
             updated = nil
             with_resolution_f1_capture do |tx|
-              main = agent.send(:execution_coordinator_for, agent.__coordination_config)
               snapshot = {
                 llm_results: [{
                   llm_call_id: llm_call_id,
@@ -178,22 +175,22 @@ module Phronomy
                   error: nil,
                   streaming: (
                     current.metadata[
-                      RecoverySupport::INVOCATION_MODE_KEY
+                      ExecutionMetadata::INVOCATION_MODE_KEY
                     ].to_s == "stream"
                   ),
                   manifest_ref: current.metadata.fetch(
                     "manifest_ref"
                   ),
                   started_at: current.metadata[
-                    RecoverySupport::PENDING_LLM_STARTED_AT_KEY
+                    ExecutionMetadata::PENDING_LLM_STARTED_AT_KEY
                   ] || current.updated_at
                 }.freeze].freeze,
                 runtime_events: [].freeze,
                 active_call: nil
               }.freeze
-              records, calls = main.send(
-                :encode_runtime_records,
+              records, calls = RuntimeRecordEncoder.encode(
                 current,
+                agent_id: agent.agent_id,
                 tx: tx,
                 snapshot: snapshot,
                 context_candidate: true,
@@ -210,15 +207,15 @@ module Phronomy
                 :recovery_provider_completed : :recovery_tools
               metadata = current.metadata.dup
               metadata.delete(
-                RecoverySupport::PENDING_LLM_ID_KEY
+                ExecutionMetadata::PENDING_LLM_ID_KEY
               )
               metadata.delete(
-                RecoverySupport::PENDING_LLM_STARTED_AT_KEY
+                ExecutionMetadata::PENDING_LLM_STARTED_AT_KEY
               )
               metadata.delete("framework_calls_pending")
               metadata["framework_calls_pending"] = true unless framework_subjects.empty?
-              if subjects.any? && Array(metadata[RecoverySupport::TOOL_BATCH_METADATA_KEY]).empty?
-                metadata[RecoverySupport::TOOL_BATCH_METADATA_KEY] = subjects.map do |entry|
+              if subjects.any? && Array(metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY]).empty?
+                metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY] = subjects.map do |entry|
                   {
                     "tool_invocation_id" => entry.fetch("tool_invocation_id"),
                     "llm_call_id" => entry.fetch("llm_call_id"),
@@ -231,11 +228,11 @@ module Phronomy
               end
               if external_subjects.empty?
                 metadata.delete(
-                  RecoverySupport::RECOVERY_METADATA_KEY
+                  ExecutionMetadata::RECOVERY_METADATA_KEY
                 )
               else
                 metadata[
-                  RecoverySupport::RECOVERY_METADATA_KEY
+                  ExecutionMetadata::RECOVERY_METADATA_KEY
                 ] = RecoverySupport.build_recovery_hash(
                   external_subjects
                 )
@@ -268,7 +265,7 @@ module Phronomy
             recovery = RecoverySupport.build_recovery_hash(subjects)
           end
           unless recovery
-            raise Phronomy::Persistence::ConflictError,
+            raise Phronomy::Persistence::StateConflictError,
               "Tool Recovery state is missing"
           end
 
@@ -281,7 +278,7 @@ module Phronomy
               hash.fetch("state", "unresolved") == "unresolved"
           end
           unless subject_entry
-            raise Phronomy::Persistence::ConflictError,
+            raise Phronomy::Persistence::StateConflictError,
               "Tool Recovery subject is no longer unresolved"
           end
           subject_entry =
@@ -309,7 +306,7 @@ module Phronomy
             updated = current.with(
               phase: :recovery_resolved_failed,
               metadata: current.metadata.merge(
-                RecoverySupport::RECOVERY_METADATA_KEY =>
+                ExecutionMetadata::RECOVERY_METADATA_KEY =>
                   resolved_recovery
               )
             )
@@ -329,7 +326,7 @@ module Phronomy
             updated = current.with(
               phase: :recovery_resolved_failed,
               metadata: current.metadata.merge(
-                RecoverySupport::RECOVERY_METADATA_KEY =>
+                ExecutionMetadata::RECOVERY_METADATA_KEY =>
                   recovery_with_failure
               )
             )
@@ -338,9 +335,7 @@ module Phronomy
           when :succeeded
             updated = nil
             with_resolution_f1_capture do |tx|
-              main = agent.send(:execution_coordinator_for, agent.__coordination_config)
-              result_ref = main.send(
-                :put_runtime_content,
+              result_ref = RuntimeRecordEncoder.put_runtime_content(
                 tx,
                 operation.result
               )
@@ -363,9 +358,9 @@ module Phronomy
                     subject_entry.fetch("llm_call_id").to_s
                 }.freeze
               )
-              records, _calls = main.send(
-                :encode_runtime_records,
+              records, _calls = RuntimeRecordEncoder.encode(
                 current,
+                agent_id: agent.agent_id,
                 tx: tx,
                 snapshot: {
                   llm_results: [].freeze,
@@ -388,7 +383,7 @@ module Phronomy
                 RecoverySupport.unresolved_subjects(
                   next_recovery
                 )
-              tool_batch = Array(current.metadata[RecoverySupport::TOOL_BATCH_METADATA_KEY]).map do |entry|
+              tool_batch = Array(current.metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY]).map do |entry|
                 if entry.fetch("tool_invocation_id") == subject_entry.fetch("tool_invocation_id")
                   entry.merge("status" => "completed", "result" => operation.result)
                 else
@@ -402,8 +397,8 @@ module Phronomy
                 working_records:
                   current.working_records + records,
                 metadata: current.metadata.merge(
-                  RecoverySupport::RECOVERY_METADATA_KEY => next_recovery,
-                  RecoverySupport::TOOL_BATCH_METADATA_KEY => tool_batch
+                  ExecutionMetadata::RECOVERY_METADATA_KEY => next_recovery,
+                  ExecutionMetadata::TOOL_BATCH_METADATA_KEY => tool_batch
                 )
               )
               tx.executions.save(
@@ -477,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::Persistence::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 = 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::Persistence::ConflictError,
+            raise Phronomy::Persistence::StateConflictError,
               "Recovery execution changed before resolution apply"
           end
           raise ready.error if ready.error
 
           result = ready.result
           if result.execution
-            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_coordinator.rb → 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::Persistence::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::Persistence::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
@@ -187,14 +194,10 @@ module Phronomy
       private
 
       def post_control(command)
-        @runtime.event_loop.post(
-          Phronomy::Event.new(
-            type: :agent_control,
-            target_id:
-              Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
-            payload: {command: command}.freeze
-          )
-        )
+        admission = command.is_a?(InstallCommand) || command.is_a?(ResolveCommand)
+        completion = admission ? command.completion : command.request.completion
+        @environment.registry.post(command,
+          admission: admission, completion: completion)
       rescue Phronomy::RuntimeShutdownError
         false
       end

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