phronomy 0.28.0 → 0.30.0

data/lib/phronomy/agent/filterable.rb

@@ -92,9 +92,11 @@ module Phronomy
       # @return [self]
       # @api public
       def add_input_filter(filter)
-        @_instance_input_filters ||= []
-        @_instance_input_filters << _resolve_filter(filter)
-        self
+        __with_operation do
+          @_instance_input_filters ||= []
+          @_instance_input_filters << _resolve_filter(filter)
+          self
+        end
       end
 
       # Registers an output filter on this instance.
@@ -105,9 +107,11 @@ module Phronomy
       # @return [self]
       # @api public
       def add_output_filter(filter)
-        @_instance_output_filters ||= []
-        @_instance_output_filters << _resolve_filter(filter)
-        self
+        __with_operation do
+          @_instance_output_filters ||= []
+          @_instance_output_filters << _resolve_filter(filter)
+          self
+        end
       end
 
       # Registers a tool result filter on this instance.
@@ -125,16 +129,18 @@ module Phronomy
       # @return [self]
       # @api public
       def add_tool_result_filter(tool_class_or_filter, filter = nil)
-        if filter.nil?
-          # Single-argument form: apply to all tools.
-          @_instance_tool_result_filters ||= []
-          @_instance_tool_result_filters << _resolve_filter(tool_class_or_filter)
-        else
-          # Two-argument form: scoped to one tool class.
-          @_scoped_tool_result_filters ||= {}
-          (@_scoped_tool_result_filters[tool_class_or_filter] ||= []) << _resolve_filter(filter)
+        __with_operation do
+          if filter.nil?
+            # Single-argument form: apply to all tools.
+            @_instance_tool_result_filters ||= []
+            @_instance_tool_result_filters << _resolve_filter(tool_class_or_filter)
+          else
+            # Two-argument form: scoped to one tool class.
+            @_scoped_tool_result_filters ||= {}
+            (@_scoped_tool_result_filters[tool_class_or_filter] ||= []) << _resolve_filter(filter)
+          end
+          self
         end
-        self
       end
 
       private

data/lib/phronomy/agent/lifecycle/lifetime_api.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Public admission boundaries. The explicit operation capability belongs to
+    # C04, including queued work and domain completion after logical cancellation.
+    # @api private
+    module LifetimeApi
+      # Releases only the Runtime incarnation; durable state and Store stay intact.
+      # @return [TaskResult<Boolean>]
+      # @api public
+      def unload_async
+        return Phronomy::TaskResult.completed(false) if @_phronomy_runtime_owner_state == :unloaded
+
+        __assert_agent_accessible!
+        transition, start = __execution_environment.ownership.reserve_unload(self)
+        start ? transition.start : transition.result
+      rescue => error
+        Phronomy::TaskResult.failed(error)
+      end
+
+      # A timeout stops this wait, never the accepted release.
+      # @return [Boolean]
+      # @api public
+      def unload!(timeout: nil)
+        _check_event_loop_reentrancy(:unload!, :unload_async)
+        unload_async.wait_result(timeout: timeout)
+      end
+
+      private
+
+      def __with_operation(async: false, read_only: false)
+        lease = __acquire_operation!(read_only: read_only)
+        followed = false
+        value = yield
+        if async && lease
+          lease.follow(value)
+          followed = true
+        end
+        value
+      rescue Phronomy::AgentUnloadedError, Phronomy::AgentBusyError, Phronomy::RuntimeShutdownError => error
+        raise unless async
+        Phronomy::TaskResult.failed(error)
+      ensure
+        lease&.release unless followed
+      end
+
+      # Accepted C04 commands carry their admission/operation capability. Their
+      # continuations read the snapshot without entering the public admission gate.
+      def __root_for_operation
+        __assert_agent_accessible!
+        @root
+      end
+
+      def __acquire_operation!(read_only: false)
+        __assert_agent_accessible!
+        return nil if @_phronomy_runtime_owner_state == :constructing
+
+        __execution_environment.ownership.acquire_operation(self, read_only: read_only)
+      end
+
+      def __mark_unloaded!
+        @_phronomy_runtime_owner_state = :unloaded
+        @root = nil
+        @_phronomy_journal_records = [].freeze
+        @_phronomy_event_listener = nil
+        @_phronomy_execution_wiring = {}.freeze
+        @execution_coordinator = nil
+        @tool_approval_policy = @before_llm_input = nil
+        @_instance_input_filters = @_instance_output_filters = nil
+        @_instance_tool_result_filters = @_scoped_tool_result_filters = nil
+        @initial_retention = nil
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/operation_lease.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # C04 capability for accepted work. Never inferred from the current thread.
+    # @api private
+    class OperationLease
+      def initialize(registry, agent, token)
+        @registry, @agent, @token = registry, agent, token
+        @mutex = Mutex.new
+      end
+
+      def release
+        ownership = @mutex.synchronize do
+          next unless @registry
+          current = [@registry, @agent, @token]
+          @registry = @agent = @token = nil
+          current
+        end
+        ownership&.first&.release_operation(ownership[1], ownership[2])
+      end
+
+      def follow(task)
+        if task.respond_to?(:on_physical_complete)
+          task.on_physical_complete { release }
+        else
+          task.on_complete { |_value, _error| release }
+        end
+        task
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/operation_result.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Logical cancellation of a public handle does not release Agent ownership.
+    # Only the domain runner acknowledges the end of its accepted operation.
+    # @api private
+    class OperationResult < Phronomy::Concurrency::PhysicalCompletionTask
+      def initialize(agent:, name:)
+        super(name: name)
+        @operation_lease = agent.send(:__acquire_operation!)
+        @lifetime_mutex = Mutex.new
+        @work = 0
+        @finished = false
+        @released = false
+      end
+
+      def finish_operation!
+        @lifetime_mutex.synchronize { @finished = true }
+        release_if_quiet
+      end
+
+      def track(task)
+        @lifetime_mutex.synchronize { @work += 1 }
+        task.on_physical_complete do
+          @lifetime_mutex.synchronize { @work -= 1 }
+          release_if_quiet
+        end
+        task
+      end
+
+      def settle(value = nil, error: nil)
+        finish_operation!
+        error ? fail(error) : complete(value)
+      end
+
+      private
+
+      def release_if_quiet
+        released = @lifetime_mutex.synchronize do
+          next unless @finished && @work.zero? && !@released
+          @released = true
+          current = @operation_lease
+          @operation_lease = nil
+          [current]
+        end
+        return unless released
+        released.first&.release
+        mark_physical_complete!
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/ownership_registry.rb

