net-connector 0.12.0 → 0.14.0

data/lib/net/connector/device/tftp.rb

@@ -11,8 +11,8 @@ module Net
       module Capability
         # 要求设备直接向 TFTP 服务器导出原生配置。
         # 完成仅表示设备报告传输成功，未读取服务器端文件。
-        def tftp_backup(host:, path: nil, source_file: nil, vrf: nil)
-          Tftp.new(self).call(host: host, path: path, source_file: source_file, vrf: vrf)
+        def tftp_backup(host:, path: nil, source_file: nil, vrf: nil, source_interface: nil)
+          Tftp.new(self).call(host: host, path: path, source_file: source_file, vrf: vrf, source_interface: source_interface)
         end
       end
 
@@ -20,7 +20,7 @@ module Net
       def initialize(device) = @device = device
 
       # 参数先纯校验；源探测、上传、证据核对及收尾共用一次会话租约。
-      def call(host:, path: nil, source_file: nil, vrf: nil)
+      def call(host:, path: nil, source_file: nil, vrf: nil, source_interface: nil)
         receipt = nil
         strategy_class = @device.profile.tftp_strategy
         unless strategy_class
@@ -34,12 +34,21 @@ module Net
         source_file = TftpTarget.validate_source_file!(source_file).dup.freeze unless source_file.nil?
         vrf = vrf&.dup&.freeze
         target = TftpTarget.new(host: host, path: path.nil? ? "preflight.cfg" : path, explicit_path: !path.nil?)
+        source_interface = source_interface.dup.freeze if source_interface.is_a?(String)
+        unless source_interface.nil?
+          unless strategy.respond_to?(:validate_source_interface!)
+            raise ArgumentError, "source_interface is not supported by this TFTP strategy"
+          end
+          strategy.validate_source_interface!(target, source_interface: source_interface)
+        end
         strategy.validate_options!(target, source_file: source_file, vrf: vrf)
         @device.with_operation(:tftp_backup) do
           source = strategy.resolve_source_file(source_file)
           source = TftpTarget.validate_source_file!(source).dup.freeze unless source.nil?
           target = TftpTarget.new(host: target.host, path: strategy.default_path(source), explicit_path: false) if path.nil?
