phronomy 0.28.0 → 0.30.0

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

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

data/lib/phronomy/agent/output_contract.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Phronomy
+  module Agent
+    # Owns the execution's output promise; generic schema interpretation is injected.
+    # @api private
+    class OutputContract
+      FACTORIES = {}
+      private_constant :FACTORIES
+      attr_reader :schema, :digest
+
+      def self.install_factory(factory)
+        FACTORIES.replace(parser: factory).freeze
+      end
+
+      def initialize(schema)
+        @parser = FACTORIES.fetch(:parser).call(schema)
+        @schema = @parser.json_schema
+        @digest = Digest::SHA256.hexdigest(JSON.generate(@schema, sort_keys: true)).freeze
+        freeze
+      end
+
+      def metadata(contents)
+        {"output_contract" => {"version" => 1, "schema_ref" => contents.put_text(JSON.generate(schema, sort_keys: true)), "schema_digest" => digest}}
+      end
+
+      def self.restore(execution, contents)
+        stored = execution.metadata["output_contract"]
+        return nil unless stored
+        raise ArgumentError, "unsupported Agent output contract version" unless stored.fetch("version") == 1
+        contract = new(contents.fetch_json(stored.fetch("schema_ref")))
+        unless contract.digest == stored.fetch("schema_digest")
+          raise Phronomy::ContentStore::IntegrityError, "Agent output schema digest mismatch"
+        end
+        contract
+      end
+
+      def validate(output, response:, execution_id:)
+        raw = response&.content
+        reason = if response&.refusal || response&.finish_reason == :refusal
+          "model_refusal"
+        elsif !response || !%i[stop].include?(response.finish_reason) || !response.tool_calls.empty?
+          %i[length content_filter].include?(response&.finish_reason) ? response.finish_reason.to_s : "unknown_finish_reason"
+        elsif output.nil? || raw.nil?
+          "missing_output"
+        end
+        if reason
+          raise OutputError.new(execution_id: execution_id, schema_digest: digest, reason: reason, raw_output: raw)
+        end
+        @parser.parse(output)
+      rescue Phronomy::ParseError => error
+        reason = case error.code
+        when "output_parser.invalid_json" then "invalid_json"
+        when "output_parser.schema_mismatch" then "schema_mismatch"
+        else raise
+        end
+        raise OutputError.new(execution_id: execution_id, schema_digest: digest, reason: reason,
+          violations: error.details, raw_output: raw), cause: error
+      end
+    end
+  end
+end

data/lib/phronomy/agent/output_error.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # A declared output contract could not be fulfilled. Tool effects remain facts.
+    # @api public
+    class OutputError < Phronomy::Error
+      CODES = {"invalid_json" => "agent.output_invalid", "schema_mismatch" => "agent.output_invalid",
+               "missing_output" => "agent.output_invalid", "model_refusal" => "agent.output_refused",
+               "length" => "agent.output_incomplete", "content_filter" => "agent.output_incomplete",
+               "unknown_finish_reason" => "agent.output_incomplete"}.freeze
+      private_constant :CODES
+
+      # @api public
+      attr_reader :execution_id, :schema_digest, :reason, :violations, :raw_output
+
+      # @api public
+      def initialize(execution_id:, schema_digest:, reason:, violations: [], raw_output: nil)
+        @execution_id = execution_id.to_s.dup.freeze
+        @schema_digest = schema_digest.to_s.dup.freeze
+        @reason = reason.to_s.dup.freeze
+        @violations = Phronomy::Values::Immutable.json(violations)
+        @raw_output = Phronomy::Values::Immutable.copy(raw_output)
+        super("Agent output contract failed: #{@reason}", code: CODES.fetch(@reason))
+      end
+
+      # Owner-defined facts for persistence and composition; no live exception values.
+      # @api private
+      def diagnostic(include_raw: true)
+        value = Phronomy::Error.diagnostic(self).merge("execution_id" => execution_id,
+          "schema_digest" => schema_digest, "reason" => reason, "violations" => violations)
+        value["raw_output"] = raw_output if include_raw
+        Phronomy::Values::Immutable.json(value)
+      end
+
+      # @api private
+      def self.restore(value)
+        error = new(execution_id: value.fetch("execution_id"), schema_digest: value.fetch("schema_digest"),
+          reason: value.fetch("reason"), violations: value.fetch("violations"), raw_output: value["raw_output"])
+        raise ArgumentError, "invalid Agent output diagnostic code" unless error.code == value.fetch("code")
+        if value["cause"]
+          begin
+            raise error, cause: Phronomy::Error.from_diagnostic(value.fetch("cause"))
+          rescue OutputError => restored
+            restored.set_backtrace(nil)
+            return restored
+          end
+        end
+        error
+      end
+    end
+  end
+end