@@ -25,12 +25,14 @@ module Phronomy
         @mutex = Mutex.new
         @condition = ConditionVariable.new
         @entries = {}
+        @scope_owners = {}
+        @operations = {}
         @state = :running
       end
 
-      def create(agent_id, expected_class:)
+      def create(agent_id, expected_class:, scope_owner: nil)
         key = normalize_agent_id(agent_id)
-        token = reserve_create!(key)
+        token = reserve_create!(key, scope_owner: scope_owner)
 
         begin
           agent = yield(@environment)
@@ -59,7 +61,7 @@ module Phronomy
         )
       end
 
-      def load(agent_id, expected_class:)
+      def load(agent_id, expected_class:, scope_owner: nil)
         key = normalize_agent_id(agent_id)
         token = nil
 
@@ -67,9 +69,14 @@ module Phronomy
           existing = @mutex.synchronize do
             ensure_running!
             entry = @entries[key]
+            if scope_owner && entry && !@scope_owners[key].equal?(scope_owner)
+              raise Phronomy::AgentBusyError, "Agent #{key.inspect} belongs to another live owner"
+            end
             case entry&.state
             when :live
               entry.agent
+            when :unloading
+              raise Phronomy::AgentBusyError, "Agent #{key.inspect} is unloading"
             when :constructing, :purging
               @condition.wait(@mutex)
               :retry
@@ -78,6 +85,7 @@ module Phronomy
             when nil
               token = Object.new.freeze
               @entries[key] = Entry.new(state: :constructing, agent: nil, token: token)
+              @scope_owners[key] = scope_owner if scope_owner
               nil
             # :nocov:
             else
@@ -119,8 +127,8 @@ module Phronomy
           when :recovery_required
             raise ownership_recovery_error(key)
           # :nocov:
-          when :purging
-            raise Phronomy::Error, "Agent #{key.inspect} is being purged"
+          when :purging, :unloading
+            raise Phronomy::AgentBusyError, "Agent #{key.inspect} is #{entry.state}"
             # :cover:
           end
         end
@@ -129,13 +137,77 @@ module Phronomy
         validate_expected_class!(agent, expected_class, key)
       end
 
