phronomy 0.26.0 → 0.27.0

data/lib/phronomy/multi_agent/team_coordinator.rb

@@ -68,7 +68,9 @@ module Phronomy
         end
 
         # @api public
-        def get(team_id) = Phronomy::Runtime.instance.__get_team(team_id, klass: self)
+        def get(team_id)
+          TeamOwnershipRegistry.existing_for(Phronomy::Runtime.instance)&.get(team_id.to_s, klass: self)
+        end
 
         # @api private
         def _coordinator_model = @coordinator_model
@@ -93,9 +95,9 @@ module Phronomy
           raise Phronomy::EventLoopReentrancyError, "Team construction cannot block EventLoop" if Phronomy::Runtime.in_event_loop_context?
           key = id.to_s
           raise ArgumentError, "team_id must not be empty" if key.empty?
-          store = persistence || Phronomy.configuration.persistence || Phronomy::Persistence::InMemory.new
+          store = persistence || Phronomy.configuration.persistence || Phronomy::Persistence.in_memory
           runtime = Phronomy::Runtime.instance
-          runtime.__team_owner(key, klass: self, create: create, persistence: store) do
+          TeamOwnershipRegistry.for(runtime).fetch(key, klass: self, create: create, persistence: store) do
             instance = allocate
             instance.send(:initialize, key.freeze, store, metadata, listener, runtime, create: create)
             instance
@@ -159,6 +161,7 @@ module Phronomy
 
       def initialize(id, store, metadata, listener, runtime, create:)
         @team_id, @persistence, @listener, @runtime = id, store, listener, runtime
+        @admissions = AdmissionRegistry.for(@runtime)
         @tokens_mutex, @tokens = Mutex.new, {}
         @coordinator_classes = {}
         definition = self.class.team_definition
@@ -189,17 +192,17 @@ module Phronomy
 
       def with_admission
         assert_caller!
-        @runtime.__admit_multi_agent(self)
+        @admissions.admit!(self)
         admitted = true
         yield
       ensure
-        @runtime.__release_multi_agent(self) if admitted
+        @admissions.release!(self) if admitted
       end
 
       def read_execution(id)
         execution = persistence.team_executions.load(id)
         unless execution.team_id == team_id
-          raise Phronomy::Persistence::ConflictError, "Team execution #{id} belongs to another Team"
+          raise Phronomy::Storage::ConflictError, "Team execution #{id} belongs to another Team"
         end
         execution
       end
@@ -235,7 +238,7 @@ module Phronomy
           raise error unless intended
           begin
             confirmed = read_execution(id)
-          rescue Phronomy::Persistence::NotFoundError
+          rescue Phronomy::Storage::NotFoundError
             raise error
           end
           raise error unless confirmed.to_h == intended.to_h
@@ -251,7 +254,7 @@ module Phronomy
           intended = nil
           persistence.transaction do |tx|
             current = tx.team_executions.load(id)
-            raise Phronomy::Persistence::ConflictError, "Team execution owner mismatch" unless current.team_id == team_id
+            raise Phronomy::Storage::ConflictError, "Team execution owner mismatch" unless current.team_id == team_id
             intended = yield(current, tx)
             next if intended.equal?(current)
             tx.team_executions.save(id, expected_revision: current.execution_revision, execution: intended)
@@ -264,7 +267,7 @@ module Phronomy
         rescue => error
           confirmed = read_execution(id)
           return confirmed if intended && confirmed.to_h == intended.to_h
-          if error.is_a?(Phronomy::Persistence::ConflictError) && (attempts += 1) < 8
+          if error.is_a?(Phronomy::Storage::ConflictError) && (attempts += 1) < 8
             retry
           end
           raise error
@@ -383,7 +386,7 @@ module Phronomy
           begin
             persistence.agents.load(id)
             present = true
-          rescue Phronomy::Persistence::NotFoundError
+          rescue Phronomy::Storage::NotFoundError
             present = false
           end
           token.raise_if_cancelled! unless present