data/lib/phronomy/agent/recovery/recovery_coordinator/continuation.rb

@@ -39,9 +39,9 @@ module Phronomy
           materializer = RuntimeInput.new(agent: agent, persistence: agent.persistence)
           messages = records.map { |record| materializer.materialize_journal_record(record) }.freeze
           assistant = messages.reverse.find { |message| message.role.to_sym == :assistant }
-          output, usage = SavedContextReader.provider_output_and_usage(agent, execution) if execution.phase.to_sym == :recovery_provider_completed
+          output, usage, response = SavedContextReader.provider_output_and_usage(agent, execution) if execution.phase.to_sym == :recovery_provider_completed
           RecoveryMaterial.new(projection: projection, messages: messages,
-            assistant_message: assistant, output: output, usage: usage,
+            assistant_message: assistant, output: output, usage: usage, response: response,
             cancellation_requested: agent.persistence.cancellation_requested?(agent_id: agent.agent_id, execution_id: execution.execution_id))
         end
 
@@ -52,9 +52,9 @@ module Phronomy
             environment.registry.mark_agent_execution_admission(agent.agent_id,
               execution_id: execution.execution_id, state: :recovery_required)
             deliver_resolution_required(execution, coordination_recovery_descriptor(execution))
-            completion.complete({execution_id: execution.execution_id,
-                                 execution_revision: execution.execution_revision,
-                                 recovery: :resolution_required}.freeze)
+            agent.send(:_complete_result_task, completion, {execution_id: execution.execution_id,
+                                                            execution_revision: execution.execution_revision,
+                                                            recovery: :resolution_required}.freeze)
             return
           end
 
@@ -73,7 +73,7 @@ module Phronomy
                 agent.send(:_phronomy_event_listener), messages: material.messages, cancellation_requested: material.cancellation_requested)
             end
             if execution.phase.to_sym == :recovery_provider_completed
-              invocation.output, invocation.usage = material.output, material.usage
+              invocation.apply_llm_response!(material.response)
             end
             prepare_saved_provider_calls(execution, invocation, material.assistant_message) if action == :framework_calls
           end

data/lib/phronomy/agent/recovery/recovery_coordinator/installation.rb

@@ -38,7 +38,7 @@ module Phronomy
         end
 
         def prepare_plan(execution)
-          root = agent.agent_root
+          root = agent.send(:__root_for_operation)
           manifest_ref = execution.metadata["manifest_ref"]
           base_ref = execution.metadata["base_manifest_ref"] ||
             manifest_ref
@@ -209,7 +209,7 @@ module Phronomy
                 }
               )
             end
-            command.completion.complete(agent)
+            agent.send(:_complete_result_task, command.completion, agent)
             return
           end
 
@@ -246,7 +246,7 @@ module Phronomy
                 result: payload
               )
             end
