phronomy 0.27.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
@@ -69,7 +84,7 @@ module Phronomy
 
         # @api public
         def get(team_id)
-          TeamOwnershipRegistry.existing_for(Phronomy::Runtime.instance)&.get(team_id.to_s, klass: self)
+          ExecutionEnvironment.current.existing_ownership&.get(team_id.to_s, klass: self)
         end
 
         # @api private
@@ -92,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.in_memory
-          runtime = Phronomy::Runtime.instance
-          TeamOwnershipRegistry.for(runtime).fetch(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
@@ -134,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
@@ -159,9 +174,9 @@ module Phronomy
 
       private
 
-      def initialize(id, store, metadata, listener, runtime, create:)
-        @team_id, @persistence, @listener, @runtime = id, store, listener, runtime
-        @admissions = AdmissionRegistry.for(@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
@@ -184,8 +199,8 @@ 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
@@ -202,7 +217,7 @@ module Phronomy
       def read_execution(id)
         execution = persistence.team_executions.load(id)
         unless execution.team_id == team_id
-          raise Phronomy::Storage::ConflictError, "Team execution #{id} belongs to another Team"
+          raise Phronomy::Persistence::StateConflictError, "Team execution #{id} belongs to another Team"
         end
         execution
       end
@@ -221,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})
@@ -238,7 +253,7 @@ module Phronomy
           raise error unless intended
           begin
             confirmed = read_execution(id)
-          rescue Phronomy::Storage::NotFoundError
+          rescue Phronomy::Persistence::NotFoundError
             raise error
           end
           raise error unless confirmed.to_h == intended.to_h
@@ -252,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::Storage::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?
@@ -267,7 +282,7 @@ module Phronomy
         rescue => error
           confirmed = read_execution(id)
           return confirmed if intended && confirmed.to_h == intended.to_h
-          if error.is_a?(Phronomy::Storage::ConflictError) && (attempts += 1) < 8
+          if error.is_a?(Phronomy::Persistence::ConflictError) && (attempts += 1) < 8
             retry
           end
           raise error
@@ -282,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
@@ -323,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
@@ -345,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
@@ -383,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::Storage::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}
@@ -417,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::Storage::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
 
@@ -444,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
@@ -452,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
 
@@ -477,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.")
@@ -489,7 +503,7 @@ module Phronomy
             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
@@ -497,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
@@ -510,39 +526,32 @@ 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::Storage::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::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::Storage::ConflictError, "Team coordinator owner mismatch"
-          end
-          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::Storage::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 = "Task ##{tasks.length} enqueued: #{task.fetch("description")}"

data/lib/phronomy/multi_agent/team_ownership_registry.rb

@@ -2,19 +2,9 @@
 
 module Phronomy
   module MultiAgent
-    # Runtime-local Team identity and construction exclusion; no execution state.
+    # Environment-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
@@ -28,7 +18,7 @@ module Phronomy
           loop do
             raise Phronomy::RuntimeShutdownError, "Runtime is draining" if @draining
             if (owner = @owners[id])
-              raise Phronomy::Storage::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

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

@@ -108,8 +108,8 @@ module Phronomy
             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
+          source["version"] = Phronomy::Context::LLMInputManifest::VERSION
+          Phronomy::Context::LLMInputManifest.from_h(source).to_h
         rescue Phronomy::Storage::SerializationError
           raise
         rescue => 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

data/lib/phronomy/persistence/save_outcome.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Persistence
+    # Classifies evidence supplied by the owning domains. No retry, callback,
+    # ownership release or external operation is performed here.
+    # @api public
+    SaveOutcome = Data.define(:disposition, :original_error, :read_error) do
+      def self.compare(before:, after:, original_error: nil)
+        current = yield
+        disposition = if current == after
+          :committed
+        elsif current == before
+          :not_committed
+        else
+          :unknown
+        end
+        new(disposition: disposition, original_error: original_error, read_error: nil)
+      rescue => error
+        new(disposition: :unknown, original_error: original_error, read_error: error)
+      end
+    end
+  end
+end

data/lib/phronomy/persistence/snapshot_comparison.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Persistence
+    # Compares revision and snapshot evidence supplied by the owning domain.
+    # Does not load, save, retry, resolve external operations or decide resumption.
+    # @api private
+    module SnapshotComparison
+      module_function
+
+      # Compare authoritative current state with a known pre/post revision pair.
+      # This is deliberately small: callers still validate entity-specific content.
+      def compare_revisions(current_revision:, expected_pre_revision:, intended_post_revision:)
+        current = current_revision
+        return :post_state if current == intended_post_revision
+        return :pre_state if current == expected_pre_revision
+
+        :conflict
+      end
+
+      # Evidence comparison for revisioned snapshot repositories.
+      # Some repositories return a newly allocated revision only after save, so
+      # callers may not know the intended post revision in advance. In that case
+      # the intended snapshot plus a revision different from the expected pre
+      # revision identifies the post-state.
+      def compare_revisioned_snapshot(
+        record:,
+        expected_pre_revision:,
+        intended_snapshot:,
+        intended_post_revision: nil
+      )
+        return :pre_state if record.nil? && expected_pre_revision.nil?
+        return :conflict if record.nil?
+
+        revision = fetch_value(record, :revision)
+        snapshot = fetch_value(record, :snapshot)
+        normalized_snapshot = normalize_value(snapshot)
+        normalized_intended = normalize_value(intended_snapshot)
+
+        if intended_post_revision
+          if revision == intended_post_revision &&
+              normalized_snapshot == normalized_intended
+            return :post_state
+          end
+        elsif normalized_snapshot == normalized_intended &&
+            revision != expected_pre_revision
+          return :post_state
+        end
+
+        return :pre_state if revision == expected_pre_revision
+
+        :conflict
+      end
+
+      def normalize_value(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, child), result|
+            result[key.to_s] = normalize_value(child)
+          end
+        when Array
+          value.map { |child| normalize_value(child) }
+        when Symbol
+          value.to_s
+        else
+          value
+        end
+      end
+
+      def fetch_value(record, key)
+        return nil unless record
+        return record.public_send(key) if record.respond_to?(key)
+        return record[key] if record.respond_to?(:key?) && record.key?(key)
+        string_key = key.to_s
+        return record[string_key] if record.respond_to?(:key?) && record.key?(string_key)
+
+        nil
+      end
+    end
+  end
+end

data/lib/phronomy/persistence/storage_boundary.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Persistence
+    # Translate only the backend's existing known failure categories. Unknown
+    # transport/commit outcomes and application exceptions pass
+    # through unchanged so the operation's existing reconciliation stays in charge.
+    # @api private
+    module StorageBoundary
+      def self.call
+        yield
+      rescue Phronomy::Storage::ConflictError => error
+        raise_domain_error(ConflictError, error)
+      rescue Phronomy::Storage::NotFoundError => error
+        raise_domain_error(NotFoundError, error)
+      rescue Phronomy::Storage::SerializationError => error
+        raise_domain_error(SerializationError, error)
+      rescue Phronomy::Storage::TransactionError => error
+        raise_domain_error(TransactionError, error)
+      rescue Phronomy::Storage::UnsupportedBackendError => error
+        raise_domain_error(UnsupportedBackendError, error)
+      end
+
+      def self.raise_domain_error(type, original)
+        mapped = type.new(original.message)
+        mapped.set_backtrace(original.backtrace)
+        raise mapped, cause: original
+      end
+      private_class_method :raise_domain_error
+    end
+  end
+end