@@ -418,7 +421,7 @@ module Phronomy
           entries = fresh.assignments.map do |entry|
             next entry unless entry.fetch("task_id") == assigned.fetch("task_id")
             next entry unless entry.fetch("state") == "reserved"
-            raise Phronomy::Persistence::ConflictError, "Assignment execution changed" unless entry.fetch("execution_id") == outcome.fetch(:execution_id)
+            raise Phronomy::Storage::ConflictError, "Assignment execution changed" unless entry.fetch("execution_id") == outcome.fetch(:execution_id)
             entry.merge("state" => outcome.fetch(:status).to_s,
               "result_ref" => outcome[:result_ref], "error_ref" => outcome[:error_ref])
           end
@@ -483,7 +486,7 @@ module Phronomy
             param :description, type: :string, desc: "Worker task"
             param :metadata, type: :string, desc: "Optional metadata", required: false
           else
-            param :summary, type: :string, desc: "TaskResult summary", required: false
+            param :summary, type: :string, desc: "Task generation summary", required: false
           end
           define_method(:call_async) do |args, cancellation_token: nil, config: {}|
             validated, schema_error = send(:validate_and_coerce, args)
@@ -512,20 +515,20 @@ module Phronomy
           operations = fresh.metadata.fetch("operations")
           if (prior = operations[key])
             unless prior.fetch("operation") == operation.to_s && prior.fetch("arguments") == argument_values
-              raise Phronomy::Persistence::ConflictError, "Team operation #{key} identity mismatch"
+              raise Phronomy::Storage::ConflictError, "Team operation #{key} identity mismatch"
             end
             next fresh
           end
           raise Phronomy::CancellationError, "Team run cancelled" if fresh.metadata["cancel_requested"]
-          raise Phronomy::Persistence::ConflictError, "Team task generation is closed" unless fresh.active? && fresh.phase == "coordinator"
+          raise Phronomy::Storage::ConflictError, "Team task generation is closed" unless fresh.active? && fresh.phase == "coordinator"
           coordinator = tx.executions.load(fresh.coordinator.fetch("execution_id"))
           unless coordinator.agent_id == fresh.coordinator.fetch("agent_id")
-            raise Phronomy::Persistence::ConflictError, "Team coordinator owner mismatch"
+            raise Phronomy::Storage::ConflictError, "Team coordinator owner mismatch"
           end
-          batch = Array(coordinator.metadata[Phronomy::Agent::RecoverySupport::TOOL_BATCH_METADATA_KEY])
+          batch = Array(coordinator.metadata[Phronomy::Agent::ExecutionMetadata::TOOL_BATCH_METADATA_KEY])
           requested = batch.find { |entry| entry.fetch("tool_invocation_id") == key }
           unless requested && requested.fetch("status") == "authorized" && requested.fetch("tool_name") == operation.to_s && requested.fetch("arguments").compact == argument_values
-            raise Phronomy::Persistence::ConflictError, "Team operation #{key} is not the authorized call"
+            raise Phronomy::Storage::ConflictError, "Team operation #{key} is not the authorized call"
           end
           # All calls passed the Agent authorization barrier. Commit this finite
           # batch in Provider order, so finalize cannot overtake queued tasks.
@@ -542,7 +545,7 @@ module Phronomy
               raise Phronomy::ConfigurationError, "Cannot enqueue after finalize" if metadata["finalized"]
               task = {"id" => Digest::SHA256.hexdigest(entry_id)[0, 32], "description" => values.fetch("description"), "metadata" => values["metadata"]}
               tasks << task
-              output = "TaskResult ##{tasks.length} enqueued: #{task.fetch("description")}"
+              output = "Task ##{tasks.length} enqueued: #{task.fetch("description")}"
             else
               output = "Finalized. #{tasks.size} task(s) enqueued. #{values["summary"]}".strip
               metadata["finalized"] = true

data/lib/phronomy/multi_agent/team_execution.rb

