phronomy 0.27.0 → 0.28.0

data/lib/phronomy/agent/runtime_binding/engine_environment.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Adapts the concrete Engine lifecycle and sessions to Agent's connection.
+    # Construction alone starts no Runtime resources and creates no registry.
+    # @api private
+    class EngineEnvironment < ExecutionEnvironment
+      def initialize(runtime: Phronomy::Runtime.instance)
+        @runtime = runtime
+      end
+
+      def registry = ExecutionRegistry.for(@runtime.event_loop)
+      def existing_registry = ExecutionRegistry.existing_for(@runtime)
+
+      def ownership
+        existing_ownership || @runtime.__register_shutdown_participant(
+          key: OwnershipRegistry, participant: OwnershipRegistry.new(environment: self)
+        )
+      end
+
+      def existing_ownership = @runtime.__shutdown_participant(key: OwnershipRegistry)
+      def executing? = @runtime.event_loop.current?
+      def session_phase(id) = @runtime.event_loop.fsm_session_state(id)
+
+      def submit(**options, &operation)
+        Phronomy::Execution.submit(runtime: @runtime, **options, &operation)
+      end
+
+      # Pool sizing is an execution resource choice, separate from Agent's
+      # authorization decision and timeout selection. Read at submission time.
+      def submit_authorization(timeout:, cancellation_token:, &operation)
+        submit(pool_name: :authorization,
+          size: Phronomy::RuntimeSettings.current.authorization_pool_size,
+          queue_size: Phronomy::RuntimeSettings.current.authorization_queue_size,
+          timeout: timeout, cancellation_token: cancellation_token,
+          on_full: :raise, &operation)
+      end
+
+      def build_llm_client(adapter:)
+        Phronomy::LLMAdapter::AsyncClient.new(adapter: adapter, submitter: self)
+      end
+
+      def build_agent_session(invocation:, resume_event: nil, resume_phase: nil)
+        EngineSessionBuilder.build(invocation: invocation, environment: self,
+          event_loop: @runtime.event_loop, resume_event: resume_event, resume_phase: resume_phase)
+      end
+
+      def build_tool_session(invocation:, parent_sink:, resume_event: nil, resume_phase: nil)
+        ToolSessionBuilder.build(invocation: invocation, environment: self,
+          event_loop: @runtime.event_loop, parent_event_sink: parent_sink,
+          resume_event: resume_event, resume_phase: resume_phase)
+      end
+
+      def register_session(session, completion:)
+        @runtime.event_loop.register(session, completion: completion)
+      end
+    end
+  end
+end

data/lib/phronomy/agent/runtime_binding/engine_session_builder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Engine-only construction. State vocabulary, ordered guards and entry
+    # operations are supplied by the Agent framework, not defined here.
+    # @api private
+    class EngineSessionBuilder
+      def self.build(invocation:, environment:, event_loop:, resume_event: nil, resume_phase: nil)
+        event_sink = Phronomy::FSMSession::EventSink.new(event_loop: event_loop)
+        invocation.bind_event_sink!(event_sink)
+        actions = InvocationActions.build_entry_actions(invocation.agent,
+          environment, mode: invocation.mode, event_sink: event_sink)
+        phase_machine = PhaseMachineBuilder.new(entry_actions: actions).build
+
+        Phronomy::FSMSession.new(
+          context: invocation,
+          event_sink: event_sink,
+          entry_point: InvocationTransitions::ENTRY_POINT,
+          phase_machine_class: phase_machine,
+          entry_actions: {},
+          auto_state_set: InvocationTransitions::AUTO_STATE_SET,
+          declared_states: InvocationTransitions::DECLARED_STATES,
+          wait_state_names: InvocationTransitions::WAIT_STATES,
+          external_events: InvocationTransitions::EXTERNAL_EVENTS,
+          recursion_limit: InvocationTransitions.recursion_limit(invocation.agent.class.max_iterations),
+          event_loop: event_loop,
+          resume_event: resume_event,
+          resume_phase: resume_phase
+        )
+      end
+    end
+  end
+end

