phronomy 0.26.0 → 0.28.0

data/lib/phronomy/multi_agent/team_coordinator.rb

@@ -11,12 +11,27 @@ module Phronomy
     # Scheduling and aggregation must be pure, replay-safe result calculations.
     # @api public
     class TeamCoordinator
-      WorkerState = Data.define(:index, :agent_id, :transcript_size, :status) do
+      WorkerState = Data.define(:index, :agent_id, :assignment_count, :status) do
         def available? = status == :available
       end
       private_constant :WorkerState
 
+      # Raised before writing an operation; update still verifies readback.
+      OperationRejected = Class.new(Phronomy::ConfigurationError)
+      private_constant :OperationRejected
+
       class << self
+        # Boot composition supplies a fresh store without selecting it here.
+        # @api private
+        def install_persistence_factory(factory)
+          raise ArgumentError, "factory must respond to call" unless factory.respond_to?(:call)
+          raise Phronomy::ConfigurationError, "Team persistence factory already installed" if @persistence_factory
+          @persistence_factory = factory
+        end
+
+        # @api private
+        def build_default_persistence = @persistence_factory.call
+
         # @api public
         def team_definition(id: nil, version: nil)
           if id || version
@@ -68,7 +83,9 @@ module Phronomy
         end
 
         # @api public
-        def get(team_id) = Phronomy::Runtime.instance.__get_team(team_id, klass: self)
+        def get(team_id)
+          ExecutionEnvironment.current.existing_ownership&.get(team_id.to_s, klass: self)
+        end
 
         # @api private
         def _coordinator_model = @coordinator_model
@@ -90,14 +107,14 @@ module Phronomy
         private
 
         def construct(id, persistence, metadata, listener, create:)
-          raise Phronomy::EventLoopReentrancyError, "Team construction cannot block EventLoop" if Phronomy::Runtime.in_event_loop_context?
+          raise Phronomy::EventLoopReentrancyError, "Team construction cannot block EventLoop" if Phronomy::WaitPolicy.blocking_forbidden?
           key = id.to_s
           raise ArgumentError, "team_id must not be empty" if key.empty?
-          store = persistence || Phronomy.configuration.persistence || Phronomy::Persistence::InMemory.new
-          runtime = Phronomy::Runtime.instance
-          runtime.__team_owner(key, klass: self, create: create, persistence: store) do
+          store = persistence || Phronomy::MultiAgent::Store.configured || TeamCoordinator.build_default_persistence
+          environment = ExecutionEnvironment.current
+          environment.ownership.fetch(key, klass: self, create: create, persistence: store) do
             instance = allocate
-            instance.send(:initialize, key.freeze, store, metadata, listener, runtime, create: create)
+            instance.send(:initialize, key.freeze, store, metadata, listener, environment, create: create)
             instance
           end
         end
@@ -132,12 +149,12 @@ module Phronomy
       # @api public
       def result(team_execution_id)
         execution = read_execution(team_execution_id)
-        persistence.team_execution_result(execution.team_execution_id)
+        persistence.result(execution.team_execution_id)
       end
 
       # @api public
       def executions(after: nil, limit: 100)
-        persistence.list_team_executions(team_id, after: after, limit: limit)
+        persistence.runs(team_id, after: after, limit: limit)
       end
 
       # Requests cancellation of this run only. Existing Agent cancellation and
@@ -157,8 +174,9 @@ module Phronomy
 
       private
 
-      def initialize(id, store, metadata, listener, runtime, create:)
-        @team_id, @persistence, @listener, @runtime = id, store, listener, runtime
+      def initialize(id, store, metadata, listener, environment, create:)
+        @team_id, @persistence, @listener, @environment = id, store, listener, environment
+        @admissions = @environment.admissions
         @tokens_mutex, @tokens = Mutex.new, {}
         @coordinator_classes = {}
         definition = self.class.team_definition
@@ -181,25 +199,25 @@ module Phronomy
       end
 
       def assert_caller!
-        raise Phronomy::EventLoopReentrancyError, "Team operation cannot block EventLoop" if Phronomy::Runtime.in_event_loop_context?
-        unless @runtime.equal?(Phronomy::Runtime.instance)
+        raise Phronomy::EventLoopReentrancyError, "Team operation cannot block EventLoop" if Phronomy::WaitPolicy.blocking_forbidden?
+        unless @environment.current?
           raise Phronomy::RuntimeShutdownError, "Team #{team_id} belongs to a previous Runtime"
         end
       end
 
       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::Persistence::StateConflictError, "Team execution #{id} belongs to another Team"
         end
         execution
       end
@@ -218,13 +236,13 @@ module Phronomy
         now = Time.now.utc.iso8601(6)
         intended = nil
         begin