@@ -14,7 +14,7 @@ module Phronomy
         source = values.transform_keys(&:to_s)
         raise ArgumentError, "TeamExecution schema mismatch" unless source.keys.sort == ATTRIBUTES.sort
         canonical = Phronomy::CanonicalJSON.load(Phronomy::CanonicalJSON.dump(source))
-        ATTRIBUTES.each { |key| instance_variable_set("@#{key}", Phronomy::Agent::Immutable.copy(canonical.fetch(key))) }
+        ATTRIBUTES.each { |key| instance_variable_set("@#{key}", Phronomy::Values::Immutable.copy(canonical.fetch(key))) }
         raise ArgumentError, "missing team_execution_id" if team_execution_id.to_s.empty?
         raise ArgumentError, "invalid execution_revision" unless execution_revision.is_a?(Integer) && execution_revision >= 0
         raise ArgumentError, "invalid metadata" unless metadata.is_a?(Hash)

data/lib/phronomy/{engine/runtime → multi_agent}/team_ownership_registry.rb

@@ -1,10 +1,20 @@
 # frozen_string_literal: true
 
 module Phronomy
-  class Runtime
+  module MultiAgent
     # Runtime-local Team identity and construction exclusion; no execution state.
     # @api private
     class TeamOwnershipRegistry
+      def self.for(runtime)
+        existing_for(runtime) || runtime.__register_shutdown_participant(
+          key: self, participant: new
+        )
+      end
+
+      def self.existing_for(runtime)
+        runtime.__shutdown_participant(key: self)
+      end
+
       def initialize
         @mutex = Mutex.new
         @condition = ConditionVariable.new
@@ -18,7 +28,7 @@ module Phronomy
           loop do
             raise Phronomy::RuntimeShutdownError, "Runtime is draining" if @draining
             if (owner = @owners[id])
-              raise Phronomy::Persistence::ConflictError, "Team #{id} already exists" if create
+              raise Phronomy::Storage::ConflictError, "Team #{id} already exists" if create
               unless owner.is_a?(klass) && owner.persistence.equal?(persistence)
                 raise Phronomy::ConfigurationError, "Team #{id} owner or Persistence mismatch"
               end
@@ -58,7 +68,7 @@ module Phronomy
         end
       end
 
-      def wait_until_stable(deadline)
+      def wait_until_idle(deadline)
         @mutex.synchronize do
           until @constructing.empty?
             remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -69,7 +79,7 @@ module Phronomy
         end
       end
 
-      def shutdown!
+      def after_runtime_shutdown
         @mutex.synchronize { @owners.clear }
       end
     end

data/lib/phronomy/multi_agent/team_root.rb

@@ -14,7 +14,7 @@ module Phronomy
         source = values.transform_keys(&:to_s)
         raise ArgumentError, "TeamRoot schema mismatch" unless source.keys.sort == ATTRIBUTES.sort
         canonical = Phronomy::CanonicalJSON.load(Phronomy::CanonicalJSON.dump(source))
-        ATTRIBUTES.each { |key| instance_variable_set("@#{key}", Phronomy::Agent::Immutable.copy(canonical.fetch(key))) }
+        ATTRIBUTES.each { |key| instance_variable_set("@#{key}", Phronomy::Values::Immutable.copy(canonical.fetch(key))) }
         raise ArgumentError, "missing team_id" if team_id.to_s.empty?
         raise ArgumentError, "invalid team_revision" unless team_revision.is_a?(Integer) && team_revision >= 0
         raise ArgumentError, "invalid metadata" unless metadata.is_a?(Hash)

data/lib/phronomy/output_parser/contract/parse_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../../common/error"
+
+module Phronomy
+  class ParseError < Error; end
+end

