phronomy 0.27.0 → 0.29.0

data/lib/phronomy/agent/execution/dispatch_preparation.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../engine/concurrency/worker_input_restricted"
+require_relative "../../execution/concurrency/worker_input_restricted"
 
 module Phronomy
   module Agent
@@ -20,35 +20,10 @@ module Phronomy
       )
       ToolCommand = Data.define(
         :execution_id, :fsm_session_id, :expected_execution_revision,
-        :root, :execution, :runtime_snapshot, :tool_batch_snapshot
-      )
-      ProviderReconciliationCommand = Data.define(
-        :operation, :intended_result, :original_error
-      )
-      ToolReconciliationCommand = Data.define(
-        :operation, :intended_result, :original_error
+        :root, :execution, :runtime_snapshot, :tool_batch_snapshot, :invocation_config
       )
       ProviderResult = Data.define(:execution, :runtime_projection, :error)
       ToolResult = Data.define(:execution)
-      ProviderReconciliationResult = Data.define(:disposition, :preparation_result)
-      ToolReconciliationResult = Data.define(:disposition, :preparation_result)
-
-      # A failed response does not prove that the execution save rolled back.
-      # @api private
-      class OutcomeUnknownError < Phronomy::Error
-        attr_reader :original_error, :intended_result
-
-        def initialize(original_error, intended_result)
-          @original_error = original_error
-          @intended_result = intended_result
-          super(
-            "durable dispatch preparation outcome is uncertain: " \
-              "#{original_error.class}: #{original_error.message}"
-          )
-          set_backtrace(original_error.backtrace)
-        end
-      end
-
       # @api private
       def initialize(agent:, persistence:)
         @agent = agent
@@ -68,47 +43,13 @@ module Phronomy
 
       # @api private
       def prepare_tools(operation)
-        intended = nil
-        begin
-          @persistence.transaction do |tx|
-            assert_local_durable_base!(tx, operation.root)
-            updated = build_tool_dispatch_execution(operation, tx)
-            updated = @agent.__prepare_coordination_record(updated, tx: tx)
-            tx.executions.save(
-              operation.execution.execution_id,
-              expected_revision: operation.execution.execution_revision,
-              execution: updated
-            )
-            intended = ToolResult.new(execution: updated)
-          end
-        rescue => caught
-          raise if known_durable_failure?(caught) || intended.nil?
-
-          raise OutcomeUnknownError.new(caught, intended)
+        updated = @persistence.transaction do |tx|
+          assert_local_durable_base!(tx, operation.root)
+          build_tool_dispatch_execution(operation, tx)
         end
-        intended
-      end
-
-      # @api private
-      def reconcile_provider(command)
-        disposition, current = reconcile_preparation(
-          command.operation, command.intended_result.execution
-        )
-        result = restore_provider_result(current) if disposition == :committed
-        ProviderReconciliationResult.new(
-          disposition: disposition, preparation_result: result
-        )
-      end
-
-      # @api private
-      def reconcile_tools(command)
-        disposition, current = reconcile_preparation(
-          command.operation, command.intended_result.execution
-        )
-        result = ToolResult.new(execution: current) if disposition == :committed
-        ToolReconciliationResult.new(
-          disposition: disposition, preparation_result: result
-        )
+        change = ExecutionChange.new(agent: @agent, current: operation.execution,
+          root: operation.root, kind: :dispatch, updated: updated, config: operation.invocation_config)
+        ToolResult.new(execution: change.perform)
       end
 
       private
@@ -154,7 +95,7 @@ module Phronomy
           call_sequence: recorded.llm_calls.length + 1,
           config: operation.invocation_config
         )