+      # Admission and lifetime transitions share this mutex. No Runtime or Store
+      # operation is called while it is held.
+      def acquire_operation(agent, read_only: false)
+        token = Object.new.freeze
+        @mutex.synchronize do
+          ensure_running! unless read_only && @state == :draining
+          entry = @entries[agent.agent_id]
+          if entry&.agent&.equal?(agent) && entry.state == :unloading
+            raise Phronomy::AgentBusyError, "Agent #{agent.agent_id.inspect} is unloading"
+          end
+          unless entry&.state == :live && entry.agent.equal?(agent)
+            raise Phronomy::RuntimeShutdownError, "Agent is no longer the live Runtime owner"
+          end
+          (@operations[agent] ||= {})[token] = true
+        end
+        OperationLease.new(self, agent, token)
+      end
+
+      def release_operation(agent, token)
+        @mutex.synchronize do
+          operations = @operations[agent]
+          operations&.delete(token)
+          @operations.delete(agent) if operations && operations.empty?
+          @condition.broadcast
+        end
+        true
+      end
+
+      # Returns the already accepted transition for duplicate callers.
+      def reserve_unload(agent)
+        @mutex.synchronize do
+          ensure_running!
+          entry = @entries[agent.agent_id]
+          if entry&.state == :unloading && entry.agent.equal?(agent)
+            return [entry.token, false]
+          end
+          unless entry&.state == :live && entry.agent.equal?(agent)
+            raise Phronomy::RuntimeShutdownError, "Agent is no longer the live Runtime owner"
+          end
+          assert_no_operations!(agent)
+          transition = UnloadTransition.new(agent: agent, environment: @environment, ownership: self)
+          @entries[agent.agent_id] = Entry.new(state: :unloading, agent: agent, token: transition)
+          [transition, true]
+        end
+      end
+
+      def finish_unload(agent, transition, success:)
+        @mutex.synchronize do
+          entry = @entries[agent.agent_id]
+          unless entry&.state == :unloading && entry.agent.equal?(agent) && entry.token.equal?(transition)
+            raise Phronomy::RuntimeShutdownError, "Agent unload reservation is no longer authoritative"
+          end
+          if success
+            agent.send(:__mark_unloaded!)
+            @entries.delete(agent.agent_id)
+            @scope_owners.delete(agent.agent_id)
+          else
+            @entries[agent.agent_id] = Entry.new(state: :live, agent: agent, token: nil)
+          end
+          @condition.broadcast
+        end
+        true
+      end
+
       def owned?(agent)
         return false unless agent
 
         key = normalize_agent_id(agent.agent_id)
         @mutex.synchronize do
           entry = @entries[key]
-          entry&.state == :live && entry.agent.equal?(agent)
+          %i[live unloading].include?(entry&.state) && entry.agent.equal?(agent)
         end
       rescue ArgumentError
         false
@@ -151,9 +223,13 @@ module Phronomy
           ensure_running!
           entry = @entries[key]
           unless entry&.state == :live && entry.agent.equal?(agent)
+            if entry&.state == :unloading && entry.agent.equal?(agent)
+              raise Phronomy::AgentBusyError, "Agent #{key.inspect} is unloading"
+            end
             raise Phronomy::RuntimeShutdownError,
               "Agent #{key.inspect} is not the live owner in this Runtime"
           end
+          assert_no_operations!(agent)
           @entries[key] = Entry.new(state: :purging, agent: agent, token: token)
         end
         agent.send(:__mark_purging!, @environment)
@@ -167,6 +243,7 @@ module Phronomy
           validate_purge_entry!(entry, agent, token, key)
           agent.send(:__mark_purged!, @environment)
           @entries.delete(key)
+          @scope_owners.delete(key)
           @condition.broadcast
         end
         true
@@ -215,7 +292,7 @@ module Phronomy
       # ownership transition that is still actively changing state must settle.
       def wait_until_idle(deadline)
         @mutex.synchronize do
-          while @entries.values.any? { |entry| %i[constructing purging].include?(entry.state) }
+          while @entries.values.any? { |entry| %i[constructing purging unloading].include?(entry.state) }
             remaining = deadline - monotonic_now
             # :nocov:
             return false if remaining <= 0
@@ -231,6 +308,8 @@ module Phronomy
           @state = :terminated
           owned = @entries.values.filter_map(&:agent).uniq
           @entries.clear
+          @scope_owners.clear
+          @operations.clear
           @condition.broadcast
           owned
         end
@@ -240,17 +319,22 @@ module Phronomy
 
       private
 
-      def reserve_create!(key)
+      def reserve_create!(key, scope_owner: nil)
         token = Object.new.freeze
         @mutex.synchronize do
           ensure_running!
           if (entry = @entries[key])
             raise ownership_recovery_error(key) if entry.state == :recovery_required
 