-          result = @device.execute_operation(strategy.script(target, source_file: source, vrf: vrf),
+          transfer_options = { source_file: source, vrf: vrf }
+          transfer_options[:source_interface] = source_interface unless source_interface.nil?
+          result = @device.execute_operation(strategy.script(target, **transfer_options),
                                              name: :tftp_backup, privilege: false)
           confirm_transfer!(strategy, target, result)
           # 一旦看到明确完成证据就保存回执；路径解析或用户钩子失败也不能抹去上传事实。

data/lib/net/connector/device/topology/audit.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "plan"
+require_relative "stages"
+
+module Net
+  module Connector
+    class Topology
+      # 逐接口区分可核实变更、未核实证据和只读平台；计划只包含明确获准的接口范围。
+      Audit = Data.define(:plan, :comparisons, :issues, :manual_required) do
+        def initialize(plan:, comparisons:, issues:, manual_required:)
+          raise ArgumentError, "audit plan must be a topology plan or nil" unless plan.nil? || plan.instance_of?(Plan)
+          unless [true, false].include?(manual_required) && comparisons.is_a?(Array) && issues.is_a?(Array)
+            raise ArgumentError, "invalid topology audit"
+          end
+          super(plan: plan, comparisons: copy_rows(comparisons), issues: copy_rows(issues), manual_required: manual_required)
+        end
+
+        def complete? = issues.empty?
+        def changes = comparisons.count { |entry| !%i[matches unverified].include?(entry[:status]) }
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
+        private
+
+        def copy_rows(rows)
+          rows.map do |row|
+            unless row.is_a?(Hash) && row.keys.all?(Symbol) && row.values.all? { |value| value.nil? || value.is_a?(String) || value.is_a?(Symbol) }
+              raise ArgumentError, "audit rows must contain scalar metadata"
+            end
+            row.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+          end.freeze
+        end
+      end
+
+      # 纯计划构造器不连接设备；协议命令仍由策略及 Stages 生成。
+      class AuditBuilder
+        def initialize(host:, vendor:, strategy:, neighbors:, descriptions:, formatter:)
+          @host, @vendor, @strategy = host, vendor, strategy
+          @neighbors, @descriptions, @formatter = neighbors, descriptions, formatter
+          @comparisons, @issues, @evidence, @changes = [], [], {}, []
+        end
+
+        def call
+          groups = @neighbors.group_by { |neighbor| @strategy.interface_key(neighbor.local_interface) }
+          groups.each { |interface, peers| inspect_interface(interface, peers) }
+          writable = @strategy.supports?(:interface_description_changes)
+          plan = build_plan if writable
+          Audit.new(plan: plan, comparisons: @comparisons, issues: @issues,
+                    manual_required: !writable && @comparisons.any? { |entry| entry[:status] != :matches })
+        end
+
+        private
+
+        def inspect_interface(interface, peers)
+          peer = peers.first
+          current = @descriptions[interface]
+          row = { interface: peer.local_interface, neighbor: peer.neighbor_name, port: peer.neighbor_interface,
+                  current: current, expected: nil, status: :unverified }
+          @comparisons << row
+          if peers.size != 1 || peer.neighbor_name.empty? || peer.neighbor_interface.empty?
+            return reject_interface(row, :ambiguous_neighbor)
+          end
+          return reject_interface(row, :interface_missing) unless @descriptions.key?(interface)
+
+          proposed = @formatter.call(peer)
+          InterfaceDescription.validate!(proposed)
+          local = @strategy.configuration_interface(peer.local_interface)
+          InterfaceDescription.validate_interface!(local)
+          row.merge!(expected: proposed, status: compare_status(current, proposed))
+          @evidence[interface] = [peer.neighbor_name, peer.neighbor_interface, current]
+          return if current == proposed
+
+          @changes << Change.new(interface: local, old_description: current, new_description: proposed, neighbor: peer)
+        rescue ArgumentError
+          reject_interface(row, :unsafe_description)
+        end
+
+        def reject_interface(row, code)
+          row[:reason] = code
+          @issues << { interface: row[:interface], code: code }
+          nil
+        end
+
+        def compare_status(current, proposed)
+          return :matches if current == proposed
+          return :missing_description if current.empty?
+
+          :content_mismatch
+        end
+
+        def build_plan
+          commands = if @changes.empty?
+                       []
+                     else
+                       Stages.build(strategy: @strategy, host: @host, changes: @changes).values.flat_map { |script| script.map(&:text) }
+                     end
+          Plan.new(host: @host, vendor: @vendor, evidence: @evidence, changes: @changes, commands: commands, scope: :interfaces)
+        end
+      end
+      private_constant :AuditBuilder
+    end
+  end
+end

data/lib/net/connector/device/topology/change.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "neighbor"
+
+module Net
+  module Connector
+    class Topology
+      # 变更的描述和接口归本对象所有；邻居值对象可安全共享。
+      Change = Data.define(:interface, :old_description, :new_description, :neighbor) do
+        def initialize(interface:, old_description:, new_description:, neighbor:)
+          fields = { interface: interface, old_description: old_description, new_description: new_description }
+          raise ArgumentError, "description change fields must be Strings" unless fields.values.all?(String)
+          raise ArgumentError, "description change requires a Neighbor" unless neighbor.instance_of?(Neighbor)
+
+          super(**fields.transform_values { |value| value.frozen? ? value : value.dup.freeze }, neighbor: neighbor)
+        end
+
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+      end
+    end
+  end
+end

data/lib/net/connector/device/topology/immediate_strategy.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "strategy"
+require_relative "interface_blocks"
 require_relative "../../engine/terminal/renderer"
 
 module Net
@@ -8,18 +9,11 @@ module Net
     class Topology
       # 接口描述立即生效的设备：退出视图、读回、保存是不同阶段，不能在 finish 中提前保存。
       class ImmediateStrategy < Strategy
+        include InterfaceBlocks
+
         def verification_commands = @device.config_commands
         def persistence_commands = @device.profile.save_commands
 
-        # TextFSM 不能静默跳过未知接口头；否则目标行正确也不足以证明读回证据完整。
-        def validate_descriptions!(config, rows)
-          expected = config.scan(/^interface[ \t]+([^\r\n]*)/).flatten.map(&:strip)
-          return if expected == rows.map { |row| row.fetch("INTERFACE").strip }
-
-          raise ParsingError.new("interface description output was not fully recognized", code: :unrecognized_output,
-                                 host: @device.host, phase: :verify)
-        end
-
         # 完成提示必须来自保存步骤；原文和渲染文本中的失败优先，单独提示符/进度不算确认。
         def persistence_confirmed?(result)
           !result.steps.empty? && result.steps.all? do |step|

data/lib/net/connector/device/topology/interface_blocks.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    class Topology
+      # interface 块方言共用完整性校验；解析器不能静默遗漏未知接口头。
+      module InterfaceBlocks
+        def validate_descriptions!(config, rows)
+          expected = config.scan(/^interface[ \t]+([^\r\n]*)/).flatten.map(&:strip)
+          return if expected == rows.map { |row| row.fetch("INTERFACE").strip }
+
+          raise ParsingError.new("interface description output was not fully recognized", code: :unrecognized_output,
+                                 host: @device.host, phase: :verify)
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/device/topology/neighbor.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    class Topology
+      # 邻居身份拥有独立字符串，格式化回调不能改写发现证据。
+      Neighbor = Data.define(:local_interface, :neighbor_name, :neighbor_interface, :chassis_id, :protocol) do
+        def initialize(local_interface:, neighbor_name:, neighbor_interface:, chassis_id:, protocol:)
+          fields = { local_interface: local_interface, neighbor_name: neighbor_name,
+                     neighbor_interface: neighbor_interface, chassis_id: chassis_id }
+          raise ArgumentError, "neighbor fields must be Strings" unless fields.values.all?(String)
+          raise ArgumentError, "neighbor protocol must be a Symbol" unless protocol.is_a?(Symbol)
+
+          super(**fields.transform_values { |value| value.frozen? ? value : value.dup.freeze }, protocol: protocol)
+        end
+
+        # Ruby 3.2 的 Data#with 不调用初始化，更新也必须重新建立快照。
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+      end
+    end
+  end
+end

data/lib/net/connector/device/topology/plan.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "change"
+
+module Net
+  module Connector
+    class Topology
+      # 审批树在领域边界固定；单设备与批量操作共享同一不可变计划。
+      Plan = Data.define(:host, :vendor, :evidence, :changes, :commands, :scope) do
+        def initialize(host:, vendor:, evidence:, changes:, commands:, scope: :device)
+          unless host.is_a?(String) && vendor.is_a?(Symbol) && evidence.is_a?(Hash) &&
+                 changes.is_a?(Array) && changes.all? { |change| change.instance_of?(Change) } &&
+                 commands.is_a?(Array) && commands.all?(String) && %i[device interfaces].include?(scope)
+            raise ArgumentError, "description plan contains invalid fields"
+          end
+
+          super(host: host.frozen? ? host : host.dup.freeze, vendor: vendor,
+                evidence: copy_evidence(evidence), changes: changes.dup.freeze,
+                commands: commands.map { |command| command.frozen? ? command : command.dup.freeze }.freeze, scope: scope)
+        end
+
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
+        private
+
+        def copy_evidence(evidence)
+          evidence.to_h do |interface, fields|
+            unless interface.is_a?(String) && fields.is_a?(Array) && fields.size == 3 && fields.all?(String)
+              raise ArgumentError, "description plan contains invalid evidence"
+            end
+
+            [interface.frozen? ? interface : interface.dup.freeze,
+             fields.map { |field| field.frozen? ? field : field.dup.freeze }.freeze]
+          end.freeze
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/device/topology/quoted_text.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require_relative "../../engine/errors"
+
+module Net
+  module Connector
+    class Topology
+      # 配置字段的引号解码是纯文本边界，不执行 shell，也不把原文写入错误。
+      module QuotedText
+        def self.decode(value, host:, split_unquoted: false)
+          value = value.strip
+          return value unless split_unquoted || value.start_with?('"')
+
+          Shellwords.split(value).join(" ")
+        rescue ArgumentError
+          raise ParsingError.new("interface description is not a complete single-line value",
+                                 code: :unrecognized_output, host: host, phase: :parse), cause: nil
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/device/topology/strategy.rb

@@ -2,6 +2,7 @@
 
 require "shellwords"
 require_relative "interface_description"
+require_relative "quoted_text"
 
 module Net
   module Connector
@@ -56,6 +57,9 @@ module Net
         # 在下发前允许厂商调整命令对象及超时。
         def script_command(command) = command
 
+        # 描述记录默认表示物理接口；厂商可保留逻辑单元的独立身份。
+        def description_key(row) = interface_key(row.fetch("INTERFACE"))
+
         # 将发现接口名归一为查找当前配置所用的键。
         def interface_key(name) = InterfaceName.key(name)
 

data/lib/net/connector/device/topology.rb

@@ -2,6 +2,8 @@
 
 require_relative "topology/strategy"
 require_relative "topology/stages"
+require_relative "topology/plan"
+require_relative "topology/audit"
 
 module Net
   module Connector
@@ -25,16 +27,17 @@ module Net
           Topology.new(self).plan_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
         end
 
+        # 核实各接口，保留缺失/冲突证据并为可确认的接口构造独立计划。
+        def audit_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+          Topology.new(self).audit_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
+        end
+
         # 明确确认且现场证据未变化时执行接口描述计划。
         def apply_interface_descriptions(plan, confirmed: false)
           Topology.new(self).apply_interface_descriptions(plan, confirmed: confirmed)
         end
       end
 
-      Neighbor = Data.define(:local_interface, :neighbor_name, :neighbor_interface, :chassis_id, :protocol)
-      Change = Data.define(:interface, :old_description, :new_description, :neighbor)
-      Plan = Data.define(:host, :vendor, :evidence, :changes, :commands)
-
       # 仅承载厂商档案的离线上下文，不能连接、查询或下发设备命令。
       PlanningContext = Data.define(:host, :vendor, :profile) do
         def config_commands = profile.config_commands
@@ -129,7 +132,7 @@ module Net
         rows = @parser.call(config, template: template, host: @device.host)
         @strategy.validate_descriptions!(config, rows)
         rows.each_with_object({}) do |row, found|
-          interface = @strategy.interface_key(row.fetch("INTERFACE"))
+          interface = @strategy.description_key(row)
           description = @strategy.decode_description(row.fetch("DESCRIPTION", ""))
           previous = found[interface]
           if previous && !previous.empty? && !description.empty? && previous != description
@@ -154,12 +157,22 @@ module Net
         end
       end
 
+      def audit_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+        unless [abbreviate, lowercase].all? { |value| value == true || value == false }
+          raise ArgumentError, "description formatting options must be boolean"
+        end
+        formatter ||= ->(peer) { InterfaceDescription.format(peer, abbreviate: abbreviate, lowercase: lowercase) }
+        @device.with_operation(:plan) do
+          AuditBuilder.new(host: @device.host, vendor: @device.vendor, strategy: @strategy,
+                           neighbors: neighbors, descriptions: interface_descriptions, formatter: formatter).call
+        end
+      end
+
       # 比对邻居和现有描述，生成包含确切命令的只读变更计划。
       def plan_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
         validate_change_support!(:plan) if @strategy.supports?(:neighbors)
         discovered = neighbors
         current = interface_descriptions
-        current.each_value(&:freeze)
         evidence = evidence_for(discovered, current)
         changes = discovered.filter_map do |neighbor|
           old = current.fetch(@strategy.interface_key(neighbor.local_interface))
@@ -171,17 +184,16 @@ module Net
           InterfaceDescription.validate!(proposed)
           next if old == proposed
 
-          Change.new(interface: @strategy.configuration_interface(neighbor.local_interface).freeze, old_description: old.freeze,
-                     new_description: proposed.freeze, neighbor: neighbor).freeze
+          Change.new(interface: @strategy.configuration_interface(neighbor.local_interface), old_description: old,
+                     new_description: proposed, neighbor: neighbor)
         end.freeze
         commands = if changes.empty?
                      []
                    else
                      stage_scripts(changes).values.flat_map { |script| script.map(&:text) }
                    end
-        commands.each(&:freeze)
-        Plan.new(host: @device.host.dup.freeze, vendor: @device.vendor, evidence: evidence,
-                 changes: changes, commands: commands.freeze).freeze
+        Plan.new(host: @device.host, vendor: @device.vendor, evidence: evidence,
+                 changes: changes, commands: commands)
       end
 
       # 只有明确确认且邻居和旧描述未变化时，才下发计划中的命令。
@@ -251,7 +263,12 @@ module Net
       # 重验失败仍在写入前直接抛异常，保持 stale_plan 的既有契约。
       def revalidate_plan!(plan)
         discovered = neighbors
-        evidence = evidence_for(discovered, interface_descriptions)
+        current = interface_descriptions
+        if plan.scope == :interfaces
+          discovered = discovered.select { |neighbor| plan.evidence.key?(@strategy.interface_key(neighbor.local_interface)) }
+          current = current.slice(*plan.evidence.keys)
+        end
+        evidence = evidence_for(discovered, current)
         current_neighbors = discovered.to_h { |neighbor| [@strategy.interface_key(neighbor.local_interface), neighbor] }
         same_neighbors = plan.changes.all? do |change|
           current_neighbors[@strategy.interface_key(change.interface)] == change.neighbor

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Net
+  module Connector
+    module Netdisco
+      # 精确地址用索引，网段和范围只保存端点；绝不展开地址或发起扫描。
+      class AddressFilter
+        def initialize(values)
+          raise ArgumentError, "host lists must be Arrays" unless values.is_a?(Array)
+
+          exact = {}
+          ranges = {}
+          values.each do |value|
+            raise ArgumentError, "host entries must be nonempty strings" unless value.is_a?(String) && !value.empty?
+
+            if value.include?("/") || value.split("%", 2).first.include?("-")
+              first, last = endpoints(value)
+              (ranges[first.family] ||= []) << [first.to_i, last.to_i]
+            else
+              exact[IPAddr.new(value).to_s.freeze] = true
+            end
+          end
+          @exact = exact.freeze
+          @ranges = ranges.transform_values { |items| merge_ranges(items) }.freeze
+          freeze
+        rescue IPAddr::Error
+          raise ArgumentError, "host entries must be IP addresses, networks or ordered ranges", cause: nil
+        end
+
+        def empty? = @exact.empty? && @ranges.empty?
+
+        def include?(host)
+          return false if empty?
+          return true if @exact.key?(host)
+          return false unless host.is_a?(String) && !host.empty?
+
+          address = IPAddr.new(host)
+          return true if @exact.key?(address.to_s)
+
+          intervals = @ranges[address.family]
+          return false unless intervals
+
+          value = address.to_i
+          interval = intervals.bsearch { |_, last| last >= value }
+          interval && interval.first <= value ? true : false
+        rescue IPAddr::Error
+          false
+        end
+
+        private
+
+        def endpoints(value)
+          if value.include?("/")
+            range = IPAddr.new(value).to_range
+            return [range.begin, range.end]
+          end
+          first, last = value.split("-", 2)
+          first = IPAddr.new(first)
+          if first.ipv4? && last&.match?(/\A\d+\z/)
+            last = first.to_s.rpartition(".").first + ".#{last}"
+          end
+          last = IPAddr.new(last)
+          unless first.family == last.family && first.to_i <= last.to_i && !(first.ipv6? && (first.zone_id || last.zone_id))
+            raise ArgumentError, "host ranges require ordered endpoints of the same address family", cause: nil
+          end
+          [first, last]
+        end
+
+        # 合并重叠范围，使每台设备匹配的成本不随网段大小增长。
+        def merge_ranges(items)
+          merged = []
+          items.sort.each do |first, last|
+            if !merged.empty? && first <= merged.last.last + 1
+              merged.last[1] = [merged.last.last, last].max
+            else
+              merged << [first, last]
+            end
+          end
+          merged.each(&:freeze).freeze
+        end
+      end
+    end
+  end
+end

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

@@ -15,9 +15,10 @@ module Net
           unless duration_ms.nil? || (duration_ms.is_a?(Numeric) && duration_ms.real? && duration_ms.finite? && duration_ms >= 0)
             raise ArgumentError, "duration_ms must be nonnegative and finite"
           end
+          raise ArgumentError, "status must be a Symbol or String" unless status.is_a?(Symbol) || status.is_a?(String)
           raise ArgumentError, "diagnostic must be a Diagnostic" unless diagnostic.nil? || diagnostic.instance_of?(Diagnostic)
 
-          super(device: device, status: status, backup: backup, error_code: error_code,
+          super(device: device, status: status.is_a?(String) ? status.dup.freeze : status, backup: backup, error_code: error_code,
                 error_type: error_type.is_a?(String) ? error_type.dup.freeze : error_type,
                 started_at: started_at&.dup&.freeze, finished_at: finished_at&.dup&.freeze,
                 duration_ms: duration_ms, diagnostic: diagnostic)
@@ -46,17 +47,45 @@ module Net
       # 汇总一次批量任务的设备结果、回调故障和报告写入状态。
       Batch = Data.define(:mode, :outcomes, :started_at, :finished_at, :callback_errors,
                           :report_location, :report_error) do
-        # 按设备最终状态统计数量。
-        def counts = outcomes.map(&:status).tally
+        # 批次拥有容器与审计元数据；调用方只能通过 with 构造新快照。
+        def initialize(mode:, outcomes:, started_at:, finished_at:, callback_errors:, report_location:, report_error:)
+          unless outcomes.is_a?(Array) && outcomes.all? { |outcome| outcome.instance_of?(Outcome) } && callback_errors.is_a?(Array)
+            raise ArgumentError, "batch requires outcome and callback error Arrays"
+          end
+
+          outcomes = outcomes.dup.freeze
+          @counts = outcomes.each_with_object({}) { |outcome, found| found[outcome.status] = found.fetch(outcome.status, 0) + 1 }.freeze
+          super(mode: mode, outcomes: outcomes,
+                started_at: started_at&.dup&.freeze, finished_at: finished_at&.dup&.freeze,
+                callback_errors: callback_errors.map { |entry| copy_callback_error(entry) }.freeze,
+                report_location: report_location&.dup&.freeze, report_error: report_error&.dup&.freeze)
+        end
+
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
+        # 只累计最终计数，不创建与清单等长的中间状态数组。
+        def counts = @counts.dup
 
         # 仅在所有设备成功且回调、报告均正常时判定整批成功。
-        def success? = !outcomes.empty? && outcomes.all?(&:success?) && callback_errors.empty? && report_error.nil?
+        def success? = !outcomes.empty? && @counts.fetch(:backed_up, 0) + @counts.fetch(:reported_uploaded, 0) == outcomes.size &&
+                       callback_errors.empty? && report_error.nil?
 
         # 空清单与已尝试但未全部成功的批次分别标记。
         def status = outcomes.empty? ? :no_devices : (success? ? :succeeded : :incomplete)
 
         # 显式从原始执行结果构造报告。
         def build_report(policy: :strict) = Report.new(self, policy: policy)
+
+        private
+
+        def copy_callback_error(entry)
+          unless entry.is_a?(Hash) && (entry[:host].nil? || entry[:host].is_a?(String))
+            raise ArgumentError, "callback errors must contain a host and error type"
+          end
+
+          { host: entry[:host]&.dup&.freeze, error_type: Error::Metadata.type(entry[:error_type]) }.freeze
+        end
+
       end
 
       autoload :Report, File.expand_path("report", __dir__)