data/lib/phronomy/agent/runtime_binding/phase_machine_builder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "state_machines"
+
+module Phronomy
+  module Agent
+    class PhaseMachineBuilder
+      def initialize(entry_actions: {}, transitions: InvocationTransitions, operation_name: "Agent")
+        @entry_actions = entry_actions
+        @transitions = transitions
+        @operation_name = operation_name
+      end
+
+      def build
+        entry_actions = @entry_actions
+        callback_builder = method(:build_entry_callback)
+        transitions = @transitions
+        declared_states = transitions::DECLARED_STATES
+        entry_point = transitions::ENTRY_POINT
+
+        Class.new do
+          attr_accessor :context, :current_event
+
+          state_machine :phase, initial: entry_point do
+            declared_states.each { |state_name| state state_name }
+
+            transitions::EVENTS.each do |event_name, definitions|
+              event event_name do
+                definitions.each do |definition|
+                  transition definition[:from] => definition[:to],
+                    :if => ->(machine) {
+                      transitions.allowed?(definition, machine.context)
+                    }
+                end
+              end
+            end
+
+            entry_actions.each do |state_name, callables|
+              callables.each do |callable|
+                after_transition(
+                  to: state_name,
+                  do: callback_builder.call(callable, state_name)
+                )
+              end
+            end
+          end
+        end
+      end
+
+      private
+
+      def build_entry_callback(callable, state_name)
+        ->(machine) {
+          result = callable.call(machine.context)
+          if result.is_a?(Phronomy::TaskResult)
+            raise Phronomy::InvalidAsyncEntryActionError,
+              "#{@operation_name} entry action for #{state_name.inspect} returned Phronomy::TaskResult"
+          end
+          machine.context = result if result.respond_to?(:set_graph_metadata)
+        }
+      end
+    end
+  end
+end

data/lib/phronomy/agent/runtime_binding/tool_session_builder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Binds Agent Tool child progress to a concrete FSM session. Session routing
+    # is fresh for each incarnation and never replaces a durable Tool identity.
+    # @api private
+    class ToolSessionBuilder
+      def self.build(invocation:, environment:, event_loop:, parent_event_sink:,
+        resume_event: nil, resume_phase: nil)
+        event_sink = Phronomy::FSMSession::EventSink.new(event_loop: event_loop)
+        actions = ToolInvocationActions.build_entry_actions(environment, event_sink, parent_event_sink)
+        phase_machine = PhaseMachineBuilder.new(entry_actions: actions,
+          transitions: ToolInvocationTransitions, operation_name: "Tool").build
+
+        Phronomy::FSMSession.new(
+          context: invocation,
+          event_sink: event_sink,
+          entry_point: ToolInvocationTransitions::ENTRY_POINT,
+          phase_machine_class: phase_machine,
+          entry_actions: {},
+          auto_state_set: ToolInvocationTransitions::AUTO_STATE_SET,
+          declared_states: ToolInvocationTransitions::DECLARED_STATES,
+          wait_state_names: ToolInvocationTransitions::WAIT_STATES,
+          external_events: ToolInvocationTransitions::EXTERNAL_EVENTS,
+          recursion_limit: ToolInvocationTransitions::RECURSION_LIMIT,
+          event_loop: event_loop,
+          resume_event: resume_event,
+          resume_phase: resume_phase
+        )
+      end
+    end
+  end
+end

data/lib/phronomy/agent/{context_assembly/ruby_llm_materializer.rb → runtime_input.rb}

@@ -2,7 +2,7 @@
 
 module Phronomy
   module Agent
