phronomy 0.27.0 → 0.29.0

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

@@ -12,37 +12,34 @@ module Phronomy
       # Candidates have no side effects. Runtime retains the first registration.
       # Existing instances remain available for lookup and transition completion
       # after admission closes; their own gate rejects new ownership changes.
-      def self.for(runtime)
-        existing_for(runtime) || runtime.__register_shutdown_participant(
-          key: self, participant: new(runtime: runtime)
-        )
-      end
-
-      def self.existing_for(runtime)
-        runtime.__shutdown_participant(key: self)
-      end
+      def self.current = ExecutionEnvironment.current.ownership
+      def self.existing_current = ExecutionEnvironment.current.existing_ownership
+      def self.for(environment) = environment.ownership
+      def self.existing_for(environment) = environment.existing_ownership
 
       Entry = Data.define(:state, :agent, :token)
       private_constant :Entry
 
-      def initialize(runtime:)
-        @runtime = runtime
+      def initialize(environment:)
+        @environment = environment
         @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(@runtime)
+          agent = yield(@environment)
         rescue Phronomy::AgentAlreadyExistsError,
-          Phronomy::Storage::ConflictError,
-          Phronomy::Storage::NotFoundError,
-          Phronomy::Storage::SerializationError,
+          Phronomy::Persistence::ConflictError,
+          Phronomy::Persistence::NotFoundError,
+          Phronomy::Persistence::SerializationError,
           ArgumentError,
           Phronomy::ConfigurationError
           release_construction!(key, token)
@@ -64,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
 
@@ -72,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
@@ -83,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
@@ -98,7 +101,7 @@ module Phronomy
         end
 
         begin
-          agent = yield(@runtime)
+          agent = yield(@environment)
           publish_constructed!(
             key,
             token,
@@ -124,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
@@ -134,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
@@ -156,12 +223,16 @@ 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!, @runtime)
+        agent.send(:__mark_purging!, @environment)
         token
       end
 
@@ -170,8 +241,9 @@ module Phronomy
         @mutex.synchronize do
           entry = @entries[key]
           validate_purge_entry!(entry, agent, token, key)
-          agent.send(:__mark_purged!, @runtime)
+          agent.send(:__mark_purged!, @environment)
           @entries.delete(key)
+          @scope_owners.delete(key)
           @condition.broadcast
         end
         true
@@ -183,7 +255,7 @@ module Phronomy
         @mutex.synchronize do
           entry = @entries[key]
           validate_purge_entry!(entry, agent, token, key)
-          agent.send(:__restore_live_after_purge_abort!, @runtime)
+          agent.send(:__restore_live_after_purge_abort!, @environment)
           @entries[key] = Entry.new(state: :live, agent: agent, token: nil)
           @condition.broadcast
         end
@@ -197,7 +269,7 @@ module Phronomy
         key = normalize_agent_id(agent.agent_id)
         @mutex.synchronize do
           validate_purge_entry!(@entries[key], agent, token, key)