-            command.completion.complete(agent)
+            agent.send(:_complete_result_task, command.completion, agent)
           when Phronomy::Agent::RecoveryRules::RESUMABLE
             continue_resumable_on_event_loop(
               execution,
@@ -288,7 +288,7 @@ module Phronomy
               end
             end
           end
-          command.completion.fail(caught)
+          agent.send(:_fail_result_task, command.completion, caught)
           # simplecov:enable
         end
 
@@ -296,6 +296,7 @@ module Phronomy
           Phronomy::Tracing::Automatic.observe_task(
             task,
             "agent.execution",
+            usage: ->(value) { value.is_a?(Hash) ? value[:usage]&.to_h&.freeze : nil },
             agent_id: agent.agent_id,
             execution_id: execution.execution_id,
             mode: (
@@ -317,7 +318,7 @@ module Phronomy
           if framework_batch?(execution)
             internal = Phronomy::TaskResult.deferred(name: "framework-tool-recovery:#{execution.execution_id}")
             continue_recovery_on_event_loop(execution, internal, material: material)
-            completion.complete(agent)
+            agent.send(:_complete_result_task, completion, agent)
             return
           end
 
@@ -359,11 +360,11 @@ module Phronomy
               result_task: internal_task,
               error: nil
             ))
-            completion.complete(agent)
+            agent.send(:_complete_result_task, completion, agent)
           when :recovery_tools_completed, :recovery_provider_completed, :recovery_resolved_failed
             internal_task = Phronomy::TaskResult.deferred(name: "agent-recovery-auto:#{execution.execution_id}")
             continue_recovery_on_event_loop(execution, internal_task, material: material)
-            completion.complete(agent)
+            agent.send(:_complete_result_task, completion, agent)
           else
             raise Phronomy::ExecutionRehydrationRequiredError,
               "no automatic continuation for #{execution.phase.inspect}"

data/lib/phronomy/agent/recovery/recovery_coordinator/resolution.rb

@@ -14,24 +14,22 @@ module Phronomy
             request.execution_id
           )
           unless state && state.agent.equal?(agent)
-            request.completion.fail(
+            agent.send(:_fail_result_task, request.completion,
               Phronomy::ExecutionRehydrationRequiredError.new(
                 "no live recovered execution #{request.execution_id}"
-              )
-            )
+              ))
             return
           end
 
           current = state.execution
           unless current.execution_revision ==
               request.expected_execution_revision
-            request.completion.fail(
+            agent.send(:_fail_result_task, request.completion,
               Phronomy::Persistence::StateConflictError.new(
                 "Recovery resolution revision conflict: expected " \
                 "#{request.expected_execution_revision}, actual " \
                 "#{current.execution_revision}"
-              )
-            )
+              ))
             return
           end
 
@@ -42,28 +40,26 @@ module Phronomy
                 descriptor.fetch(:subject),
                 request.subject
               )
-            request.completion.fail(
+            agent.send(:_fail_result_task, request.completion,
               ArgumentError.new(
                 "Recovery subject is not current for execution #{request.execution_id}"
-              )
-            )
+              ))
             return
           end
 
           unless Array(
             descriptor.fetch(:allowed_outcomes)
           ).map(&:to_sym).include?(request.outcome)
-            request.completion.fail(
+            agent.send(:_fail_result_task, request.completion,
               ArgumentError.new(
                 "Recovery outcome #{request.outcome.inspect} is not allowed for the current subject"
-              )
-            )
+              ))
             return
           end
 
           operation = ResolutionOperation.new(
             execution: current,
-            root: agent.agent_root,
+            root: agent.send(:__root_for_operation),
             subject: request.subject,
             outcome: request.outcome,
             result: request.result,
@@ -77,6 +73,7 @@ module Phronomy
           task = @environment.submit(on_full: :raise) do
             prepare_resolution(operation)
           end
+          request.completion.track(task) if request.completion.respond_to?(:track)
           task.on_complete do |result, error|
             ready = ResolveReady.new(
               coordinator: self,
@@ -86,15 +83,14 @@ module Phronomy
               error: error
             )
             unless post_control(ready)
-              request.completion.fail(
+              agent.send(:_fail_result_task, request.completion,
                 Phronomy::RuntimeShutdownError.new(
                   "EventLoop rejected Recovery resolution apply"
-                )
-              )
+                ))
             end
           end
         rescue => caught