-    class RubyLLMMaterializer
+    class RuntimeInput
       RuntimeProjection = Data.define(
         :system, :messages, :tool_classes, :ask_message,
         :model_config, :manifest, :manifest_ref
@@ -63,7 +63,7 @@ module Phronomy
       private
 
       def segment_from_record(record, position: 0)
-        LLMInputManifest::Segment.new(
+        Phronomy::Context::LLMInputManifest::Segment.new(
           position: position,
           category: record.kind,
           role: record.role,
@@ -88,7 +88,7 @@ module Phronomy
       end
 
       def verify_adapter!(manifest)
-        actual = Phronomy.configuration.llm_adapter.class.name
+        actual = Phronomy::Agent::Settings.current.llm_adapter.class.name
         return if manifest.adapter_name.nil? || manifest.adapter_name == actual
 
         raise Phronomy::ConfigurationError,
@@ -97,19 +97,16 @@ module Phronomy
 
       def verify_tool_definitions!(manifest)
         unless manifest.tool_definitions_ref
-          return ToolDefinitionSet.build(
-            @agent,
-            additional_tools: @additional_tools
-          )
+          return @agent.send(:tool_definition_set, additional_tools: @additional_tools)
         end
 
         expected_definitions = fetch_json(manifest.tool_definitions_ref)
         additional = @additional_tools
         if additional.empty?
-          additional = Array(@agent.__coordination_config[:phronomy_handoff_bindings]).map(&:tool_class)
+          additional = Array(@agent.__execution_wiring[:phronomy_control_bindings]).map(&:tool_class)
         end
 
-        ToolDefinitionSet.build(@agent, additional_tools: additional)
+        @agent.send(:tool_definition_set, additional_tools: additional)
           .select_definitions(expected_definitions)
       end
 
@@ -130,7 +127,7 @@ module Phronomy
         when :tool_result
           raise ArgumentError, "raw Tool result is not an LLM message"
         else
-          RubyLLM::Message.new(
+          Phronomy::LLMAdapter::Message.new(
             role: segment.role,
             content: @persistence.contents.fetch_text(segment.content_ref),
             tool_call_id: segment.tool_call_id
@@ -151,39 +148,25 @@ module Phronomy
         end
 
         tool_calls = materialize_tool_calls(payload["tool_calls"])
-        RubyLLM::Message.new(
+        Phronomy::LLMAdapter::Message.new(
           role: role,
-          content: initial_content_for(role, payload.fetch("content", nil), tool_calls),
-          tool_calls: tool_calls.empty? ? nil : tool_calls,
+          content: payload.fetch("content", nil),
+          tool_calls: tool_calls,
           tool_call_id: payload["tool_call_id"],
-          model: payload["model_id"]
+          metadata: {"model_id" => payload["model_id"]}.compact
         )
       end
 
-      def initial_content_for(role, content, tool_calls)
-        return "" if role == :assistant && content.nil? && !tool_calls.empty?
-
-        (content.is_a?(Hash) || content.is_a?(Array)) ? JSON.generate(content) : content
-      end
-
       def materialize_tool_calls(payloads)
-        Array(payloads).each_with_object({}) do |payload, result|
-          tool_call_id = payload.fetch("id").to_s
-          if result.key?(tool_call_id)
-            raise ArgumentError, "duplicate Tool Call in assistant message: #{tool_call_id}"
-          end
-          result[tool_call_id] = materialize_tool_call(payload)
+        Array(payloads).map do |payload|
+          # Read the pre-unit6 durable format explicitly; SDK objects are never
+          # reconstituted during recovery. New records use opaque metadata.
+          metadata = payload.fetch("metadata", {}).dup
+          metadata["thought_signature"] = payload["thought_signature"] if payload["thought_signature"]
+          Phronomy::Tool::CallRequest.new(id: payload.fetch("id"), name: payload.fetch("name"),
+            arguments: payload.fetch("arguments", {}), metadata: metadata)
         end
       end
-
-      def materialize_tool_call(payload)
-        RubyLLM::ToolCall.new(
-          id: payload.fetch("id").to_s,
-          name: payload.fetch("name"),
-          arguments: payload.fetch("arguments", {}),
-          thought_signature: payload["thought_signature"]
-        )
-      end
     end
   end
 end

data/lib/phronomy/agent/{context_assembly/saved_context_reader.rb → saved_context_reader.rb}

@@ -9,13 +9,15 @@ module Phronomy
       module_function
 
       def manifest_from_ref(agent, ref)
-        raw = agent.persistence.contents.fetch_json(ref)
-        Phronomy::Agent::LLMInputManifest.from_h(raw)
+        Phronomy::Persistence::StorageBoundary.call do
+          raw = agent.persistence.contents.fetch_json(ref)
+          Phronomy::Context::LLMInputManifest.from_h(raw)
+        end
       end
 
       def materialize_projection(agent, manifest_ref)
         manifest = manifest_from_ref(agent, manifest_ref)
-        projection = Phronomy::Agent::RubyLLMMaterializer.new(
+        projection = Phronomy::Agent::RuntimeInput.new(
           agent: agent,
           persistence: agent.persistence
         ).materialize(manifest: manifest, manifest_ref: manifest_ref)
@@ -40,7 +42,7 @@ module Phronomy
         else
           {}
         end
-        usage = Phronomy::TokenUsage.new(
+        usage = Phronomy::LLMAdapter::TokenUsage.new(
           input: usage_hash["input"] || usage_hash[:input] || usage_hash["input_tokens"] || usage_hash[:input_tokens],
           output: usage_hash["output"] || usage_hash[:output] || usage_hash["output_tokens"] || usage_hash[:output_tokens],
           cached: usage_hash["cached"] || usage_hash[:cached] || usage_hash["cache_read_tokens"] || usage_hash[:cache_read_tokens] || usage_hash["cached_tokens"] || usage_hash[:cached_tokens],

data/lib/phronomy/agent/settings.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "../common/configuration_error"
+
+module Phronomy
+  module Agent
+    # Agent-owned option values and policy validation. Composition supplies
+    # concrete components and default values; execution reads at existing sites.
+    # @api private
+    class Settings
+      class << self
+        # Bind at boot without reading settings or starting runtime resources.
+        def install_provider(&provider)
+          raise ArgumentError, "settings provider requires a block" unless provider
+          @provider = provider
+          nil
+        end
+
+        # Read only when requested; no cache or change notification is involved.
+        def current
+          @provider.call
+        end
+      end
+
+      STREAM_CALLBACK_ERROR_POLICIES = %i[report fail_task].freeze
+      private_constant :STREAM_CALLBACK_ERROR_POLICIES
+
+      attr_accessor :default_model, :before_llm_input, :agent_store, :llm_adapter, :authorization_timeout
+      attr_reader :stream_callback_error_policy
+
+      def initialize(llm_adapter:, authorization_timeout:, stream_callback_error_policy:)
+        @llm_adapter = llm_adapter
+        @authorization_timeout = authorization_timeout
+        self.stream_callback_error_policy = stream_callback_error_policy
+      end
+
+      def stream_callback_error_policy=(value)
+        unless STREAM_CALLBACK_ERROR_POLICIES.include?(value)
+          allowed = STREAM_CALLBACK_ERROR_POLICIES.map(&:inspect).join(", ")
+          raise Phronomy::ConfigurationError,
+            "stream_callback_error_policy must be one of: #{allowed}"
+        end
+        @stream_callback_error_policy = value
+      end
+    end
+  end
+end

data/lib/phronomy/agent/{context_assembly/state_writer.rb → state_writer.rb}

@@ -14,7 +14,7 @@ module Phronomy
         @agent_id = agent_id
       end
 
-      def create_root(definition:, context:, knowledge:, metadata:)
+      def create_root(definition:, context:, knowledge:, metadata:, retention: nil)
         root = Agent::AgentRoot.create(
           agent_id: agent_id,
           agent_definition_id: definition.fetch(:id),
@@ -23,6 +23,7 @@ module Phronomy
         )
         persistence.transaction do |tx|
           tx.agents.create(root)
+          tx.retentions.retain(retention) if retention
           records = initial_context_records(tx: tx, root: root, context: context)
           records.concat(initial_knowledge_records(tx: tx, root: root, knowledge: knowledge))
           unless records.empty?
@@ -137,8 +138,8 @@ module Phronomy
           build_knowledge_record(
             tx: tx,
             root: root,
-            content: content,
-            metadata: {}
+            content: content.is_a?(KnowledgeItem) ? content.content : content,
+            metadata: content.is_a?(KnowledgeItem) ? content.metadata : {}
           )
         end
       end

data/lib/phronomy/agent/store.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Agent-owned durable operations and observations. An injected record
+    # adapter implements storage; this framework never selects a DB or codec.
+    # @api public
+    class Store
+      # Provider-ordered authorized calls, with no internal execution metadata.
+      AuthorizedOperation = Data.define(:invocation_id, :name, :arguments)
+
+      attr_reader :coordinator
+
+      # Record protocol for Agent-owned framework operations only.
+      # @api private
+      attr_reader :contents, :agents, :journals, :executions, :retentions
+
+      def initialize(coordinator:, records:)
+        @coordinator, @record_adapter = coordinator, records
+        @records = coordinator.bind(records)
+        @contents = @records.contents
+        @agents = @records.agents
+        @journals = @records.journals
+        @executions = @records.executions
+        @retentions = @records.retentions
+      end
+
+      # A domain operation owns this short transaction. A coordinating parent
+      # can instead call participate with its existing shared scope.
+      def transaction
+        coordinator.atomic do |scope|
+          participate(scope) { |records| yield records, scope }
+        end
+      end
+
+      def participate(scope, &operation)
+        scope.participate(persistence: coordinator, adapter: @record_adapter, &operation)
+      end
+
+      # Authoritative presence only. Failed reads propagate, never mean absent.
+      def exist?(agent_id)
+        assert_observation_thread!
+        agents.load(agent_id)
+        true
+      rescue Phronomy::Persistence::NotFoundError
+        false
+      end
+
+      # Validate the exact requested call and project its authorized batch in
+      # Provider order from one execution snapshot in the caller's transaction.
+      # The receiving domain owns application and replay of these operations.
+      def authorized_operations(scope, agent_id:, execution_id:, invocation_id:, name:, arguments:, names:)
+        participate(scope) do |records|
+          execution = records.executions.load(execution_id)
+          unless execution.agent_id == agent_id
+            raise Phronomy::Persistence::StateConflictError, "Authorized operation owner mismatch"
+          end
+          batch = Array(execution.metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY])
+          requested = batch.find { |entry| entry.fetch("tool_invocation_id") == invocation_id }
+          unless names.include?(name) && requested && requested.fetch("status") == "authorized" &&
+              requested.fetch("tool_name") == name && authorized_argument_values(requested) == arguments
+            raise Phronomy::Persistence::StateConflictError, "Operation #{invocation_id} is not the authorized call"
+          end
+          batch.filter_map do |entry|
+            next unless entry.fetch("status") == "authorized" && names.include?(entry.fetch("tool_name"))
+            AuthorizedOperation.new(
+              invocation_id: Phronomy::Values::Immutable.copy(entry.fetch("tool_invocation_id")),
+              name: Phronomy::Values::Immutable.copy(entry.fetch("tool_name")),
+              arguments: Phronomy::Values::Immutable.copy(authorized_argument_values(entry))
+            )
+          end.freeze
+        end
+      end
+
+      def result(execution_id)
+        assert_observation_thread!
+        execution = executions.load(execution_id)
+        {
+          execution_id: execution.execution_id, agent_id: execution.agent_id,
+          status: execution.status, phase: execution.phase,
+          result_ref: execution.result_ref, error_ref: execution.error_ref,
+          result: execution.result_ref && contents.fetch_text(execution.result_ref),
+          error: execution.error_ref && contents.fetch_json(execution.error_ref)
+        }.then { |value| Phronomy::Values::Immutable.copy(value) }
+      end
+
+      # Exact, immutable observation. Only authoritative NotFound means absent.
+      def observe_execution(agent_id:, execution_id:, scope: nil)
+        with_scope(scope) do |records|
+          begin
+            execution = records.executions.load(execution_id)
+          rescue Phronomy::Persistence::NotFoundError
+            next ExecutionObservation.new(agent_id: agent_id, execution_id: execution_id,
+              status: :absent, result: nil, error: nil, reservation: nil,
+              transfer_receipt: nil, cancellation_requested: false)
+          end
+          assert_execution_owner!(execution, agent_id)
+          ExecutionObservation.new(agent_id: execution.agent_id, execution_id: execution.execution_id,
+            status: execution.status,
+            result: execution.result_ref && records.contents.fetch_text(execution.result_ref),
+            error: execution.error_ref && Phronomy::Values::Immutable.copy(records.contents.fetch_json(execution.error_ref)),
+            reservation: execution.metadata["reservation"] && ReservedExecution.new(agent_id: agent_id,
+              execution_id: execution_id, correlation: execution.metadata["reservation"]),
+            transfer_receipt: Phronomy::Values::Immutable.copy(execution.metadata["transfer_receipt"]),
+            cancellation_requested: records.cancellations.requested?(agent_id, execution_id) || execution.metadata["cancellation_requested"] == true)
+        end
+      end
+
+      def active_executions(agent_id:, scope: nil)
+        with_scope(scope) do |records|
+          records.executions.list_active(agent_id).map do |execution|
+            observe_execution(agent_id: agent_id, execution_id: execution.execution_id, scope: scope)
+          end.freeze
+        end
+      end
+
+      def definition(agent_id:, scope: nil)
+        with_scope(scope) do |records|
+          root = records.agents.load(agent_id)
+          {id: root.agent_definition_id, version: root.agent_definition_version}.freeze
+        end
+      end
+
+      def knowledge_snapshot(agent_id:, scope: nil)
+        with_scope(scope) do |records|
+          root = records.agents.load(agent_id)
+          journal = records.journals.read(agent_id, limit: root.journal_position)
+          JournalProjection.new(agent_root: root, records: journal).context_records.filter_map do |record|
+            next unless record.kind == :knowledge
+            KnowledgeItem.new(content: records.contents.fetch_text(record.content_ref), metadata: record.metadata)
+          end.freeze
+        end
+      end
+
+      # Participant SPI: opaque extension state, never an AgentExecution getter.
+      def execution_extension(agent_id:, execution_id:, binding_key:, scope: nil)
+        with_scope(scope) do |records|
+          execution = records.executions.load(execution_id)
+          assert_execution_owner!(execution, agent_id)
+          raw = execution.metadata["execution_extension"]
+          next nil unless raw
+          extension = ExecutionExtensionState.from_h(raw)
+          unless extension.binding_key == binding_key
+            raise Phronomy::ConfigurationError, "Execution participant binding mismatch"
+          end
+          extension
+        end
+      end
+
+      # Coordination guards are acquired first by the participant. All Agent
+      # roots then use the same lexical order, including admission and purge.
+      def guard_agents(scope, agent_ids:)
+        participate(scope) { |records| agent_ids.map(&:to_s).uniq.sort.each { |id| records.guard_agent!(id) } }
+        nil
+      end
+
+      # History release is terminal-only and preserves execution/result identity.
+      def remove_execution_extension(agent_id:, execution_id:, binding_key:, scope:)
+        participate(scope) do |records|
+          records.guard_agent!(agent_id)
+          execution = records.executions.load(execution_id)
+          assert_execution_owner!(execution, agent_id)
+          raise Phronomy::AgentBusyError, "Active execution history cannot be released" unless execution.terminal?
+          extension = execution.metadata["execution_extension"]
+          unless extension && extension.fetch("binding_key") == binding_key
+            raise Phronomy::Persistence::StateConflictError, "Extension history identity mismatch"
+          end
+          updated = execution.with(metadata: execution.metadata.except("execution_extension"))
+          records.executions.save(execution_id, expected_revision: execution.execution_revision, execution: updated)
+        end
+        nil
+      end
+
+      def execution_identity(execution_id, scope: nil)
+        with_scope(scope) do |records|
+          execution = records.executions.load(execution_id)
+          ReservedExecution.new(agent_id: execution.agent_id, execution_id: execution.execution_id,
+            correlation: execution.metadata["reservation"])
+        end
+      end
+
+      def retained_references(agent_id:, scope: nil)
+        with_scope(scope) { |records| records.retentions.list(agent_id) }
+      end
+
+      def retain(retention, scope: nil)
+        with_scope(scope) do |records|
+          records.guard_agent!(retention.agent_id)
+          records.agents.load(retention.agent_id)
+          records.retentions.retain(retention)
+        end
+      end
+
+      def release_retention(agent_id:, owner_key:, scope:)
+        participate(scope) { |records| records.retentions.release(agent_id: agent_id, owner_key: owner_key) }
+      end
+
+      def cancellation_requested?(agent_id:, execution_id:, scope: nil)
+        with_scope(scope) { |records| records.cancellations.requested?(agent_id, execution_id) }
+      end
+
+      def request_cancellation(agent_id:, execution_id:, scope: nil)
+        with_scope(scope) do |records|
+          records.guard_agent!(agent_id)
+          begin
+            current = records.executions.load(execution_id)
+          rescue Phronomy::Persistence::NotFoundError
+            next false
+          end
+          assert_execution_owner!(current, agent_id)
+          next false if current.terminal?
+          records.cancellations.request(agent_id, execution_id)
+          true
+        end
+      end
+
+      def runs(agent_id, after: nil, limit: 100)
+        assert_observation_thread!
+        executions.list(agent_id, after: after, limit: limit)
+      end
+
+      # Agent's snapshot fence, independent of any physical schema.
+      def assert_agent_watermark!(agent_id:, agent_revision:, journal_position:)
+        @records.assert_agent_watermark!(agent_id: agent_id, agent_revision: agent_revision, journal_position: journal_position)
+      end
+
+      private
+
+      def authorized_argument_values(entry)
+        # Unit 6 persists the exact validated snapshot. Older records encoded
+        # legacy raw params, whose explicit optional nil meant omission.
+        entry.key?("validated_arguments") ? entry.fetch("validated_arguments") : entry.fetch("arguments").compact
+      end
+
+      def with_scope(scope, &block)
+        assert_observation_thread!
+        scope ? participate(scope, &block) : transaction(&block)
+      end
+
+      def assert_execution_owner!(execution, agent_id)
+        unless execution.agent_id == agent_id.to_s
+          raise Phronomy::Persistence::StateConflictError, "Execution owner mismatch"
+        end
+      end
+
+      def assert_observation_thread!
+        if Phronomy::WaitPolicy.blocking_forbidden?
+          raise Phronomy::EventLoopReentrancyError, "Durable observation cannot block EventLoop"
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/{lifecycle_contract/stream_callback_error.rb → stream_callback_error.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../common/error"
+require_relative "../common/error"
 
 module Phronomy
   # Raised when an Application stream callback fails and