-          persistence.transaction do |tx|
+          persistence.transaction do |tx, scope|
             root = tx.teams.load(team_id)
             raise Phronomy::AgentBusyError, "Team #{team_id} has an active run; use resume" unless tx.team_executions.list_active(team_id).empty?
             intended = TeamExecution.new(team_execution_id: id, team_id: team_id,
               execution_revision: 0, status: "active", phase: "coordinator", input_ref: tx.contents.put_text(input),
               coordinator: {"agent_id" => SecureRandom.uuid, "execution_id" => SecureRandom.uuid, "state" => "reserved"},
-              workers: Array.new(self.class._pool_size) { |i| {"index" => i, "agent_id" => SecureRandom.uuid, "transcript_size" => 0} },
+              workers: Array.new(self.class._pool_size) { |i| {"index" => i, "agent_id" => SecureRandom.uuid} },
               tasks: [], assignments: [], result_ref: nil, error_ref: nil, created_at: now, updated_at: now,
               metadata: {"definition" => definition, "operations" => {}, "cancel_requested" => false,
                          "durable_context_ref" => config.key?(:durable_context) ? tx.contents.put_json(config.fetch(:durable_context)) : nil})
@@ -249,10 +267,10 @@ module Phronomy
         attempts = 0
         begin
           intended = nil
-          persistence.transaction do |tx|
+          persistence.transaction do |tx, scope|
             current = tx.team_executions.load(id)
-            raise Phronomy::Persistence::ConflictError, "Team execution owner mismatch" unless current.team_id == team_id
-            intended = yield(current, tx)
+            raise Phronomy::Persistence::StateConflictError, "Team execution owner mismatch" unless current.team_id == team_id
+            intended = yield(current, tx, scope)
             next if intended.equal?(current)
             tx.team_executions.save(id, expected_revision: current.execution_revision, execution: intended)
             if intended.terminal? && current.active?
@@ -279,9 +297,9 @@ module Phronomy
         end
         token = Phronomy::Concurrency::CancellationToken.new
         @tokens_mutex.synchronize { @tokens[id] = token }
-        external = config[:cancellation_token]
-        callback = proc { @runtime.offload.submit(on_full: :raise) { cancel(id) } }
-        external&.on_cancel(&callback)
+        cancellation_subscriptions = Phronomy::Concurrency::ResultSubscriptions.new
+        callback = proc { @environment.submit(on_full: :raise) { cancel(id) } }
+        cancellation_subscriptions.explicit_cancellation(config[:cancellation_token], &callback)
         token.cancel! if current.metadata["cancel_requested"]
         begin
           loop do
@@ -320,13 +338,13 @@ module Phronomy
             values = assignment_values(current)
             aggregate = self.class._aggregator
             begin
-              output = Phronomy::Agent::RecoverySupport.canonical_copy(aggregate ? aggregate.call(values) : values)
+              output = Phronomy::Values::Serializable.convert(aggregate ? aggregate.call(values) : values, unsupported_message: "Team result is not canonically serializable")
               Phronomy::CanonicalJSON.dump(output)
             rescue => error
-              return terminal_value(finish_error(id, Phronomy::Agent::RecoverySupport.resolution_failure(error)))
+              return terminal_value(finish_error(id, {"class" => error.class.name.to_s, "message" => error.message.to_s}))
             end
             # Aggregate may be replayed only until the canonical outcome commits.
-            completed = update(id) do |fresh, tx|
+            completed = update(id) do |fresh, tx, scope|
               next fresh if fresh.terminal? || fresh.metadata["cancel_requested"]
               fresh.with(status: "completed", phase: "completed", result_ref: tx.contents.put_json(output))
             end
@@ -342,7 +360,7 @@ module Phronomy
             terminal_value(finish_error(id, {"class" => "Phronomy::CancellationError", "message" => "Team run cancelled"}, status: "cancelled"))
           end
         ensure
-          external&.send(:unregister_cancel_callback, callback)
+          cancellation_subscriptions.close
           @tokens_mutex.synchronize { @tokens.delete(id) }
         end
       end
@@ -380,30 +398,31 @@ module Phronomy
         id = slot.fetch("agent_id")
         child = klass.get(id)
         unless child
-          begin
-            persistence.agents.load(id)
-            present = true
-          rescue Phronomy::Persistence::NotFoundError
-            present = false
-          end
+          present = persistence.agent_store.exist?(id)
           token.raise_if_cancelled! unless present
-          child = present ? klass.load(id, persistence: persistence, on_event: @listener) : klass.create(agent_id: id, persistence: persistence, on_event: @listener)
+          child = present ? klass.load(id, persistence: persistence.agent_store, on_event: @listener) : klass.create(agent_id: id, persistence: persistence.agent_store, on_event: @listener)
         end