data/lib/phronomy/persistence/api/persistence.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Persistence
+    # Content-addressed immutable content repository. ContentStore has its own
+    # codec/canonicalization boundary and is not wrapped in DurableRecord.
+    #
+    # @return [Object]
+    # @api public
+    def contents = @repositories.contents
+
+    # Runtime/domain-facing AgentRoot repository. The injected backend is
+    # record-oriented; this facade owns encode/decode.
+    #
+    # @return [Object]
+    # @api public
+    def agents = @repositories.agents
+
+    # Runtime/domain-facing append-only Agent Journal repository.
+    #
+    # @return [Object]
+    # @api public
+    def journals = @repositories.journals
+
+    # Runtime/domain-facing AgentExecution repository.
+    #
+    # @return [Object]
+    # @api public
+    def executions = @repositories.executions
+
+    # Runtime/domain-facing durable Workflow snapshot repository.
+    #
+    # @return [Object]
+    # @api public
+    def workflow_states = @repositories.workflow_states
+
+    # Purpose-specific durable Handoff and Team repositories in atomic_all.
+    # @api public
+    def handoff_states = @repositories.handoff_states
+
+    # @api public
+    def teams = @repositories.teams
+
+    # @api public
+    def team_executions = @repositories.team_executions
+
+    # Read-only exact Agent execution result; never creates a live Agent owner.
+    # Result is nil until a result_ref exists; errors remain canonical data.
+    # @api public
+    def execution_result(execution_id)
+      assert_observation_thread!
+      Phronomy::Agent::Persistence::Queries.new(self).execution_result(execution_id)
+    end
+
+    # Follows one exact Handoff turn without constructing a live Agent or graph.
+    # A committed absent Target reservation remains active; failed reads raise.
+    # @api public
+    def handoff_result(execution_id, main_agent_id: nil)
+      assert_observation_thread!
+      Phronomy::Agent::Persistence::Queries.new(self).handoff_result(execution_id, main_agent_id: main_agent_id)
+    end
+
+    # Lists retained active and terminal executions in lexical ID order.
+    # after is an exclusive ID cursor; discovery does not imply request dedup.
+    # @api public
+    def list_executions(agent_id, after: nil, limit: 100)
+      assert_observation_thread!
+      Phronomy::Agent::Persistence::Queries.new(self).list_executions(agent_id, after: after, limit: limit)
+    end
+
+    # Read-only exact Team result, independent of current Team class/Proc wiring.
+    # @api public
+    def team_execution_result(team_execution_id)
+      assert_observation_thread!
+      Phronomy::MultiAgent::Persistence::Queries.new(self).team_execution_result(team_execution_id)
+    end
+
+    # Lists retained Team runs; no continuation or callback delivery occurs.
+    # @api public
+    def list_team_executions(team_id, after: nil, limit: 100)
+      assert_observation_thread!
+      Phronomy::MultiAgent::Persistence::Queries.new(self).list_team_executions(team_id, after: after, limit: limit)
+    end
+
+    # The selected raw storage backend, for backend-specific administration.
+    # Read and write domain records through the repository accessors above.
+    # @api public
+    attr_reader :backend
+
+    # Assembles domain repositories over one synchronous storage backend.
+    # @api public
+    def initialize(backend:)
+      Phronomy::Storage::Backend.validate_capabilities!(backend)
+      PersistenceComposition::StorageSchema.validate!(backend.view)
+      @backend = backend
+      @repositories = PersistenceComposition::Repositories.new(backend.view)
+    end
+
+    # Constructs an isolated in-memory storage domain with standard codecs.
+    # @api public
+    def self.in_memory
+      new(backend: Phronomy::Storage::Backends::InMemory.new(resources: PersistenceComposition::StorageSchema.resources))
+    end
+
+    # @api public
+    def capabilities = {atomic_all: true, atomic_admission: true, optimistic_revision: true}.freeze
+
+    # Executes a single backend transaction and exposes domain repositories
+    # bound to its raw view. Codec and caller failures remain inside the backend
+    # block so the backend can roll them back. The block result is returned.
+    # Explicit nested calls on this service use savepoint semantics: a failed
+    # inner scope rolls back and re-raises; a successful inner scope is committed
+    # only with its outer scope. See Storage::Backend#transaction.
+    # Storage failures whose commit outcome is fundamentally
+    # unknown remain backend/database failures; Phronomy does not claim
+    # exactly-once semantics for such failures.
+    # @api public
+    def transaction
+      backend.transaction do |raw_view|
+        repositories = PersistenceComposition::Repositories.new(raw_view)
+        yield repositories
+      end
+    end
+
+    # @api public
+    def assert_agent_watermark!(agent_id:, agent_revision:, journal_position:)
+      @repositories.assert_agent_watermark!(
+        agent_id: agent_id, agent_revision: agent_revision, journal_position: journal_position
+      )
+    end
+
+    private
+
+    def assert_observation_thread!
+      if Phronomy::Runtime.in_event_loop_context?
+        raise Phronomy::EventLoopReentrancyError, "Persistence observation cannot block EventLoop"
+      end
+    end
+  end
+end