-          request.completion.fail(caught)
+          agent.send(:_fail_result_task, request.completion, caught)
         end
 
         def perform_resolution(operation)
@@ -498,7 +494,7 @@ module Phronomy
 
           continue_recovery_on_event_loop(result.execution, request.completion, material: result.material)
         rescue => caught
-          request.completion.fail(caught)
+          agent.send(:_fail_result_task, request.completion, caught)
         end
       end
     end

data/lib/phronomy/agent/recovery/recovery_coordinator.rb

@@ -39,7 +39,7 @@ module Phronomy
       )
       ResolutionResult = Data.define(:execution)
       ResolutionPreparation = Data.define(:execution, :material, :error)
-      RecoveryMaterial = Data.define(:projection, :messages, :assistant_message, :output, :usage, :cancellation_requested)
+      RecoveryMaterial = Data.define(:projection, :messages, :assistant_message, :output, :usage, :response, :cancellation_requested)
       RecoveryPlan = Data.define(
         :execution, :root, :manifest, :base_manifest,
         :projection, :classification, :material
@@ -147,9 +147,8 @@ module Phronomy
         failure = error_present ?
           RecoverySupport.resolution_failure(error) : nil
 
-        completion = Phronomy::TaskResult.deferred(
-          name: "agent-recovery-resolve:#{execution_id}"
-        )
+        completion = OperationResult.new(agent: agent,
+          name: "agent-recovery-resolve:#{execution_id}")
         command = ResolveCommand.new(
           coordinator: self,
           execution_id: execution_id.to_s.freeze,
@@ -162,18 +161,15 @@ module Phronomy
           completion: completion
         )
         unless post_control(command)
-          completion.fail(
-            Phronomy::RuntimeShutdownError.new(
-              "EventLoop rejected Agent Recovery resolution"
-            )
-          )
+          agent.send(:_fail_result_task, completion,
+            Phronomy::RuntimeShutdownError.new("EventLoop rejected Agent Recovery resolution"))
         end
         completion
       rescue => caught
         completion ||= Phronomy::TaskResult.deferred(
           name: "agent-recovery-resolve:#{execution_id}"
         )
-        completion.fail(caught)
+        agent.send(:_fail_result_task, completion, caught)
         completion
       end
 

data/lib/phronomy/agent/recovery/recovery_support.rb

@@ -26,17 +26,15 @@ module Phronomy
       end
 
       def resolution_failure(error)
-        {
-          "class" => error.class.name.to_s,
-          "message" => error.message.to_s
-        }.freeze
+        Phronomy::Error.diagnostic(error).freeze
       end
 
       def error_from_failure(failure)
-        hash = failure.to_h { |key, value| [key.to_s, value] }
-        Phronomy::Error.new(
-          "#{hash.fetch("class", "Error")}: #{hash.fetch("message", "Recovery-resolved failure")}"
-        )
+        if failure["class"] == "Phronomy::Agent::OutputError"
+          OutputError.restore(failure)
+        else
+          Phronomy::Error.from_diagnostic(failure)
+        end
       end
 
       def event_payload(execution, descriptor)

data/lib/phronomy/agent/runtime_binding/engine_session_builder.rb

@@ -23,7 +23,8 @@ module Phronomy
           declared_states: InvocationTransitions::DECLARED_STATES,
           wait_state_names: InvocationTransitions::WAIT_STATES,
           external_events: InvocationTransitions::EXTERNAL_EVENTS,
-          recursion_limit: InvocationTransitions.recursion_limit(invocation.agent.class.max_iterations),
+          recursion_limit: InvocationTransitions::AUTOMATIC_RECURSION_LIMIT,
+          recursion_limit_scope: :automatic_chain,
           event_loop: event_loop,
           resume_event: resume_event,
           resume_phase: resume_phase

data/lib/phronomy/agent/runtime_input.rb

@@ -5,8 +5,12 @@ module Phronomy
     class RuntimeInput
       RuntimeProjection = Data.define(
         :system, :messages, :tool_classes, :ask_message,
-        :model_config, :manifest, :manifest_ref
-      )
+        :model_config, :manifest, :manifest_ref, :response_schema
+      ) do
+        def initialize(response_schema: nil, **values)
+          super(**values, response_schema: response_schema)
+        end
+      end
 
       def initialize(agent:, persistence:, additional_tools: [])
         @agent = agent
