net-connector 0.9.0 → 0.10.0

data/lib/net/connector/netdisco/fleet.rb

@@ -2,10 +2,12 @@
 
 require "fileutils"
 require_relative "../storage"
+require_relative "../device_session"
 require_relative "client"
 require_relative "settings"
 require_relative "device"
 require_relative "worker"
+require_relative "operations"
 require_relative "result_store"
 require_relative "planner"
 require_relative "report"
@@ -17,6 +19,8 @@ module Net
     module Netdisco
       # 基于已验证的清单快照组织有上限的并发备份。
       class Fleet
+        attr_reader :inventory_status
+
         DEFAULT_SETTING = Object.new.freeze
         private_constant :DEFAULT_SETTING
 
@@ -34,19 +38,19 @@ module Net
         end
 
         # 拉取并标记重复管理地址的设备清单。
-        def devices
-          inventory(@settings.snapshot(mode: :inventory))
+        def devices(force_refresh: false)
+          inventory(@settings.snapshot(mode: :inventory), force_refresh: force_refresh)
         end
 
         # 规划本地配置备份的设备集合。
-        def plan_backup(limit_per_vendor: nil)
-          build_plan(:backup, limit_per_vendor, @settings.snapshot(mode: :backup))
+        def plan_backup(limit_per_vendor: nil, force_refresh: false)
+          build_plan(:backup, limit_per_vendor, @settings.snapshot(mode: :backup), force_refresh: force_refresh)
         end
 
         # 规划 TFTP 配置备份的设备集合。
-        def plan_tftp_backup(limit_per_vendor: 5, allow_fixed_name_reuse: false)
+        def plan_tftp_backup(limit_per_vendor: 5, allow_fixed_name_reuse: false, force_refresh: false)
           build_plan(:tftp, limit_per_vendor, @settings.snapshot(mode: :tftp),
-                     allow_fixed_name_reuse: allow_fixed_name_reuse)
+                     allow_fixed_name_reuse: allow_fixed_name_reuse, force_refresh: force_refresh)
         end
 
         # 先拉取完整清单，再并发采集并保存设备配置。
@@ -108,23 +112,59 @@ module Net
           end
           archive = TftpArchive.new(directory: report_directory, root: verification_root) if preserve_history
           run_batch(:tftp, plan, concurrency: concurrency, report_directory: report_directory,
-                    settings_snapshot: settings_snapshot, success_policy: success_policy, on_start: on_start, on_result: on_result,
-                    verification: preserve_history ? nil : verification) do |device, log_directory|
+                    settings_snapshot: settings_snapshot, success_policy: success_policy, on_start: on_start, on_result: on_result) do |device, log_directory|
             if archive
               archive.upload_and_archive(device, started_at: Time.now.utc) do |remote_filename|
                 tftp_backup_device(device, server, source_files, log_directory, vrfs, settings_snapshot, path: remote_filename)
               end
             else
-              tftp_backup_device(device, server, source_files, log_directory, vrfs, settings_snapshot)
+              verification.upload_and_verify(device) do |remote_filename|
+                tftp_backup_device(device, server, source_files, log_directory, vrfs, settings_snapshot, path: remote_filename)
+              end
             end
           end
         end
 
+        # 配置批次在任何连接之前验证全部脚本与目标，写操作须显式确认。
+        def execute_scripts(**options)
+          operations.execute_scripts(**options)
+        end
+
+        # 默认连贯同步，不要求调用方管理计划或重新建立设备连接。
+        def sync_interface_descriptions(**options, &)
+          operations.sync_interface_descriptions(**options, &)
+        end
+
+        # 并发生成接口描述计划，不执行配置变更。
+        def plan_interface_descriptions(**options, &)
+          operations.plan_interface_descriptions(**options, &)
+        end
+
+        # 每台设备独立重验审批证据、回读并保存，不将计划当作普通脚本执行。
+        def apply_interface_descriptions(**options)
+          operations.apply_interface_descriptions(**options)
+        end
+
         private
 
+        def operations
+          Operations.new(settings: @settings, inventory: method(:inventory), credentials: @credentials,
+                         connector_factory: @connector_factory)
+        end
+
         # 策略在清单请求之前固定；注入的清单客户端仍由调用方负责其自身生命周期。