-        assembler = ContextAssembler.new(
+        assembler = ContextPreparation.new(
           agent: @agent,
           persistence: @persistence,
           journal_records: operation.journal_records
@@ -175,27 +116,14 @@ module Phronomy
       end
 
       def commit_provider_preparation(operation, recorded, assembler, prepared)
-        manifest = manifest_ref = intended = nil
-        begin
-          @persistence.transaction do |tx|
-            assert_local_durable_base!(tx, operation.root)
-            manifest, manifest_ref = assembler.finalize(prepared, persistence: tx)
-            updated = execution_with_provider_manifest(recorded, manifest_ref)
-            updated = @agent.__prepare_coordination_record(updated, tx: tx)
-            tx.executions.save(
-              operation.execution.execution_id,
-              expected_revision: operation.execution.execution_revision,
-              execution: updated
-            )
-            intended = ProviderResult.new(
-              execution: updated, runtime_projection: nil, error: nil
-            )
-          end
-        rescue => caught
-          raise if known_durable_failure?(caught) || intended.nil?
-
-          raise OutcomeUnknownError.new(caught, intended)
+        manifest, manifest_ref = @persistence.transaction do |tx|
+          assert_local_durable_base!(tx, operation.root)
+          Phronomy::Context::Assembly.new.store(prepared, contents: tx.contents)
         end
+        updated = execution_with_provider_manifest(recorded, manifest_ref)
+        change = ExecutionChange.new(agent: @agent, current: operation.execution,
+          root: operation.root, kind: :dispatch, updated: updated, config: operation.invocation_config)
+        intended = ProviderResult.new(execution: change.perform, runtime_projection: nil, error: nil)
         [intended, manifest, manifest_ref]
       end
 
@@ -213,7 +141,7 @@ module Phronomy
       def materialize_provider_result(execution, manifest, manifest_ref)
         projection = materialization_error = nil
         begin
-          projection = RubyLLMMaterializer.new(
+          projection = RuntimeInput.new(
             agent: @agent, persistence: @persistence
           ).materialize(manifest: manifest, manifest_ref: manifest_ref)
         rescue => error
@@ -225,21 +153,6 @@ module Phronomy
         )
       end
 
-      def restore_provider_result(execution)
-        projection = materialization_error = nil
-        begin
-          _manifest, projection = SavedContextReader.materialize_projection(
-            @agent, execution.metadata.fetch("manifest_ref")
-          )
-        rescue => error
-          materialization_error = error
-        end
-        ProviderResult.new(
-          execution: execution, runtime_projection: projection,
-          error: materialization_error
-        )
-      end
-
       def build_tool_dispatch_execution(operation, tx)
         encoded_records, call_records = RuntimeRecordEncoder.encode(
           operation.execution,
@@ -270,29 +183,6 @@ module Phronomy
         metadata
       end
 
-      def reconcile_preparation(operation, intended_execution)
-        current = @persistence.executions.load(operation.execution_id)
-        if current.execution_revision == intended_execution.execution_revision &&
-            current.to_h == intended_execution.to_h
-          return [:committed, current]
-        end
-        if current.execution_revision == operation.execution.execution_revision &&
-            current.to_h == operation.execution.to_h
-          return [:not_committed, current]
-        end
-
-        [:conflict, current]
-      end
-
-      def known_durable_failure?(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?(ArgumentError) ||
-          error.is_a?(Phronomy::ConfigurationError)
-      end
-
       def assert_local_durable_base!(tx, root)
         tx.assert_agent_watermark!(
           agent_id: root.agent_id,

data/lib/phronomy/agent/execution/exact_execution.rb

@@ -10,24 +10,25 @@ module Phronomy
       Wait = Data.define(:coordinator, :agent, :execution_id)
       private_constant :Wait
 
-      def self.start(agent:, execution_id:, input:, config: {})
-        new(agent, execution_id, input, config).start
+      def self.start(agent:, execution_id:, input:, config: {}, resume_only: false)
+        new(agent, execution_id, input, config, resume_only).start
       end
 
-      def initialize(agent, execution_id, input, config)
+      def initialize(agent, execution_id, input, config, resume_only)
         @agent, @id, @input, @config = agent, execution_id.to_s.freeze, input, config.freeze
-        @runtime = Phronomy::Runtime.instance
-        @completion = Phronomy::TaskResult.deferred(name: "exact-execution:#{@id}")
+        @resume_only = resume_only
+        @environment = @agent.__execution_environment
+        @completion = OperationResult.new(agent: @agent, name: "exact-execution:#{@id}")
       end
 
       def start
-        preparation = @runtime.offload.submit(on_full: :raise) do
+        preparation = @environment.submit(on_full: :raise) do
           execution = read_execution
           if execution&.terminal?
             [:terminal, materialize(execution)]
           elsif execution
-            unless Phronomy::Agent::ExecutionRegistry.existing_for(@runtime)&.agent_execution_owner(@id)
-              @agent.instance_variable_set(:@_phronomy_coordination_config, @config)
+            unless @environment.existing_registry&.agent_execution_owner(@id)
+              @agent.instance_variable_set(:@_phronomy_execution_wiring, @config)
               begin
                 RecoveryCoordinator.new(@agent).recover_on_load!
               rescue Phronomy::ConfigurationError => error
@@ -37,17 +38,19 @@ module Phronomy
             end
             [:active, nil]
           else
+            raise Phronomy::Persistence::NotFoundError, "Execution #{@id} is absent" if @resume_only
             @config[:cancellation_token]&.raise_if_cancelled!
             [:absent, nil]
           end
         end
+        @completion.track(preparation)
         preparation.on_complete do |prepared, error|
           if error
-            @completion.fail(error)
+            @completion.settle(error: error)
           else
             disposition, result = prepared
             case disposition
-            when :terminal then @completion.complete(result)
+            when :terminal then @completion.settle(result)
             when :absent
               source = @agent.send(:_start_agent_operation, @input,
                 config: @config.merge(phronomy_reserved_execution_id: @id, phronomy_exact_observers: [@completion].freeze),
@@ -55,21 +58,21 @@ module Phronomy
               source.on_complete { |_value, failure| reconcile(failure) }
             when :active
               command = Wait.new(coordinator: self, agent: @agent, execution_id: @id)
-              posted = ExecutionRegistry.for(@runtime.event_loop).post(command, completion: @completion)
-              @completion.fail(Phronomy::RuntimeShutdownError.new("Exact execution observer rejected")) unless posted
+              posted = @environment.registry.post(command, completion: @completion)
+              @completion.settle(error: Phronomy::RuntimeShutdownError.new("Exact execution observer rejected")) unless posted
             end
           end
         rescue => failure
-          @completion.fail(failure)
+          @completion.settle(error: failure)
         end
         @completion
       rescue => failure
-        @completion.fail(failure)
+        @completion.settle(error: failure)
         @completion
       end
 
       def deliver_on_event_loop(command)
-        state = Phronomy::Agent::ExecutionRegistry.for(@runtime.event_loop).agent_execution_state(command.execution_id)
+        state = @environment.registry.agent_execution_state(command.execution_id)
         unless state
           # Ownership can be released between the durable read and this command.
           # Reinstall once with the caller's current wiring/cancellation request.
@@ -80,9 +83,13 @@ module Phronomy
           return reconcile(nil)
         end
         unless state.agent.equal?(command.agent)
-          raise Phronomy::Storage::ConflictError, "Exact execution #{@id} owner mismatch"
+          raise Phronomy::Persistence::StateConflictError, "Exact execution #{@id} owner mismatch"
         end
         if @config[:cancellation_token]&.cancelled?
+          # One observation governs both recording and notification. A newly
+          # observed request must be persisted off EventLoop before signaling.
+          return start unless @cancellation_recorded
+
           state.invocation&.config&.fetch(:cancellation_token, nil)&.cancel!
         end
         if state.execution.status == :suspended || state.fsm_session_id.nil?
@@ -93,9 +100,9 @@ module Phronomy
         state.invocation.merge_config!(phronomy_exact_observers: (observers + [@completion]).uniq.freeze)
         waiter = Phronomy::TaskResult.deferred(name: "exact-wait:#{@id}")
         waiter.on_complete { |_result, failure| reconcile(failure) }
-        Phronomy::Agent::ExecutionRegistry.for(@runtime.event_loop).register_agent_completion_waiter(@id, waiter)
+        @environment.registry.register_agent_completion_waiter(@id, waiter)
       rescue => failure
-        @completion.fail(failure)
+        @completion.settle(error: failure)
       end
 
       private
@@ -103,30 +110,45 @@ module Phronomy
       def read_execution
         begin
           execution = @agent.persistence.executions.load(@id)
-        rescue Phronomy::Storage::NotFoundError
+        rescue Phronomy::Persistence::NotFoundError
           return nil
         end
         unless execution.agent_id == @agent.agent_id
-          raise Phronomy::Storage::ConflictError, "Reserved execution #{@id} belongs to another Agent"
+          raise Phronomy::Persistence::StateConflictError, "Reserved execution #{@id} belongs to another Agent"
         end
-        expected = @config[:phronomy_coordination]
-        stored = execution.metadata["coordination"]
+        expected = @config[:phronomy_reservation]
+        stored = execution.metadata["reservation"]
         if expected && stored != expected
-          actual_identity = stored&.except("handoff_revision")
-          expected_identity = expected.except("handoff_revision")
-          unless actual_identity == expected_identity
-            raise Phronomy::Storage::ConflictError, "Reserved execution #{@id} coordination mismatch"
-          end
+          raise Phronomy::Persistence::StateConflictError, "Reserved execution #{@id} correlation mismatch"
         end
         ref = execution.metadata["current_input_ref"]
+        @input = @agent.persistence.contents.fetch_text(ref) if @resume_only && ref
         if ref && @agent.persistence.contents.fetch_text(ref) != @input
-          raise Phronomy::Storage::ConflictError, "Reserved execution #{@id} input mismatch"
+          raise Phronomy::Persistence::StateConflictError, "Reserved execution #{@id} input mismatch"
+        end
+        unless execution.terminal?
+          extension = execution.metadata["execution_extension"]
+          participant = @config[:phronomy_execution_participant]
+          if extension && (!participant || participant.binding.to_h.except("state_ref") != extension.except("state_ref"))
+            raise Phronomy::ExecutionRehydrationRequiredError, "Execution #{@id} needs its current participant binding"
+          end
+          # The ledger is independent of execution revision, so recording intent
+          # does not invalidate an already captured outcome command.
+          if @config[:cancellation_token]&.cancelled?
+            @cancellation_recorded = @agent.persistence.request_cancellation(agent_id: @agent.agent_id, execution_id: @id)
+          end
+          if @agent.persistence.cancellation_requested?(agent_id: @agent.agent_id, execution_id: @id)
+            @cancellation_recorded = true
+            token = @config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new
+            token.cancel!
+            @config = @config.merge(cancellation_token: token).freeze
+          end
         end
         execution
       end
 
       def reconcile(failure)
-        task = @runtime.offload.submit(on_full: :raise) do
+        task = @environment.submit(on_full: :raise) do
           execution = read_execution
           if execution&.terminal?
             materialize(execution)
@@ -136,15 +158,16 @@ module Phronomy
             ))
           end
         end
+        @completion.track(task)
         task.on_complete do |result, error|
-          error ? @completion.fail(error) : @completion.complete(result)
+          error ? @completion.settle(error: error) : @completion.settle(result)
         end
       rescue => error
-        @completion.fail(error)
+        @completion.settle(error: error)
       end
 
       def materialize(execution)
-        result = @agent.persistence.execution_result(execution.execution_id)
+        result = @agent.persistence.result(execution.execution_id)
         result.merge(output: result[:result]).freeze
       end
     end

data/lib/phronomy/agent/execution/execution_cancellation.rb

@@ -9,13 +9,17 @@ module Phronomy
       Command = Data.define(:coordinator, :execution_id, :agent_id)
       private_constant :Command
 
-      def self.signal(execution_id, agent_id)
-        command = Command.new(coordinator: new, execution_id: execution_id, agent_id: agent_id)
-        ExecutionRegistry.for(Phronomy::Runtime.instance.event_loop).post(command)
+      def self.signal(execution_id, agent_id, environment:)
+        command = Command.new(coordinator: new(environment), execution_id: execution_id, agent_id: agent_id)
+        environment.registry.post(command)
+      end
+
+      def initialize(environment)
+        @environment = environment
       end
 
       def deliver_on_event_loop(command)
-        state = Phronomy::Agent::ExecutionRegistry.for(Phronomy::Runtime.instance.event_loop).agent_execution_state(command.execution_id)
+        state = @environment.registry.agent_execution_state(command.execution_id)
         return unless state && state.agent.agent_id == command.agent_id
         state.invocation&.config&.fetch(:cancellation_token, nil)&.cancel!
       end