data/lib/phronomy/persistence/migration/initial_format_migration.rb

@@ -32,10 +32,10 @@ module Phronomy
             PRE_S3_AGENT_ROOT_KEYS,
             label: "pre-S3 AgentRoot"
           )
-          DurableCodec.encode_agent_root(
+          Phronomy::Agent::Persistence::Codec.encode_agent_root(
             Phronomy::Agent::AgentRoot.from_h(source)
           )
-        rescue Phronomy::Persistence::SerializationError
+        rescue Phronomy::Storage::SerializationError
           raise
         rescue => error
           migration_error("AgentRoot", error)
@@ -68,8 +68,8 @@ module Phronomy
             execution_id: source.fetch("execution_id")
           )
           execution = Phronomy::Agent::AgentExecution.from_h(source)
-          DurableCodec.encode_agent_execution(execution)
-        rescue Phronomy::Persistence::SerializationError
+          Phronomy::Agent::Persistence::Codec.encode_agent_execution(execution)
+        rescue Phronomy::Storage::SerializationError
           raise
         rescue => error
           migration_error("AgentExecution", error)
@@ -77,40 +77,40 @@ module Phronomy
 
         def journal_record(hash)
           source = normalize_legacy_journal_record(hash, label: "pre-S3 JournalRecord")