-          agent.send(:__mark_ownership_recovery_required!, @runtime)
+          agent.send(:__mark_ownership_recovery_required!, @environment)
           @entries[key] = Entry.new(
             state: :recovery_required,
             agent: agent,
@@ -220,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
@@ -236,26 +308,33 @@ module Phronomy
           @state = :terminated
           owned = @entries.values.filter_map(&:agent).uniq
           @entries.clear
+          @scope_owners.clear
+          @operations.clear
           @condition.broadcast
           owned
         end
-        agents.each { |agent| agent.send(:__release_runtime_owner!, @runtime) }
+        agents.each { |agent| agent.send(:__release_runtime_owner!, @environment) }
         true
       end
 
       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
@@ -267,7 +346,7 @@ module Phronomy
             "constructed Agent identity mismatch: reserved #{key.inspect}, got #{agent.agent_id.inspect}"
         end
 
-        agent.send(:__bind_runtime_owner!, @runtime)
+        agent.send(:__bind_runtime_owner!, @environment)
         @mutex.synchronize do
           entry = @entries[key]
           unless entry&.state == :constructing && entry.token.equal?(token)
@@ -282,7 +361,7 @@ module Phronomy
         # :nocov:
         if fail_closed
           fail_construction_closed!(key, token, agent: agent)
-          agent&.send(:__mark_ownership_recovery_required!, @runtime)
+          agent&.send(:__mark_ownership_recovery_required!, @environment)
         else
           release_construction!(key, token)
         end
@@ -296,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:
@@ -358,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,198 @@
+# 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
+        begin
+          result = yield(scope)
+          result = result.wait_result if result.is_a?(Phronomy::TaskResult)
+        rescue Exception => primary # standard:disable Lint/RescueException
+          raise
+        ensure
+          failures = scope.send(:__close)
+          if primary
+            failures.each do |failure|
+              error = failure.fetch(:error)
+              Phronomy::RuntimeSettings.current.logger&.warn(
+                "[Agent scope] cleanup failed agent_id=#{failure.fetch(:agent_id).inspect}: #{error.class}: #{error.message}"
+              )
+            rescue
+              nil
+            end
+          elsif failures.any?
+            raise ScopeCleanupError.new(failures: failures, result: result)
+          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
+
+      # @api private
+      def __close
+        agents = @mutex.synchronize do
+          @state = :closing
+          @condition.wait(@mutex) until @receipts.empty?
+          @agents.values.dup
+        end
+        failures = []
+        agents.each do |agent|
+          agent.unload!
+        rescue => error
+          failures << {agent_id: agent.agent_id, error: error}.freeze
+        end
+        @mutex.synchronize do
+          @agents.clear
+          @environment = @ownership = @owner_token = nil
+          @state = :closed
+        end
+        failures.freeze
+      end
+      private :__close
+
+      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,19 @@
+# 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
+
+      def initialize(failures:, result:)
+        @failures = failures.map { |failure| failure.dup.freeze }.freeze
+        @result = result
+        super("Agent scope cleanup failed for: #{@failures.map { |f| f.fetch(:agent_id) }.join(", ")}",
+          code: "agent.scope_cleanup_failed")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Agent-owned two-phase release. The worker only checks durable facts; the
+    # EventLoop completes the exact process-local reservation after physical I/O.
+    # @api private
+    class UnloadTransition
+      Command = Data.define(:coordinator, :phase)
+      private_constant :Command
+
+      attr_reader :result
+
+      def initialize(agent:, environment:, ownership:)
+        @agent, @environment, @ownership = agent, environment, ownership
+        @result = Phronomy::TaskResult.deferred(name: "agent-unload:#{agent.agent_id}")
+        @mutex = Mutex.new
+        @finished = false
+      end
+
+      def start
+        post(:check)
+        @result
+      end
+
+      def deliver_on_event_loop(command)
+        if command.phase == :check
+          if @environment.existing_registry&.agent_execution_admitted?(@agent.agent_id)
+            raise Phronomy::AgentBusyError, "Agent #{@agent.agent_id.inspect} has a nonterminal execution"
+          end
+          agent_id, persistence = @agent.agent_id, @agent.persistence
+          task = @environment.submit(on_full: :raise) do
+            persistence.transaction do |tx|
+              tx.executions.assert_idle!(agent_id)
+              tx.guard_agent!(agent_id)
+              unless tx.retentions.list(agent_id).empty?
+                raise Phronomy::AgentBusyError, "Agent #{agent_id.inspect} is retained by durable coordination"
+              end
+            end
+          end
+          task.on_complete do |_value, error|
+            @read_error = error
+            task.on_physical_complete { post(:apply) }
+          end
+        else
+          finish(@read_error)
+        end
+      rescue => error
+        finish(error)
+      end
+
+      private
+
+      def post(phase)
+        accepted = @environment.registry.post(Command.new(coordinator: self, phase: phase), completion: @result)
+        finish(Phronomy::RuntimeShutdownError.new("EventLoop rejected Agent unload #{phase}")) unless accepted
+      rescue => error
+        finish(error)
+      end
+
+      def finish(error)
+        first = @mutex.synchronize do
+          next false if @finished
+          @finished = true
+        end
+        return unless first
+
+        begin
+          @ownership.finish_unload(@agent, self, success: error.nil?)
+        rescue => ownership_error
+          error ||= ownership_error
+        end
+        @agent = @environment = @ownership = nil
+        error ? @result.fail(error) : @result.complete(true)
+      end
+    end
+  end
+end

data/lib/phronomy/agent/persistence/agent_repository.rb

@@ -9,39 +9,47 @@ module Phronomy
         def initialize(view) = @view = view
 
         def create(root)
-          record = Codec.encode_agent_root(root)
-          @view.atomic do |bound|
-            entry = bound.records(StorageSchema::ROOTS).insert(key: root.agent_id.to_s,
-              revision: Integer(root.agent_revision), attributes: {}, record: record)
-            decode(entry, root.agent_id, revision: root.agent_revision)
+          Phronomy::Persistence::StorageBoundary.call do
+            record = Codec.encode_agent_root(root)
+            @view.atomic do |bound|
+              entry = bound.records(StorageSchema::ROOTS).insert(key: root.agent_id.to_s,
+                revision: Integer(root.agent_revision), attributes: {}, record: record)
+              decode(entry, root.agent_id, revision: root.agent_revision)
+            end
           end
         end
 
         def load(agent_id)
-          value = @view.atomic do |bound|
-            entry = bound.records(StorageSchema::ROOTS).read(agent_id.to_s)
-            entry && decode(entry, agent_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            value = @view.atomic do |bound|
+              entry = bound.records(StorageSchema::ROOTS).read(agent_id.to_s)
+              entry && decode(entry, agent_id)
+            end
+            value || raise(Phronomy::Storage::NotFoundError, "Agent not found: #{agent_id}")
           end
-          value || raise(Phronomy::Storage::NotFoundError, "Agent not found: #{agent_id}")
         end
 
         def save(agent_id, expected_revision:, root:)
-          expected = Integer(expected_revision)
-          revision = Integer(root.agent_revision)
-          raise Phronomy::Storage::ConflictError, "root save must advance revision exactly once" unless revision == expected + 1
-          unless root.agent_id.to_s == agent_id.to_s
-            raise Phronomy::Storage::SerializationError, "Agent root identity mismatch"
-          end
-          record = Codec.encode_agent_root(root)
-          @view.atomic do |bound|
-            entry = bound.records(StorageSchema::ROOTS).replace(key: agent_id.to_s,
-              expected_revision: expected, next_revision: revision, attributes: {}, record: record)
-            decode(entry, agent_id, revision: revision)
+          Phronomy::Persistence::StorageBoundary.call do
+            expected = Integer(expected_revision)
+            revision = Integer(root.agent_revision)
+            raise Phronomy::Storage::ConflictError, "root save must advance revision exactly once" unless revision == expected + 1
+            unless root.agent_id.to_s == agent_id.to_s
+              raise Phronomy::Storage::SerializationError, "Agent root identity mismatch"
+            end
+            record = Codec.encode_agent_root(root)
+            @view.atomic do |bound|
+              entry = bound.records(StorageSchema::ROOTS).replace(key: agent_id.to_s,
+                expected_revision: expected, next_revision: revision, attributes: {}, record: record)
+              decode(entry, agent_id, revision: revision)
+            end
           end
         end
 
         def delete(agent_id)
-          @view.records(StorageSchema::ROOTS).delete(key: agent_id.to_s)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.records(StorageSchema::ROOTS).delete(key: agent_id.to_s)
+          end
         end
 
         private