@@ -45,7 +49,8 @@ module Phronomy
           ask_message: ask_message,
           model_config: Phronomy::Values::Immutable.copy(model_config),
           manifest: manifest,
-          manifest_ref: manifest_ref
+          manifest_ref: manifest_ref,
+          response_schema: manifest.response_schema_ref && Phronomy::Values::Immutable.json(fetch_json(manifest.response_schema_ref))
         )
       end
 
@@ -148,12 +153,18 @@ module Phronomy
         end
 
         tool_calls = materialize_tool_calls(payload["tool_calls"])
+        metadata = payload.fetch("metadata", {})
+        raise ArgumentError, "canonical message metadata must be a Hash" unless metadata.is_a?(Hash)
+        metadata = metadata.dup
+        # Preserve backend-owned values without interpreting them. Old records
+        # stored model_id only at the top level; retain that read compatibility.
+        metadata["model_id"] = payload["model_id"] if !metadata.key?("model_id") && payload["model_id"]
         Phronomy::LLMAdapter::Message.new(
           role: role,
           content: payload.fetch("content", nil),
           tool_calls: tool_calls,
           tool_call_id: payload["tool_call_id"],
-          metadata: {"model_id" => payload["model_id"]}.compact
+          metadata: metadata
         )
       end
 

data/lib/phronomy/agent/saved_context_reader.rb

@@ -48,7 +48,8 @@ module Phronomy
           cached: usage_hash["cached"] || usage_hash[:cached] || usage_hash["cache_read_tokens"] || usage_hash[:cache_read_tokens] || usage_hash["cached_tokens"] || usage_hash[:cached_tokens],
           cache_creation: usage_hash["cache_creation"] || usage_hash[:cache_creation] || usage_hash["cache_write_tokens"] || usage_hash[:cache_write_tokens] || usage_hash["cache_creation_tokens"] || usage_hash[:cache_creation_tokens]
         )
-        [output, usage]
+        response = Phronomy::LLMAdapter::Response.from_h(payload.merge("usage" => usage.to_h))
+        [output, usage, response]
       end
     end
   end

data/lib/phronomy/agent/store.rb

@@ -79,7 +79,8 @@ module Phronomy
           execution_id: execution.execution_id, agent_id: execution.agent_id,
           status: execution.status, phase: execution.phase,
           result_ref: execution.result_ref, error_ref: execution.error_ref,
-          result: execution.result_ref && contents.fetch_text(execution.result_ref),
+          result: materialize_result(execution, contents),
+          raw_output: execution.metadata["raw_output_ref"] && contents.fetch_text(execution.metadata.fetch("raw_output_ref")),
           error: execution.error_ref && contents.fetch_json(execution.error_ref)
         }.then { |value| Phronomy::Values::Immutable.copy(value) }
       end