-        unless child.persistence.equal?(persistence)
+        unless child.persistence.equal?(persistence.agent_store)
           raise Phronomy::ConfigurationError, "Team child #{id} Persistence mismatch"
         end
         child_config = config.merge(cancellation_token: token,
-          phronomy_coordination: {"kind" => "team", "team_id" => team_id,
-                                  "team_execution_id" => current.team_execution_id, "slot" => purpose})
+          phronomy_reservation: {"kind" => "team", "team_id" => team_id,
+                                 "team_execution_id" => current.team_execution_id, "slot" => purpose})
+        child_config = child_config.merge(phronomy_admission: ReservedChildAdmission.new(
+          persistence: persistence, owner: child_config.fetch(:phronomy_reservation)
+        ))
         if (context_ref = current.metadata["durable_context_ref"])
           child_config = child_config.merge(durable_context: persistence.contents.fetch_json(context_ref))
         end
-        Phronomy::Agent::ExactExecution.start(agent: child, execution_id: slot.fetch("execution_id"), input: input, config: child_config).wait_result
+        child.start_reserved_async(reservation: Phronomy::Agent::ReservedExecution.new(agent_id: id, execution_id: slot.fetch("execution_id"), correlation: child_config.fetch(:phronomy_reservation)), input: input, config: child_config).wait_result
       end
 
       def reserve_assignment(current, task)
-        available = current.workers.map { |w| WorkerState.new(index: w.fetch("index"), agent_id: w.fetch("agent_id"), transcript_size: w.fetch("transcript_size"), status: :available) }.freeze
-        worker = self.class._scheduler ? self.class._scheduler.call(available) : available.min_by(&:transcript_size)
+        # Team owns this count. Deriving it from retained assignments also
+        # makes replay idempotent and avoids consulting the child's journal.
+        counts = current.assignments.each_with_object(Hash.new(0)) { |entry, totals| totals[entry.fetch("worker")] += 1 }
+        available = current.workers.map { |w| WorkerState.new(index: w.fetch("index"), agent_id: w.fetch("agent_id"), assignment_count: counts[w.fetch("index")], status: :available) }.freeze
+        worker = self.class._scheduler ? self.class._scheduler.call(available) : available.min_by(&:assignment_count)
         raise Phronomy::ConfigurationError, "Scheduler must select an available worker slot" unless available.include?(worker)
         reserved = {"task_id" => task.fetch("id"), "worker" => worker.index,
                     "execution_id" => SecureRandom.uuid, "state" => "reserved", "result_ref" => nil, "error_ref" => nil}
@@ -414,20 +433,15 @@ module Phronomy
       end
 
       def record_assignment(id, assigned, outcome)
-        update(id) do |fresh, tx|
+        update(id) do |fresh, _tx|
           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::Persistence::StateConflictError, "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
-          workers = fresh.workers.map do |worker|
-            next worker unless worker.fetch("index") == assigned.fetch("worker")
-            root = tx.agents.load(worker.fetch("agent_id"))
-            worker.merge("transcript_size" => root.journal_position)
-          end
-          fresh.with(assignments: entries, workers: workers)
+          fresh.with(assignments: entries)
         end
       end
 
@@ -441,7 +455,7 @@ module Phronomy
       end
 
       def finish_error(id, error, status: "failed")
-        update(id) do |fresh, tx|
+        update(id) do |fresh, tx, scope|
           next fresh if fresh.terminal?
           fresh.with(status: status, phase: status, error_ref: tx.contents.put_json(error))
         end
@@ -449,7 +463,10 @@ module Phronomy
 
       def terminal_value(execution)
         raise Phronomy::CancellationError, "Team run #{execution.team_execution_id} cancelled" if execution.status == "cancelled"
-        raise Phronomy::Agent::RecoverySupport.error_from_failure(persistence.contents.fetch_json(execution.error_ref)) if execution.error_ref
+        if execution.error_ref
+          failure = persistence.contents.fetch_json(execution.error_ref)
+          raise Phronomy::Error, "#{failure.fetch("class")}: #{failure.fetch("message")}"
+        end
         persistence.contents.fetch_json(execution.result_ref)
       end
 
@@ -474,7 +491,7 @@ module Phronomy
 
       def build_operation_tool(run_id, operation)
         team = self
-        Class.new(Phronomy::Agent::Context::Capability::Base) do
+        Class.new(Phronomy::Tool::Base) do
           def self.__framework_owned_operation? = true
           tool_name operation.to_s
           description((operation == :enqueue_task) ? "Add a task to the worker queue." : "Finish task generation.")
@@ -483,10 +500,10 @@ 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)
+            validated, schema_error = validate_arguments(args)
             raise Phronomy::ToolError, schema_error if schema_error
             execute_async(**validated, cancellation_token: cancellation_token, config: config)
           rescue => error