-          DurableCodec.encode_journal_record(
+          Phronomy::Agent::Persistence::Codec.encode_journal_record(
             Phronomy::Agent::JournalRecord.from_h(source)
           )
-        rescue Phronomy::Persistence::SerializationError
+        rescue Phronomy::Storage::SerializationError
           raise
         rescue => error
           migration_error("JournalRecord", error)
         end
 
         def workflow_state(workflow_instance_id:, revision:, snapshot:)
-          DurableCodec.encode_workflow_state(
+          Phronomy::Workflow::Persistence::Codec.encode_workflow_state(
             workflow_instance_id: workflow_instance_id,
             workflow_revision: Integer(revision),
             snapshot: snapshot
           )
-        rescue Phronomy::Persistence::SerializationError
+        rescue Phronomy::Storage::SerializationError
           raise
         rescue => error
           migration_error("Workflow state", error)
         end
 
         # LLMInputManifest is a ContentStore codec boundary, not a
-        # Persistence::DurableRecord. Its pre-CG-07 integer version 1 is migrated
+        # Storage::DurableRecord. Its pre-CG-07 integer version 1 is migrated
         # explicitly to the pre-1.0 string version "0.1".
         def llm_input_manifest(hash)
           source = stringify_keys(hash)
           old_version = source.fetch("version")
           unless old_version == 1 || old_version == "1"
-            raise Phronomy::Persistence::SerializationError,
+            raise Phronomy::Storage::SerializationError,
               "unsupported pre-S3 LLMInputManifest version: #{old_version.inspect}"
           end
           source["version"] = Phronomy::Agent::LLMInputManifest::VERSION
           Phronomy::Agent::LLMInputManifest.from_h(source).to_h
-        rescue Phronomy::Persistence::SerializationError
+        rescue Phronomy::Storage::SerializationError
           raise
         rescue => error
           migration_error("LLMInputManifest", error)
@@ -141,13 +141,13 @@ module Phronomy
           )
           parents = PRE_S3_APPROVAL_PARENT_KEYS.select { |key| source.key?(key) }
           unless parents.length == 1
-            raise Phronomy::Persistence::SerializationError,
+            raise Phronomy::Storage::SerializationError,
               "pre-S3 approval_request must contain exactly one parent identity, got #{parents.inspect}"
           end
 
           items = source.fetch("items")
           unless items.is_a?(Array) && !items.empty?
-            raise Phronomy::Persistence::SerializationError,
+            raise Phronomy::Storage::SerializationError,
               "pre-S3 approval_request items must be a non-empty Array"
           end
           source["items"] = items.map.with_index do |item, index|
@@ -164,7 +164,7 @@ module Phronomy
             source.delete("agent_invocation_id")
             source["execution_id"] = execution_id.to_s
           elsif source.fetch("execution_id").to_s != execution_id.to_s
-            raise Phronomy::Persistence::SerializationError,
+            raise Phronomy::Storage::SerializationError,
               "pre-S3 approval_request execution_id does not match AgentExecution"
           end
           source
@@ -180,7 +180,7 @@ module Phronomy
           details = []
           details << "missing=#{missing.inspect}" unless missing.empty?
           details << "unknown=#{unknown.inspect}" unless unknown.empty?
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "#{label} schema mismatch (#{details.join(", ")})"
         end
         private_class_method :validate_allowed_keys!
@@ -197,17 +197,17 @@ module Phronomy
 
         def stringify_keys(hash)
           unless hash.is_a?(Hash)
-            raise Phronomy::Persistence::SerializationError,
+            raise Phronomy::Storage::SerializationError,
               "migration input must be a Hash"
           end
           hash.each_with_object({}) do |(key, value), result|
             unless key.is_a?(String) || key.is_a?(Symbol)
-              raise Phronomy::Persistence::SerializationError,
+              raise Phronomy::Storage::SerializationError,
                 "migration key must be String or Symbol, got #{key.class}"
             end
             string_key = key.to_s
             if result.key?(string_key)
-              raise Phronomy::Persistence::SerializationError,
+              raise Phronomy::Storage::SerializationError,
                 "duplicate migration key after normalization: #{string_key.inspect}"
             end
             result[string_key] = value
@@ -216,7 +216,7 @@ module Phronomy
         private_class_method :stringify_keys
 
         def migration_error(label, error)
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "cannot migrate pre-S3 #{label}: #{error.class}: #{error.message}"
         end
         private_class_method :migration_error

data/lib/phronomy/persistence_composition/repositories.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module PersistenceComposition
+    # Assemble domain repositories over one raw backend or transaction view.
+    # @api private
+    class Repositories
+      attr_reader :contents
+
+      def initialize(view)
+        @view = view
+        @contents = Phronomy::ContentStore::StoredContents.new(view)
+        @domain_repositories = {}
+        @repository_lock = Mutex.new
+      end
+
+      def agents
+        domain_repository(:agents) do
+          Phronomy::Agent::Persistence::AgentRepository.new(@view)
+        end
+      end
+
+      def journals
+        domain_repository(:journals) do
+          Phronomy::Agent::Persistence::JournalRepository.new(@view)
+        end
+      end
+
+      def executions
+        domain_repository(:executions) do
+          Phronomy::Agent::Persistence::ExecutionRepository.new(@view)
+        end
+      end
+
+      def workflow_states
+        domain_repository(:workflow_states) do
+          Phronomy::Workflow::Persistence::StateRepository.new(@view)
+        end
+      end
+
+      def handoff_states
+        domain_repository(:handoff_states) do
+          Phronomy::Agent::Persistence::HandoffStateRepository.new(@view)
+        end
+      end
+
+      def teams
+        domain_repository(:teams) do
+          Phronomy::MultiAgent::Persistence::TeamRepository.new(@view)
+        end
+      end
+
+      def team_executions
+        domain_repository(:team_executions) do
+          Phronomy::MultiAgent::Persistence::TeamExecutionRepository.new(@view)
+        end
+      end
+
+      def assert_agent_watermark!(agent_id:, agent_revision:, journal_position:)
+        Phronomy::Agent::Persistence::Watermark.new(@view).check!(
+          agent_id: agent_id.to_s,
+          agent_revision: Integer(agent_revision),
+          journal_position: Integer(journal_position)
+        )
+      end
+
+      private
+
+      # Cache one wrapper per view without loading unused domain implementations.
+      def domain_repository(name)
+        @repository_lock.synchronize do
+          @domain_repositories.fetch(name) { @domain_repositories[name] = yield }
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/persistence_composition/storage_schema.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module PersistenceComposition
+    # One composition catalog, supplied to a neutral storage driver.
+    # @api private
+    module StorageSchema
+      def self.validate!(view)
+        resources.each { |resource| view.public_send(resource.kind, resource) }
+      end
+
+      def self.resources
+        [Agent::Persistence::StorageSchema::ROOTS,
+          Agent::Persistence::StorageSchema::EXECUTIONS,
+          Agent::Persistence::StorageSchema::JOURNAL,
+          Agent::Persistence::StorageSchema::HANDOFF_STATES,
+          TeamStorageSchema::ROOTS,
+          TeamStorageSchema::EXECUTIONS,
+          WorkflowStorageSchema::STATES,
+          ContentStore::StorageSchema::CONTENTS].freeze
+      end
+    end
+  end
+end

data/lib/phronomy/{execution_rehydration_required_error.rb → recovery/execution_rehydration_required_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../common/error"
+
 module Phronomy
   class ExecutionRehydrationRequiredError < Phronomy::Error; end
 end

data/lib/phronomy/{recovery.rb → recovery/recovery.rb}

@@ -36,7 +36,7 @@ module Phronomy
           reason: reason.to_sym,
           subject: subject && Phronomy::Recovery.normalize_subject(subject),
           allowed_outcomes: Array(allowed_outcomes).map(&:to_sym).freeze,
-          facts: Phronomy::Agent::Immutable.copy(facts || {})
+          facts: Phronomy::Values::Immutable.copy(facts || {})
         )
       end
     end

data/lib/phronomy/runtime_composition/agent_defaults.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Select the Agent default at the application composition boundary. Binding
+# does not create Persistence, global configuration, or a Runtime.
+Phronomy::Agent::DefaultPersistence.install_factory(
+  -> { Phronomy::Persistence.in_memory }
+)

data/lib/phronomy/runtime_composition/configuration_defaults.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Select concrete defaults at the application composition boundary. Each factory
+# runs during Configuration.new, not during binding; no Runtime is started here.
+# Explicitly loaded after Zeitwerk setup and before global configuration access.
+Phronomy::Configuration.install_default_factories(
+  tracer: -> { Phronomy::Tracing::NullTracer.new },
+  llm_adapter: -> { Phronomy::LLMAdapter::RubyLLM.new }
+)

data/lib/phronomy/runtime_composition/global_runtime.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Application lifecycle coordination across Runtime and global configuration.
+# Explicitly loaded by the application entry point; not an Engine primitive.
+module Phronomy
+  class << self
+    def reset_runtime!(timeout: configuration.event_loop_stop_grace_seconds)
+      previous_grace = @configuration&.event_loop_stop_grace_seconds
+      result = Runtime.reset_default!(timeout: timeout)
+
+      new_configuration = Configuration.new
+      if previous_grace
+        new_configuration.event_loop_stop_grace_seconds = previous_grace
+      end
+      @configuration = new_configuration
+      result
+    end
+  end
+end