-        def inventory(settings_snapshot)
-          rows = (@client || @settings.client(policy: settings_snapshot)).devices
+        def inventory(settings_snapshot, force_refresh: false)
+          @inventory_status = nil
+          raise ArgumentError, "force_refresh must be true or false" unless [true, false].include?(force_refresh)
+
+          client = @client || @settings.client(policy: settings_snapshot)
+          rows = client.is_a?(InventoryCache) ? client.devices(force_refresh: force_refresh) : client.devices
+          @inventory_status = if client.is_a?(InventoryCache)
+                                { source: client.status, fetched_at: client.fetched_at,
+                                  refresh_error_code: client.refresh_error_code, write_error_type: client.write_error_type }.freeze
+                              else
+                                { source: :uncached }.freeze
+                              end
           raise Client::Error, "Netdisco returned an invalid device inventory" unless rows.is_a?(Array)
 
           rules = @rules || settings_snapshot.rules
@@ -133,14 +173,14 @@ module Net
           devices.map { |device| host_counts[device.host] > 1 ? device.with(issue: :duplicate_host) : device }.freeze
         end
 
-        def build_plan(mode, limit, settings_snapshot, allow_fixed_name_reuse: false)
+        def build_plan(mode, limit, settings_snapshot, allow_fixed_name_reuse: false, force_refresh: false)
           Planner.validate_limit!(limit)
-          Planner.new(inventory(settings_snapshot)).call(mode: mode, limit_per_vendor: limit,
+          Planner.new(inventory(settings_snapshot, force_refresh: force_refresh)).call(mode: mode, limit_per_vendor: limit,
                                                allow_fixed_name_reuse: allow_fixed_name_reuse)
         end
 
         # 统一组织设备任务、日志目录与报告；Worker 保证单台设备失败不影响其他设备。
-        def run_batch(mode, plan, concurrency:, report_directory:, settings_snapshot:, success_policy:, on_start:, on_result:, output_directory: nil, verification: nil)
+        def run_batch(mode, plan, concurrency:, report_directory:, settings_snapshot:, success_policy:, on_start:, on_result:, output_directory: nil)
           worker = Worker.new(concurrency: concurrency)
           started_at = Time.now.utc
           started = monotonic
@@ -156,7 +196,6 @@ module Net
                             finished_at: Time.now.utc, callback_errors: callback_errors,
                             report_location: nil, report_error: nil)
           report = Report.new(batch, policy: success_policy, duration_ms: ((monotonic - started) * 1000).round, log_directory: log_directory)
-          report = verification.call(report) if verification
           save_report(report, directory: report_directory)
         end
 
@@ -218,7 +257,7 @@ module Net
         end
 
         # 隔离单台设备的凭据、连接、操作和关闭异常。
-        def run_device(device, log_directory, settings_snapshot, success_status:, partial_status:, backup_class:)
+        def run_device(device, log_directory, settings_snapshot, success_status:, partial_status:, backup_class:, &operation)
           connection_settings = @credentials ? @credentials.call(device) : @settings.device_credentials_for(device)
           return build_outcome(device, :missing_credentials) if connection_settings.nil?
           unless connection_settings.is_a?(Hash) && connection_settings.keys.all?(Symbol) &&
@@ -232,8 +271,9 @@ module Net
           if log_directory
             connection_settings = connection_settings.merge(log_file: File.join(log_directory, "#{log_name}.log"))
           end
-          connector = @connector_factory.call(device, connection_settings)
-          backup, failure = perform_one(connector, backup_class) { yield connector }
+          backup, failure = perform_one(backup_class, factory: -> { @connector_factory.call(device, connection_settings) }) do |connector|
+            operation.call(connector)
+          end
           return build_outcome(device, success_status, backup: backup) unless failure
 
           build_outcome(device, backup ? partial_status : :failed, backup: backup, error: failure)
@@ -242,26 +282,18 @@ module Net
         end
 
         # 仅信任库定义且产物类型匹配的提交后错误；普通第三方异常上的 backup 字段不代表完成。
-        def perform_one(connector, backup_class)
-          backup = nil
-          failure = nil
-          begin
-            result = yield
+        def perform_one(backup_class, factory:)
+          backup, failure = DeviceSession.call(factory: factory) do |session|
+            result = yield session
             raise TypeError, "backup operation did not return #{backup_class}" unless result.is_a?(backup_class)
 