+            if scope_owner
+              raise Phronomy::AgentBusyError, "Agent #{key.inspect} already has a Runtime owner"
+            end
+
             raise Phronomy::AgentAlreadyExistsError,
               "Agent #{key.inspect} already exists in this Runtime (#{entry.state})"
           end
           @entries[key] = Entry.new(state: :constructing, agent: nil, token: token)
+          @scope_owners[key] = scope_owner if scope_owner
         end
         token
       end
@@ -291,6 +375,7 @@ module Phronomy
           # :nocov:
           if entry&.state == :constructing && entry.token.equal?(token)
             @entries.delete(key)
+            @scope_owners.delete(key)
             @condition.broadcast
           end
           # :cover:
@@ -353,6 +438,12 @@ module Phronomy
         # :cover:
       end
 
+      def assert_no_operations!(agent)
+        return unless @operations[agent]&.any?
+
+        raise Phronomy::AgentBusyError, "Agent #{agent.agent_id.inspect} still has accepted operations"
+      end
+
       def monotonic_now
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end

data/lib/phronomy/agent/lifecycle/scope.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Owns the Agents materialized within one application operation. A scope is
+    # Runtime-bound, process-local, and must not be persisted as Workflow state.
+    # @api public
+    class Scope
+      # @api private
+      def self.open
+        raise ArgumentError, "open_scope requires a block" unless block_given?
+        if Phronomy::WaitPolicy.blocking_forbidden?
+          raise Phronomy::EventLoopReentrancyError, "Agent.open_scope cannot block EventLoop"
+        end
+
+        scope = new(environment: ExecutionEnvironment.current)
+        result = nil
+        primary = nil
+        begin
+          returned = yield(scope)
+          result = returned.is_a?(Phronomy::TaskResult) ? returned.wait_result : returned
+        rescue Exception => error # standard:disable Lint/RescueException
+          primary = error
+          raise
+        ensure
+          begin
+            scope.release!
+          rescue => cleanup
+            failures = cleanup.is_a?(ScopeCleanupError) ? cleanup.failures : [{agent_id: nil, error: cleanup}]
+            raise ScopeCleanupError.new(scope: scope, failures: failures, result: result,
+              primary_error: primary), cause: primary || failures.first.fetch(:error)
+          end
+        end
+        result
+      end
+      private_class_method :open
+
+      def initialize(environment:)
+        @environment = environment
+        @ownership = environment.ownership
+        @owner_token = Object.new.freeze
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @state = :open
+        @receipts = {}
+        @agents = {}
+      end
+      private_class_method :new
+
+      # @return [Agent::Base]
+      # @api public
+      def create(agent_class, **options, &listener)
+        check_blocking!
+        materialize(:create, agent_class, options, listener, async: false)
+      end
+
+      # @return [TaskResult<Agent::Base>]
+      # @api public
+      def create_async(agent_class, **options, &listener)
+        materialize(:create, agent_class, options, listener, async: true)
+      rescue => error
+        Phronomy::TaskResult.failed(error)
+      end
+
+      # Repeated load in this scope returns the same live owner. Supplying a new
+      # listener or different Store for an already live instance is rejected.
+      # @return [Agent::Base]
+      # @api public
+      def load(agent_class, agent_id, persistence:, **options, &listener)
+        check_blocking!
+        materialize(:load, agent_class, options.merge(agent_id: agent_id, persistence: persistence), listener, async: false)
+      end
+
+      # @return [TaskResult<Agent::Base>]
+      # @api public
+      def load_async(agent_class, agent_id, persistence:, **options, &listener)
+        materialize(:load, agent_class, options.merge(agent_id: agent_id, persistence: persistence), listener, async: true)
+      rescue => error
+        Phronomy::TaskResult.failed(error)
+      end
+
+      # Release only safe owners; retain failed owners so the caller can retry.
+      # @api public
+      def release!
+        owns_release = false
+        check_blocking!
+        agents = @mutex.synchronize do
+          return false if @state == :released
+          raise Phronomy::Error.new("Agent scope is releasing", code: "agent.scope_busy") if @state == :releasing
+          @state = :releasing
+          owns_release = true
+          @condition.wait(@mutex) until @receipts.empty?
+          @agents.values.dup
+        end
+        failures = []
+        agents.each do |agent|
+          agent.unload!
+          @mutex.synchronize { @agents.delete(agent.object_id) }
+        rescue => error
+          failures << {agent_id: agent.agent_id, error: error}.freeze
+        end
+        @mutex.synchronize do
+          @state = failures.empty? ? :released : :release_failed
+          @environment = @ownership = @owner_token = nil if failures.empty?
+        end
+        unless failures.empty?
+          raise ScopeCleanupError.new(scope: self, failures: failures), cause: failures.first.fetch(:error)
+        end
+        true
+      ensure
+        # An interrupted waiter/unloader must remain retryable, without changing
+        # another thread's release state when this call was rejected as busy.
+        if owns_release
+          @mutex.synchronize { @state = :release_failed if @state == :releasing }
+        end
+      end
+
+      private
+
+      def check_blocking!
+        return unless Phronomy::WaitPolicy.blocking_forbidden?
+
+        raise Phronomy::EventLoopReentrancyError, "Agent scope materialization cannot block EventLoop; use create_async/load_async"
+      end
+
+      def materialize(kind, agent_class, options, listener, async:)
+        unless agent_class.is_a?(Class) && agent_class <= Base
+          raise ArgumentError, "agent_class must be an Agent::Base subclass"
+        end
+        if options[:on_event] && listener
+          raise ArgumentError, "Provide either on_event: or a block, not both"
+        end
+        if kind == :load && !options[:persistence]
+          raise ArgumentError, "persistence is required"
+        end
+        key = (options[:agent_id] || (SecureRandom.uuid if kind == :create)).to_s.dup.freeze
+        raise ArgumentError, "agent_id must not be empty" if key.empty?
+        options = options.merge(agent_id: key)
+        receipt = Object.new.freeze
+        @mutex.synchronize do
+          raise Phronomy::Error, "Agent scope is #{@state}" unless @state == :open
+          @receipts[receipt] = key
+        end
+        operation = -> { acquire(kind, agent_class, key, options, listener) }
+        if async
+          begin
+            task = @environment.submit(on_full: :raise, &operation)
+            task.on_physical_complete { finish_receipt(receipt) }
+            task
+          rescue
+            finish_receipt(receipt)
+            raise
+          end
+        else
+          begin
+            operation.call
+          ensure
+            finish_receipt(receipt)
+          end
+        end
+      end
+
+      def acquire(kind, agent_class, key, options, listener)
+        materialized = false
+        agent = @ownership.public_send(kind, key, expected_class: agent_class, scope_owner: @owner_token) do |environment|
+          materialized = true
+          instance = agent_class.send(:__construct_owned_agent, environment, key,
+            **options, load_existing: kind == :load, &listener)
+          RecoveryCoordinator.new(instance).recover_on_load! if kind == :load
+          instance
+        end
+        # Register before any result or post-materialization check reaches the
+        # caller, even when scope closure began while the worker was running.
+        @mutex.synchronize { @agents[agent.object_id] = agent }
+        if kind == :load
+          unless agent.persistence.equal?(options[:persistence])
+            raise Phronomy::ConfigurationError, "Agent #{key.inspect} is already live with a different Persistence instance"
+          end
+          if !materialized && (options[:on_event] || listener)
+            raise Phronomy::ConfigurationError, "Agent #{key.inspect} is already live; load cannot re-bind on_event"
+          end
+        end
+        agent
+      rescue Phronomy::Persistence::ConflictError => error
+        raise unless kind == :create
+        raise Phronomy::AgentAlreadyExistsError, "Agent #{key.inspect} already exists durably: #{error.message}"
+      rescue => error
+        # A fail-closed construction remains reserved in C04. Do not purge or
+        # release that reservation just because no instance reached this scope.
+        report_materialization_error(key, error)
+        raise
+      end
+
+      def finish_receipt(receipt)
+        @mutex.synchronize do
+          @receipts.delete(receipt)
+          @condition.broadcast
+        end
+      end
+
+      def report_materialization_error(key, error)
+        Phronomy::RuntimeSettings.current.logger&.warn("[Agent scope] materialization failed agent_id=#{key.inspect}: #{error.class}: #{error.message}")
+      rescue
+        nil
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/scope_cleanup_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Successful application work with one or more failed Agent releases.
+    # Original exceptions and the successful result remain available to the caller.
+    # @api public
+    class ScopeCleanupError < Phronomy::Error
+      attr_reader :failures, :result, :primary_error, :scope
+
+      def initialize(scope:, failures:, result: nil, primary_error: nil)
+        @failures = failures.map { |failure| failure.dup.freeze }.freeze
+        @result = result
+        @primary_error = primary_error
+        @scope = scope
+        super("Agent scope cleanup failed for: #{@failures.map { |f| f.fetch(:agent_id) }.join(", ")}",
+          code: "agent.scope_cleanup_failed")
+      end
+    end
+  end
+end