@@ -494,8 +511,10 @@ module Phronomy
           end
           define_method(:execute_async) do |config: {}, cancellation_token: nil, **arguments|
             key = config.fetch(:phronomy_tool_invocation_id)
-            Phronomy::Runtime.instance.offload.submit(on_full: :raise) do
+            Phronomy::Execution.submit(on_full: :raise) do
               team.send(:apply_operation, run_id, key, operation, arguments)
+            rescue OperationRejected => error
+              raise Phronomy::ConfigurationError, error.message
             rescue Phronomy::CancellationError
               raise
             rescue => error
@@ -507,42 +526,35 @@ module Phronomy
       end
 
       def apply_operation(run_id, key, operation, arguments)
-        argument_values = Phronomy::Agent::RecoverySupport.canonical_copy(arguments)
-        current = update(run_id) do |fresh, tx|
+        argument_values = Phronomy::Values::Serializable.convert(arguments, unsupported_message: "Team arguments are not canonically serializable")
+        current = update(run_id) do |fresh, tx, scope|
           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::Persistence::StateConflictError, "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"
-          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"
-          end
-          batch = Array(coordinator.metadata[Phronomy::Agent::RecoverySupport::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"
-          end
+          raise Phronomy::Persistence::StateConflictError, "Team task generation is closed" unless fresh.active? && fresh.phase == "coordinator"
+          batch = persistence.agent_store.authorized_operations(scope,
+            agent_id: fresh.coordinator.fetch("agent_id"), execution_id: fresh.coordinator.fetch("execution_id"),
+            invocation_id: key, name: operation.to_s, arguments: argument_values, names: %w[enqueue_task finalize])
           # All calls passed the Agent authorization barrier. Commit this finite
           # batch in Provider order, so finalize cannot overtake queued tasks.
           tasks = fresh.tasks.dup
           operations = operations.dup
           metadata = fresh.metadata.dup
           batch.each do |entry|
-            entry_id = entry.fetch("tool_invocation_id")
-            next if operations.key?(entry_id) || entry.fetch("status") != "authorized"
-            name = entry.fetch("tool_name")
-            next unless %w[enqueue_task finalize].include?(name)
-            values = entry.fetch("arguments").compact
+            entry_id = entry.invocation_id
+            next if operations.key?(entry_id)
+            name = entry.name
+            values = entry.arguments
             if name == "enqueue_task"
-              raise Phronomy::ConfigurationError, "Cannot enqueue after finalize" if metadata["finalized"]
+              raise OperationRejected, "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,8 +1,8 @@
 # frozen_string_literal: true
 
 module Phronomy
-  class Runtime
-    # Runtime-local Team identity and construction exclusion; no execution state.
+  module MultiAgent
+    # Environment-local Team identity and construction exclusion; no execution state.
     # @api private
     class TeamOwnershipRegistry
       def initialize
@@ -18,7 +18,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::Persistence::StateConflictError, "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 +58,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 +69,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/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/content_repository.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Persistence
+    # Domain-facing content access uses the Persistence failure vocabulary.
+    # ContentStore implementations retain their independent backend contract.
+    # @api private
+    class ContentRepository < Phronomy::ContentStore::Base
+      def initialize(store)
+        @store = store
+      end
+
+      def put(bytes, canonicalization_version:)
+        StorageBoundary.call { @store.put(bytes, canonicalization_version: canonicalization_version) }
+      end
+
+      def fetch(content_id)
+        StorageBoundary.call { @store.fetch(content_id) }
+      end
+
+      def exist?(content_id)
+        StorageBoundary.call { @store.exist?(content_id) }
+      end
+    end
+  end
+end

data/lib/phronomy/persistence/errors.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class Persistence
+    # Failures describe a category, not a universal claim about commit outcome.
+    class Error < Phronomy::Error; end
+    class ConflictError < Error; end
+    class StateConflictError < ConflictError; end
+    class NotFoundError < Error; end
+    class SerializationError < Error; end
+    class UnsupportedBackendError < Error; end
+    class TransactionError < Error; 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
+          source["version"] = Phronomy::Context::LLMInputManifest::VERSION
+          Phronomy::Context::LLMInputManifest.from_h(source).to_h
+        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/persistence.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Domain-neutral transaction ownership and participation. Domain operations
+  # choose their atomic boundary; composition supplies their storage adapters.
+  # @api public
+  class Persistence
+    attr_reader :backend
+
+    def initialize(backend:)
+      StorageBoundary.call { Storage::Backend.validate_capabilities!(backend) }
+      @backend = backend
+    end
+
+    # Bind an injected adapter for ordinary synchronous reads/standalone writes.
+    # Only that adapter receives Storage's raw view. Multi-operation changes use
+    # atomic/Transaction#participate so all participants use the exact same view.
+    # @api private
+    def bind(adapter)
+      StorageBoundary.call { adapter.new(backend.view) }
+    end
+  end
+end