-            backup = result
-          rescue StandardError => error
-            failure = error
-            if backup_class == Backup && error.instance_of?(BackupPersistenceError) && error.backup.instance_of?(Backup)
-              backup = error.backup
-            elsif backup_class == TftpReceipt && error.instance_of?(TftpCompletionError) && error.receipt.instance_of?(TftpReceipt)
-              backup = error.receipt
-            end
-          ensure
-            begin
-              connector.close
-            rescue StandardError => error
-              failure ||= error
+            result
+          end
+          if failure && backup.nil?
+            if backup_class == Backup && failure.instance_of?(BackupPersistenceError) && failure.backup.instance_of?(Backup)
+              backup = failure.backup
+            elsif backup_class == TftpReceipt && failure.instance_of?(TftpCompletionError) && failure.receipt.instance_of?(TftpReceipt)
+              backup = failure.receipt
             end
           end
           [backup, failure]

data/lib/net/connector/netdisco/inventory_cache.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "digest"
+require_relative "client"
+require_relative "../engine/error_metadata"
+require_relative "../storage/private_file"
+
+module Net
+  module Connector
+    module Netdisco
+      # 只缓存完整的原始清单；规则映射和设备凭据始终留在每次执行入口。
+      class InventoryCache
+        class Error < IOError; end
+        class Busy < Error; end
+        class InvalidCache < StandardError; end
+        private_constant :InvalidCache
+
+        DEFAULT_TTL = 3 * 24 * 60 * 60
+        ERROR_CODES = %i[client_error inventory_timeout request_failed invalid_json connection_failed
+                         pagination_stalled max_pages max_response_bytes max_inventory_bytes max_devices
+                         invalid_inventory query_failed].freeze
+        private_constant :ERROR_CODES
+        attr_reader :status, :refresh_error_code, :write_error_type, :fetched_at
+
+        def initialize(client:, directory:, identity:, ttl: DEFAULT_TTL,
+                       max_inventory_bytes: Client::DEFAULTS.fetch(:max_inventory_bytes),
+                       max_devices: Client::DEFAULTS.fetch(:max_devices), clock: -> { Time.now.utc }, lock_timeout: 5)
+          raise ArgumentError, "client must respond to devices" unless client.respond_to?(:devices)
+          raise ArgumentError, "directory must be a nonempty String" unless directory.is_a?(String) && !directory.empty? && !directory.include?("\0")
+          raise ArgumentError, "identity must be a nonempty String" unless identity.is_a?(String) && !identity.empty?
+          [ttl, lock_timeout].each do |value|
+            unless value.is_a?(Numeric) && value.real? && value.finite? && value >= 0 && value.to_f.finite?
+              raise ArgumentError, "cache durations must be nonnegative finite numbers"
+            end
+          end
+          [max_inventory_bytes, max_devices].each do |value|
+            raise ArgumentError, "cache limits must be positive integers" unless value.is_a?(Integer) && value.positive?
+          end
+          raise ArgumentError, "clock must respond to call" unless clock.respond_to?(:call)
+
+          @client, @directory, @clock = client, File.expand_path(directory).freeze, clock
+          @identity = Digest::SHA256.hexdigest(identity).freeze
+          @ttl, @lock_timeout = ttl, lock_timeout
+          @max_inventory_bytes, @max_devices = max_inventory_bytes, max_devices
+          @path = File.join(@directory, "#{@identity}.json").freeze
+          @lock_path = File.join(@directory, "#{@identity}.lock").freeze
+        end
+
+        # 锁内重读避免多个进程同时刷新；强刷仍然允许远端失败时交付历史清单。
+        def devices(force_refresh: false)
+          raise ArgumentError, "force_refresh must be true or false" unless [true, false].include?(force_refresh)
+
+          @status = @refresh_error_code = @write_error_type = @fetched_at = nil
+          with_directory do
+            previous = read_cache
+            return deliver(previous, :fresh_cache) if !force_refresh && fresh?(previous)
+
+            with_lock do
+              previous = read_cache
+              return deliver(previous, :fresh_cache) if !force_refresh && fresh?(previous)
+
+              refresh(previous)
+            end
+          end
+        end
+
+        def inspect = "#<#{self.class} status=#{@status.inspect}>"
+
+        private
+
+        # 目录的所有者和权限是末级 NOFOLLOW 检查的前提；不修补不可信的既有目录。
+        def with_directory
+          FileUtils.mkdir_p(@directory, mode: 0o700) unless File.exist?(@directory) || File.symlink?(@directory)
+          File.open(@directory, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |directory|
+            stat = directory.stat
+            unless stat.directory? && stat.uid == Process.euid && (stat.mode & 0o7777) == 0o700
+              raise Error, "inventory cache directory must be owned with mode 0700"
+            end
+            verify_entry!(@directory, stat)
+            result = yield
+            verify_entry!(@directory, stat)
+            result
+          end
+        rescue Errno::ELOOP, Errno::ENOTDIR
+          raise Error, "inventory cache directory must not be a symlink", cause: nil
+        end
+
+        def with_lock
+          File.open(@lock_path, File::RDWR | File::CREAT | File::NOFOLLOW | File::NONBLOCK, 0o600) do |lock|
+            verify_private_file!(lock, @lock_path)
+            deadline = monotonic + @lock_timeout
+            until lock.flock(File::LOCK_EX | File::LOCK_NB)
+              remaining = deadline - monotonic
+              raise Busy, "inventory cache refresh lock timed out" if remaining <= 0
+
+              sleep([remaining, 0.05].min)
+            end
+            verify_private_file!(lock, @lock_path)
+            yield
+          end
+        rescue Errno::ELOOP, Errno::EISDIR, Errno::ENXIO
+          raise Error, "inventory cache lock must be a private regular file", cause: nil
+        end
+
+        # 同一 FD 上校验和限量读取，不依赖 stat 的大小来约束持续增长的文件。
+        def read_cache
+          File.open(@path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
+            stat = verify_private_file!(file, @path)
+            return nil if stat.size > @max_inventory_bytes
+
+            body = file.read(@max_inventory_bytes + 1)
+            return nil if body.bytesize > @max_inventory_bytes
+
+            entry = JSON.parse(body)
+            unless entry.is_a?(Hash) && entry.keys.sort == %w[fetched_at identity rows schema] &&
+                   entry["schema"] == 1 && entry["identity"] == @identity && valid_time?(entry["fetched_at"])
+              return nil
+            end
+            entry["rows"] = normalize_rows(entry["rows"])
+            entry
+          end
+        rescue Errno::ENOENT, JSON::ParserError, InvalidCache
+          nil
+        rescue Errno::ELOOP, Errno::EISDIR, Errno::ENXIO
+          raise Error, "inventory cache must be a private regular file", cause: nil
+        end
+
+        # 清单已取得后，落盘失败不能让调用方退回旧清单或重新执行远端查询。
+        def refresh(previous)
+          begin
+            rows = normalize_rows(@client.devices)
+          rescue Client::Error => error
+            raise unless previous
+
+            @refresh_error_code = ERROR_CODES.include?(error.code) ? error.code : :client_error
+            return deliver(previous, :stale_cache)
+          rescue InvalidCache
+            error = Client::Error.new("Netdisco returned an invalid device inventory", code: :invalid_inventory)
+            raise error, cause: nil unless previous
+
+            @refresh_error_code = ERROR_CODES.include?(error.code) ? error.code : :client_error
+            return deliver(previous, :stale_cache)
+          end
+          entry = { "schema" => 1, "identity" => @identity, "fetched_at" => now, "rows" => rows }
+          begin
+            body = JSON.generate(entry)
+            raise Error, "inventory cache exceeds max_inventory_bytes" if body.bytesize > @max_inventory_bytes
+
+            Storage::PrivateFile.write(@path, body)
+          rescue StandardError => error
+            @write_error_type = ErrorMetadata.type(error.class.name) || "StandardError"
+          end
+          deliver(entry, :refreshed)
+        end
+
+        # 校验限额后只复制白名单字段；调用方和缓存不能共享可变的远端响应。
+        def normalize_rows(rows)
+          raise InvalidCache unless rows.is_a?(Array) && rows.size <= @max_devices
+
+          bytes = 0
+          rows.map do |row|
+            unless row.is_a?(Hash) && row["ip"].is_a?(String) && !row["ip"].strip.empty? &&
+                   Client::FIELDS.all? { |field| row[field].nil? || row[field].is_a?(String) }
+              raise InvalidCache
+            end
+            selected = row.slice(*Client::FIELDS)
+            bytes += selected.sum { |key, value| key.bytesize + (value&.bytesize || 0) }
+            raise InvalidCache if bytes > @max_inventory_bytes
+
+            selected.transform_values { |value| value&.dup&.freeze }.freeze
+          end.freeze
+        end
+
+        def verify_private_file!(file, path)
+          stat = file.stat
+          unless stat.file? && stat.uid == Process.euid && stat.nlink == 1 && (stat.mode & 0o7777) == 0o600
+            raise Error, "inventory cache files must be owned regular files with mode 0600 and one link"
+          end
+          verify_entry!(path, stat)
+          stat
+        end
+
+        def verify_entry!(path, stat)
+          current = File.lstat(path)
+          return if current.dev == stat.dev && current.ino == stat.ino && !current.symlink?
+
+          raise Error, "inventory cache path changed during access"
+        end
+
+        def valid_time?(value)
+          value.is_a?(Numeric) && value.real? && value.finite? && value >= 0 && value <= now
+        end
+
+        def fresh?(entry) = entry && now - entry.fetch("fetched_at") < @ttl
+
+        def deliver(entry, status)
+          @status = status
+          @fetched_at = Time.at(entry.fetch("fetched_at")).utc.freeze
+          entry.fetch("rows")
+        end
+
+        def now
+          input = @clock.call
+          value = input.is_a?(Time) ? input.to_f : input
+          unless value.is_a?(Numeric) && value.real? && value.finite? && value >= 0 && value.to_f.finite?
+            raise ArgumentError, "clock must return a finite nonnegative timestamp"
+          end
+
+          value.to_f
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco/operation_batch.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "diagnostic"
+require_relative "device"
+require_relative "../engine/result"
+require_relative "../device/topology"
+require "time"
+
+module Net
+  module Connector
+    module Netdisco
+      # 设备操作保留领域返回值；公开摘要不展开命令、配置、异常消息或审批证据。
+      OperationOutcome = Data.define(:device, :status, :value, :error, :started_at, :finished_at, :duration_ms) do
+        # 时间对象也可被调用方修改；领域值由操作边界固定，结果不共享可变时间。
+        def initialize(device:, status:, value:, error:, started_at:, finished_at:, duration_ms:)
+          raise ArgumentError, "operation outcome requires a Device" unless device.is_a?(Device)
+          unless %i[succeeded partial failed missing_credentials].include?(status)
+            raise ArgumentError, "operation outcome contains an invalid status"
+          end
+          unless value.nil? || value.is_a?(Result) || value.is_a?(Topology::Plan)
+            raise ArgumentError, "operation outcome contains an invalid domain value"
+          end
+          raise ArgumentError, "operation error must be a StandardError or nil" unless error.nil? || error.is_a?(StandardError)
+          validate_state!(status, value, error)
+          unless started_at.is_a?(Time) && finished_at.is_a?(Time)
+            raise ArgumentError, "operation outcome timestamps must be Times"
+          end
+          unless duration_ms.is_a?(Numeric) && duration_ms.real? && duration_ms.finite? && duration_ms >= 0
+            raise ArgumentError, "operation duration must be nonnegative and finite"
+          end
+
+          value = immutable_plan_value(value) if value.is_a?(Topology::Plan)
+          super(device: device, status: status, value: value, error: error,
+                started_at: started_at.dup.freeze, finished_at: finished_at.dup.freeze, duration_ms: duration_ms)
+        end
+
+        def with(**attributes)
+          return self if attributes.empty?
+
+          fields = self.class.members.to_h { |name| [name, public_send(name)] }
+          self.class.new(**fields.merge(attributes))
+        end
+
+        def success? = status == :succeeded
+
+        def partial? = status == :partial
+
+        def to_h
+          { host: device.host, vendor: device.vendor, status: status,
+            started_at: started_at.iso8601, finished_at: finished_at.iso8601, duration_ms: duration_ms,
+            steps: value.is_a?(Result) ? value.steps.size : nil,
+            changes: value.is_a?(Topology::Plan) ? value.changes.size : nil,
+            diagnostic: Diagnostic.from(error)&.to_h }.compact
+        end
+
+        def inspect = "#<#{self.class} host=#{device.host.inspect} status=#{status.inspect}>"
+
+        private
+
+        # 公开更新不能把失败的领域结果改写成成功；首个业务错误与完成步骤仍是权威。
+        def validate_state!(status, value, error)
+          same_error = !value.is_a?(Result) || value.success? || error.equal?(value.error)
+          valid = case status
+                  when :succeeded then value && error.nil? && (!value.is_a?(Result) || value.success?)
+                  when :partial then value && error && (!value.is_a?(Result) || value.success? || !value.steps.empty?)
+                  when :failed then error && (value.nil? || (value.is_a?(Result) && value.failure? && value.steps.empty?))
+                  when :missing_credentials then value.nil? && error.nil?
+                  end
+          raise ArgumentError, "operation state contradicts its domain value or error" unless valid && same_error
+        end
+
+        # 外部构造或 with 更新也复制审批树，不仅冻结 Data 的最外层。
+        def immutable_plan_value(value)
+          case value
+          when String then value.frozen? ? value : value.dup.freeze
+          when Array then value.map { |item| immutable_plan_value(item) }.freeze
+          when Hash then value.to_h { |key, item| [immutable_plan_value(key), immutable_plan_value(item)] }.freeze
+          when Topology::Plan, Topology::Change, Topology::Neighbor
+            fields = value.to_h.transform_values { |item| immutable_plan_value(item) }
+            value.class.new(**fields).freeze
+          else value
+          end
+        end
+      end
+
+      # 一次操作的结果按请求顺序返回，回调故障与设备故障分别记录。
+      OperationBatch = Data.define(:operation, :outcomes, :callback_errors, :started_at, :finished_at) do
+        def initialize(operation:, outcomes:, callback_errors:, started_at:, finished_at:)
+          unless %i[execute_scripts sync_interface_descriptions plan_interface_descriptions apply_interface_descriptions].include?(operation)
+            raise ArgumentError, "operation batch contains an invalid operation"
+          end
+          unless outcomes.is_a?(Array) && outcomes.all?(OperationOutcome) && callback_errors.is_a?(Array)
+            raise ArgumentError, "operation batch requires outcome and callback error Arrays"
+          end
+          unless started_at.is_a?(Time) && finished_at.is_a?(Time)
+            raise ArgumentError, "operation batch timestamps must be Times"
+          end
+          super(operation: operation, outcomes: outcomes.dup.freeze,
+                callback_errors: callback_errors.map { |entry| copy_callback_error(entry) }.freeze,
+                started_at: started_at.dup.freeze, finished_at: finished_at.dup.freeze)
+        end
+
+        # Ruby 3.2 更新同样重新复制容器；摘要 to_h 不参与领域对象的重建。
+        def with(**attributes)
+          return self if attributes.empty?
+
+          fields = self.class.members.to_h { |name| [name, public_send(name)] }
+          self.class.new(**fields.merge(attributes))
+        end
+
+        def success? = !outcomes.empty? && outcomes.all?(&:success?) && callback_errors.empty?
+
+        def counts = outcomes.map(&:status).tally
+
+        def status = outcomes.empty? ? :no_devices : (success? ? :succeeded : :incomplete)
+
+        # 清单总数指本批调度设备；部分完成与缺少凭据均计入失败，通知故障单独计数。
+        # 设备成功只在操作与关闭均完成后确认，不把远端已经发生的变更解释成可回滚事务。
+        def summary
+          statuses = counts
+          succeeded = statuses.fetch(:succeeded, 0)
+          { total: outcomes.size, succeeded: succeeded, failed: outcomes.size - succeeded,
+            partial: statuses.fetch(:partial, 0), missing_credentials: statuses.fetch(:missing_credentials, 0),
+            callback_errors: callback_errors.size }.freeze
+        end
+
+        # 只有完整成功的只读规划自动进入下一阶段；关闭失败的证据仍可从 outcome.value 显式检查。
+        def plans
+          outcomes.each_with_object({}) do |outcome, found|
+            found[outcome.device.host] = outcome.value if outcome.success? && outcome.value.is_a?(Topology::Plan)
+          end.freeze
+        end
+
+        def to_h
+          { operation: operation, status: status, success: success?, summary: summary, counts: counts,
+            started_at: started_at.iso8601, finished_at: finished_at.iso8601,
+            outcomes: outcomes.map(&:to_h), callback_errors: callback_errors }
+        end
+
+        def inspect = "#<#{self.class} operation=#{operation.inspect} counts=#{counts.inspect}>"
+
+        private
+
+        def copy_callback_error(entry)
+          unless entry.is_a?(Hash) && entry.keys.sort == %i[error_type host] && entry[:host].is_a?(String)
+            raise ArgumentError, "callback errors must contain a host and error type"
+          end
+
+          { host: entry[:host].dup.freeze, error_type: ErrorMetadata.type(entry[:error_type]) || "StandardError" }.freeze
+        end
+      end
+    end
+  end
+end