@@ -97,7 +98,8 @@ module Phronomy
           assert_execution_owner!(execution, agent_id)
           ExecutionObservation.new(agent_id: execution.agent_id, execution_id: execution.execution_id,
             status: execution.status,
-            result: execution.result_ref && records.contents.fetch_text(execution.result_ref),
+            result: materialize_result(execution, records.contents),
+            raw_output: execution.metadata["raw_output_ref"] && records.contents.fetch_text(execution.metadata.fetch("raw_output_ref")),
             error: execution.error_ref && Phronomy::Values::Immutable.copy(records.contents.fetch_json(execution.error_ref)),
             reservation: execution.metadata["reservation"] && ReservedExecution.new(agent_id: agent_id,
               execution_id: execution_id, correlation: execution.metadata["reservation"]),
@@ -226,6 +228,12 @@ module Phronomy
 
       private
 
+      def materialize_result(execution, contents)
+        return nil unless execution.result_ref
+        (execution.metadata["result_format"] == "json") ?
+          Phronomy::Values::Immutable.json(contents.fetch_json(execution.result_ref)) : contents.fetch_text(execution.result_ref)
+      end
+
       def authorized_argument_values(entry)
         # Unit 6 persists the exact validated snapshot. Older records encoded
         # legacy raw params, whose explicit optional nil meant omission.

data/lib/phronomy/agent/stream_callback_error.rb

@@ -22,14 +22,14 @@ module Phronomy
     # @return [Exception] original Application callback exception
     attr_reader :original_error
 
-    def initialize(event_type:, original_error:, result: nil)
+    def initialize(event_type:, original_error:, result: nil, code: nil)
       @event_type = event_type
       @original_error = original_error
       @result = result
 
       super(
         "Stream callback failed while handling #{event_type.inspect}: " \
-        "#{original_error.class}: #{original_error.message}"
+        "#{original_error.class}: #{original_error.message}", code: code
       )
       set_backtrace(original_error.backtrace)
     end

data/lib/phronomy/common/error.rb

@@ -1,5 +1,69 @@
 # frozen_string_literal: true
 
 module Phronomy
-  class Error < StandardError; end
+  class Error < StandardError
+    # Optional stable reason supplied by the owner of the failed operation.
+    # It does not imply retry safety or replace execution status.
+    # @api public
+    attr_reader :code
+
+    # Existing message-only construction retains StandardError behavior.
+    # @api public
+    def initialize(message = nil, code: nil)
+      raise ArgumentError, "error code must be a String or nil" unless code.nil? || code.is_a?(String)
+      @code = code&.dup&.freeze
+      super(message)
+    end
+
+    # Generic diagnostic transport. No domain-specific interpretation.
+    # External exceptions are not extended with this protocol.
+    # @api private
+    def self.diagnostic(error)
+      diagnostic = {"class" => error.class.name, "message" => error.message}
+      diagnostic["code"] = error.code if error.is_a?(Phronomy::Error) && error.code
+      cause = error.cause
+      diagnostic["cause"] = cause_diagnostic(cause, remaining: 3, seen: [error.object_id]) if cause
+      diagnostic
+    end
+
+    # Restores data, never a saved class name or arbitrary instance attributes.
+    # Restored causes are generic errors as well. Old diagnostics remain valid.
+    # @api private
+    def self.from_diagnostic(value, remaining: 3)
+      hash = value.to_h { |key, item| [key.to_s, item] }
+      error = Phronomy::Error.new(
+        "#{hash.fetch("class", "Error")}: #{hash.fetch("message", "Recovery-resolved failure")}",
+        code: hash["code"]
+      )
+      return error unless remaining.positive? && hash["cause"].is_a?(Hash) && hash["cause"].key?("class")
+
+      cause = from_diagnostic(hash["cause"], remaining: remaining - 1)
+      begin
+        raise error, cause: cause
+      rescue Phronomy::Error => restored
+        restored.set_backtrace(nil)
+        restored
+      end
+    end
+
+    def self.cause_diagnostic(error, remaining:, seen:)
+      return {"truncated" => true} if remaining.zero? || seen.include?(error.object_id)
+
+      # Bound newly added cause data; retain the existing top-level format.
+      fields = {"class" => error.class.name, "message" => error.message}
+      fields["code"] = error.code if error.is_a?(Phronomy::Error) && error.code
+      diagnostic = fields.to_h do |key, value|
+        [key, value.is_a?(String) ? value[0, 2048] : value]
+      end
+      # Never turn a truncated reason into a different, apparently valid code.
+      diagnostic.delete("code") if fields["code"] && fields["code"].length > 2048
+      diagnostic["truncated"] = true if diagnostic != fields
+      if error.cause
+        diagnostic["cause"] = cause_diagnostic(error.cause,
+          remaining: remaining - 1, seen: seen + [error.object_id])
+      end
+      diagnostic
+    end
+    private_class_method :cause_diagnostic
+  end
 end