net-connector 0.4.1 → 0.5.0

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

@@ -10,7 +10,13 @@ module Net
       class ConfigFile
         FIELDS = {
           "netdisco" => { "url" => ["NETDISCO_URL", :string],
-                          "page_size" => ["NETDISCO_PAGE_SIZE", :integer] },
+                          "page_size" => ["NETDISCO_PAGE_SIZE", :integer],
+                          "max_pages" => ["NETDISCO_MAX_PAGES", :integer],
+                          "max_response_bytes" => ["NETDISCO_MAX_RESPONSE_BYTES", :integer],
+                          "max_inventory_bytes" => ["NETDISCO_MAX_INVENTORY_BYTES", :integer],
+                          "max_devices" => ["NETDISCO_MAX_DEVICES", :integer],
+                          "inventory_timeout" => ["NETDISCO_INVENTORY_TIMEOUT", :number],
+                          "allow_insecure_http" => ["NETDISCO_ALLOW_INSECURE_HTTP", :boolean] },
           "backup" => { "directory" => ["NET_CONNECTOR_BACKUP_DIRECTORY", :string],
                         "concurrency" => ["NET_CONNECTOR_CONCURRENCY", :integer],
                         "limit_per_vendor" => ["NET_CONNECTOR_SAMPLE_PER_VENDOR", :integer] },
@@ -21,12 +27,16 @@ module Net
                            "host_overrides" => ["NET_CONNECTOR_HOST_OVERRIDES", :json],
                            "device_rules" => ["NET_CONNECTOR_DEVICE_RULES", :json] },
           "ssh" => { "protocol" => ["NET_CONNECTOR_PROTOCOL", :string],
+                     "max_script_output_bytes" => ["NET_CONNECTOR_MAX_SCRIPT_OUTPUT_BYTES", :optional_integer],
                      "known_hosts" => ["NET_CONNECTOR_KNOWN_HOSTS", :string],
                      "host_key_policy" => ["NET_CONNECTOR_HOST_KEY_POLICY", :string],
                      "log_directory" => ["NET_CONNECTOR_LOG_DIRECTORY", :string],
                      "log_level" => ["NET_CONNECTOR_LOG_LEVEL", :string] },
           "tftp" => { "server" => ["TFTP_HOST", :string],
-                      "vrfs" => ["NET_CONNECTOR_TFTP_VRFS", :json] }
+                      "vrfs" => ["NET_CONNECTOR_TFTP_VRFS", :json],
+                      "h3c_source_file" => ["NET_CONNECTOR_H3C_TFTP_SOURCE_FILE", :string],
+                      "h3c_wireless_source_file" => ["NET_CONNECTOR_H3C_WIRELESS_TFTP_SOURCE_FILE", :string],
+                      "huawei_source_file" => ["NET_CONNECTOR_HUAWEI_TFTP_SOURCE_FILE", :string] }
         }.freeze
 
         # 安全读取 YAML 配置并映射到环境变量格式。
@@ -52,7 +62,7 @@ module Net
             end
           end
         rescue Psych::Exception => error
-          raise ArgumentError, "invalid YAML config (#{error.class})"
+          raise ArgumentError, "invalid YAML config (#{error.class})", cause: nil
         end
 
         # 按字段类型校验并编码单项配置。
@@ -62,9 +72,21 @@ module Net
             raise ArgumentError, "#{section}.#{name} must be a nonempty String" unless value.is_a?(String) && !value.strip.empty?
 
             value
-          when :integer
+          when :integer, :optional_integer
+            return nil if type == :optional_integer && value.nil?
+
             raise ArgumentError, "#{section}.#{name} must be a positive Integer" unless value.is_a?(Integer) && value.positive?
 
+            value.to_s
+          when :number
+            unless value.is_a?(Numeric) && value.real? && value.finite? && value.positive? && value.to_f.finite?
+              raise ArgumentError, "#{section}.#{name} must be a positive finite number"
+            end
+
+            value.to_s
+          when :boolean
+            raise ArgumentError, "#{section}.#{name} must be true or false" unless [true, false].include?(value)
+
             value.to_s
           when :list
             unless value.is_a?(Array) && value.all? { |item| item.is_a?(String) && !item.empty? && !item.include?(",") }

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "ipaddr"
-require_relative "../operations/saved_config"
+require_relative "../storage/saved_config"
 
 module Net
   module Connector
@@ -44,7 +44,7 @@ module Net
         def ready? = issue.nil?
 
         # 生成不随名称或厂商信息改变的本地文本文件名。
-        def backup_filename = Operations::SavedConfig.filename(host)
+        def backup_filename = Storage::SavedConfig.filename(host)
 
         # 生成设备 CLI 可用的 ASCII 远端文件名。
         def tftp_filename
@@ -53,13 +53,12 @@ module Net
                       .gsub(/\A[._-]+|[._-]+\z/, "")
           label = vendor&.to_s || "device" if label.empty?
           strategy = Net::Connector.vendor_class(vendor).profile.tftp_strategy if vendor
-          # 旧版自定义策略只需实现实例接口，缺少命名接口时沿用通用 cfg 名称。
-          strategy = Operations::Tftp::Strategy unless strategy.respond_to?(:filename)
+          raise UnsupportedOperation, "device has no TFTP strategy" unless strategy
           TftpTarget.validate_path!(strategy.filename(host, label: label))
         end
 
         # 按厂商及设备地址实例化连接器。
-        def connector(**settings)
+        def build_connector(**settings)
           raise ArgumentError, "device is not ready: #{issue}" unless ready?
           raise ArgumentError, "host cannot be overridden" if settings.key?(:host)
 

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "../engine/error_metadata"
+
+module Net
+  module Connector
+    module Netdisco
+      # 报告是新的诊断通道：只接受固定词表，不展开异常消息、调用栈、命令、source 或 line。
+      Diagnostic = Data.define(:error_code, :error_type, :phase, :underlying_type,
+                               :artifact_state, :artifact_phase, :verification)
+
+      class Diagnostic
+        ARTIFACT_STATES = %i[not_committed committed durable reported_uploaded].freeze
+        ARTIFACT_PHASES = %i[resolve_parent temporary_file write file_sync rename directory_open directory_sync
+                            cleanup complete path finalize].freeze
+        private_constant :ARTIFACT_STATES, :ARTIFACT_PHASES
+
+        # 包括手工构造的结果在内，v2 都不能携带自由文本诊断值。
+        def initialize(error_code: nil, error_type: nil, phase: nil, underlying_type: nil,
+                       artifact_state: nil, artifact_phase: nil, verification: nil)
+          super(error_code: ErrorMetadata.code(error_code),
+                error_type: ErrorMetadata.type(error_type), phase: ErrorMetadata.phase(phase),
+                underlying_type: ErrorMetadata.type(underlying_type),
+                artifact_state: ARTIFACT_STATES.include?(artifact_state) ? artifact_state : nil,
+                artifact_phase: ARTIFACT_PHASES.include?(artifact_phase) ? artifact_phase : nil,
+                verification: verification == :device_reported ? verification : nil)
+        end
+
+        # 读取已知错误的白名单属性后立即丢弃异常引用，不把回调对象保留进批次。
+        def self.from(error, backup: nil, phase: nil)
+          return unless error
+
+          fields = { error_type: ErrorMetadata.type(error.class.name) || "StandardError", phase: phase }
+          if error.is_a?(Net::Connector::Error)
+            fields.merge!(error_code: error.code, phase: phase || error.phase)
+            fields[:underlying_type] = error.underlying.type if error.underlying.instance_of?(UnderlyingError)
+          end
+          new(**fields.merge(completion_fields(error, backup, phase)))
+        rescue StandardError
+          new(error_type: "StandardError", phase: phase)
+        end
+
+        def self.completion_fields(error, backup, phase)
+          if error.instance_of?(BackupPersistenceError) && backup.instance_of?(Backup) && error.backup.equal?(backup)
+            { artifact_state: error.receipt.state, artifact_phase: error.receipt.phase,
+              underlying_type: error.underlying_type }
+          elsif error.instance_of?(TftpCompletionError) && backup.instance_of?(TftpReceipt) && error.receipt.equal?(backup)
+            { artifact_state: :reported_uploaded, artifact_phase: error.code == :transfer_finalize_failed ? :finalize : :path,
+              verification: :device_reported, underlying_type: error.underlying_type }
+          elsif phase == :report && Storage::PrivateFile.receipt_error?(error)
+            { error_code: error.code, artifact_state: error.receipt.state, artifact_phase: error.receipt.phase,
+              underlying_type: error.underlying_type }
+          else
+            {}
+          end
+        end
+        private_class_method :completion_fields
+      end
+    end
+  end
+end

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

@@ -8,101 +8,130 @@ module Net
     module Netdisco
       # 基于已验证的清单快照组织有上限的并发备份。
       class Fleet
+        DEFAULT_SETTING = Object.new.freeze
+        private_constant :DEFAULT_SETTING
+
         # 组装清单客户端、规则、凭据与结果存储。
         def initialize(client: nil, settings: Settings.new, rules: nil, credentials: nil, connector_factory: nil,
                        result_store: ResultStore::Text.new)
           @settings = settings
-          @client = client || settings.client
-          @rules = rules || settings.rules
-          @credentials = credentials || settings.method(:credentials_for)
-          @connector_factory = connector_factory || ->(device, connection_settings) { device.connector(**connection_settings) }
+          @client = client
+          @rules = rules
+          @credentials = credentials
+          @connector_factory = connector_factory || ->(device, connection_settings) { device.build_connector(**connection_settings) }
           @result_store = result_store
-          raise ArgumentError, "credentials must respond to call" unless @credentials.respond_to?(:call)
+          raise ArgumentError, "credentials must respond to call" if @credentials && !@credentials.respond_to?(:call)
           raise ArgumentError, "result_store must respond to write" if result_store && !result_store.respond_to?(:write)
         end
 
         # 拉取并标记重复管理地址的设备清单。
         def devices
-          rows = @client.devices
-          raise Client::Error, "Netdisco returned an invalid device inventory" unless rows.is_a?(Array)
-
-          devices = rows.map { |row| Device.from_row(row, rules: @rules) }
-          duplicates = devices.group_by(&:host).reject { |host, entries| host.nil? || entries.size == 1 }
-          devices.map do |device|
-            duplicates.key?(device.host) ? device.with(issue: :duplicate_host) : device
-          end.freeze
+          inventory(@settings.snapshot(mode: :inventory))
         end
 
         # 规划本地配置备份的设备集合。
         def plan_backup(limit_per_vendor: nil)
-          Planner.new(devices).call(mode: :backup, limit_per_vendor: limit_per_vendor)
+          build_plan(:backup, limit_per_vendor, @settings.snapshot(mode: :backup))
         end
 
         # 规划 TFTP 配置备份的设备集合。
         def plan_tftp_backup(limit_per_vendor: 5)
-          Planner.new(devices).call(mode: :tftp, limit_per_vendor: limit_per_vendor)
+          build_plan(:tftp, limit_per_vendor, @settings.snapshot(mode: :tftp))
         end
 
         # 先拉取完整清单，再并发采集并保存设备配置。
-        def backup_all(directory: @settings.backup_directory, concurrency: @settings.concurrency,
-                       limit_per_vendor: nil, plan: nil, on_start: nil, on_result: nil, on_change: nil)
+        def backup_all(directory: DEFAULT_SETTING, concurrency: DEFAULT_SETTING,
+                       limit_per_vendor: nil, plan: nil, on_start: nil, on_result: nil, on_change: nil,
+                       success_policy: :strict)
+          reporting = Report.validate_policy!(success_policy)
+          policy = @settings.snapshot(mode: :backup)
+          directory = policy.backup_directory if directory.equal?(DEFAULT_SETTING)
+          concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
           raise ArgumentError, "directory must be a nonempty String" unless directory.is_a?(String) && !directory.empty?
+          Worker.new(concurrency: concurrency)
           Planner.validate_limit!(limit_per_vendor)
           validate_callback!(on_result, :on_result)
           validate_callback!(on_start, :on_start)
           validate_callback!(on_change, :on_change)
 
-          plan ||= plan_backup(limit_per_vendor: limit_per_vendor)
+          plan ||= build_plan(:backup, limit_per_vendor, policy)
           validate_plan!(plan, :backup)
           callbacks = [on_result]
           callbacks << ->(item) { on_change.call(item) if item.backup.is_a?(Backup) && item.backup.changed? } if on_change
           target_directory = File.expand_path(directory)
           run_batch(:backup, plan, concurrency: concurrency, report_directory: directory,
-                   output_directory: target_directory, on_start: on_start, on_result: callbacks.compact) do |device, log_directory|
-            backup_one(device, target_directory, log_directory)
+                    output_directory: target_directory, policy: policy, reporting: reporting,
+                    on_start: on_start, on_result: callbacks.compact) do |device, log_directory|
+            backup_one(device, target_directory, log_directory, policy)
           end
         end
 
         # 让设备主动导出配置，在执行前检查同批目标文件名冲突。
-        def tftp_backup_all(server:, source_files: {}, concurrency: @settings.concurrency,
+        def tftp_backup_all(server:, source_files: {}, concurrency: DEFAULT_SETTING,
                             limit_per_vendor: 5, vrfs: {}, on_start: nil, on_result: nil, plan: nil,
-                            report_directory: @settings.backup_directory)
-          TftpTarget.new(host: server, path: "preflight.cfg")
+                            report_directory: DEFAULT_SETTING, success_policy: :strict)
+          reporting = Report.validate_policy!(success_policy)
+          policy = @settings.snapshot(mode: :tftp)
+          concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
+          report_directory = policy.backup_directory if report_directory.equal?(DEFAULT_SETTING)
+          Worker.new(concurrency: concurrency)
+          server = TftpTarget.new(host: server, path: "preflight.cfg").host
           raise ArgumentError, "source_files must be a Hash" unless source_files.is_a?(Hash)
           source_files.each_value { |source_file| TftpTarget.validate_source_file!(source_file) }
-          validate_vrfs!(vrfs)
+          source_files = source_files.transform_values { |value| value.dup.freeze }.freeze
+          vrfs = Settings.validate_vrfs!(vrfs).transform_values { |value| value.dup.freeze }.freeze
           Planner.validate_limit!(limit_per_vendor)
           validate_callback!(on_result, :on_result)
           validate_callback!(on_start, :on_start)
 
-          plan ||= plan_tftp_backup(limit_per_vendor: limit_per_vendor)
+          plan ||= build_plan(:tftp, limit_per_vendor, policy)
           validate_plan!(plan, :tftp)
           run_batch(:tftp, plan, concurrency: concurrency, report_directory: report_directory,
-                    on_start: on_start, on_result: on_result) do |device, log_directory|
-            tftp_backup_one(device, server, source_files, log_directory, vrfs)
+                    policy: policy, reporting: reporting, on_start: on_start, on_result: on_result) do |device, log_directory|
+            tftp_backup_one(device, server, source_files, log_directory, vrfs, policy)
           end
         end
 
         private
 
+        # 策略在清单请求之前固定；注入的清单客户端仍由调用方负责其自身生命周期。
+        def inventory(policy)
+          rows = (@client || @settings.client(policy: policy)).devices
+          raise Client::Error, "Netdisco returned an invalid device inventory" unless rows.is_a?(Array)
+
+          rules = @rules || policy.rules
+          devices = rows.map { |row| Device.from_row(row, rules: rules) }
+          duplicates = devices.group_by(&:host).reject { |host, entries| host.nil? || entries.size == 1 }
+          devices.map { |device| duplicates.key?(device.host) ? device.with(issue: :duplicate_host) : device }.freeze
+        end
+
+        def build_plan(mode, limit, policy)
+          Planner.validate_limit!(limit)
+          Planner.new(inventory(policy)).call(mode: mode, limit_per_vendor: limit)
+        end
+
         # 统一组织设备任务、日志目录与报告；Worker 保证单台设备失败不影响其他设备。
-        def run_batch(mode, plan, concurrency:, report_directory:, on_start:, on_result:, output_directory: nil)
+        def run_batch(mode, plan, concurrency:, report_directory:, policy:, reporting:, on_start:, on_result:, output_directory: nil)
           worker = Worker.new(concurrency: concurrency)
           started_at = Time.now.utc
+          started = monotonic
           outcomes = plan.outcomes.dup
           FileUtils.mkdir_p(output_directory, mode: 0o700) if output_directory && !plan.ready.empty?
-          log_directory = @settings.log_directory
+          log_directory = policy.log_directory
           FileUtils.mkdir_p(log_directory, mode: 0o700) if log_directory && !plan.ready.empty?
           callback_errors = worker.run(plan.ready, outcomes: outcomes, on_start: on_start, on_result: on_result,
-                                       on_error: ->(device, error) { outcome(device, :failed, error: error) }) do |device|
+                                       on_error: ->(device, error) { build_outcome(device, :failed, error: error) }) do |device|
             yield device, log_directory
           end
           batch = Batch.new(mode: mode, outcomes: outcomes.freeze, started_at: started_at,
                             finished_at: Time.now.utc, callback_errors: callback_errors,
                             report_location: nil, report_error: nil)
+          batch = Report.new(batch, policy: reporting, duration_ms: ((monotonic - started) * 1000).round)
           save_report(batch, directory: report_directory)
         end
 
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         # 校验批量任务回调接口。
         def validate_callback!(callback, name)
           raise ArgumentError, "#{name} must respond to call" if callback && !callback.respond_to?(:call)
@@ -113,18 +142,12 @@ module Net
           return batch unless @result_store
 
           batch.with(report_location: @result_store.write(batch, directory: directory))
+        rescue Storage::PrivateFile::WriteError => error
+          # 报告也可能已经原子替换；保留已知位置，不将持久性失败误写成完全没有产物。
+          location = error.receipt.path if Storage::PrivateFile.receipt_error?(error) && error.receipt.committed?
+          batch.with_report_error(error, location: location)
         rescue StandardError => error
-          batch.with(report_error: error.class.name)
-        end
-
-        # 校验厂商 VRF 映射和名称。
-        def validate_vrfs!(vrfs)
-          unless vrfs.is_a?(Hash) && vrfs.all? { |vendor, value|
-            %i[cisco_nxos hillstone].include?(vendor) && value.is_a?(String) &&
-              value.match?(/\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/)
-          }
-            raise ArgumentError, "vrfs must map supported vendor names to safe VRF names"
-          end
+          batch.with_report_error(error)
         end
 
         # 确认传入计划属于当前备份模式。
@@ -135,16 +158,16 @@ module Net
         end
 
         # 构造包含错误类型的单台设备结果。
-        def outcome(device, status, backup: nil, error: nil)
+        def build_outcome(device, status, backup: nil, error: nil)
           Outcome.new(device: device, status: status, backup: backup,
                       error_code: error.respond_to?(:code) ? error.code : nil,
-                      error_type: error&.class&.name)
+                      error_type: error&.class&.name, diagnostic: Diagnostic.from(error, backup: backup))
         end
 
         # 执行单台设备的 TFTP 导出。
-        def tftp_backup_one(device, server, source_files, log_directory, vrfs)
-          run_one(device, log_directory, success_status: :reported_uploaded,
-                  close_error_status: :reported_with_error, backup_class: TftpBackup) do |connector|
+        def tftp_backup_one(device, server, source_files, log_directory, vrfs, policy)
+          run_one(device, log_directory, policy, success_status: :reported_uploaded,
+                  close_error_status: :reported_with_error, backup_class: TftpReceipt) do |connector|
             source_file = source_files.fetch(device.vendor, nil)
             transfer_settings = { host: server, path: device.tftp_filename, source_file: source_file }
             transfer_settings[:vrf] = vrfs.fetch(device.vendor) if vrfs.key?(device.vendor)
@@ -153,46 +176,57 @@ module Net
         end
 
         # 执行单台设备的本地配置采集。
-        def backup_one(device, directory, log_directory)
+        def backup_one(device, directory, log_directory, policy)
           destination = File.join(directory, device.backup_filename)
-          previous = Operations::SavedConfig.new(directory: directory).find(device.host, required: false)
-          previous_digest = Digest::SHA256.file(previous).hexdigest if previous && previous != destination
-          run_one(device, log_directory, success_status: :backed_up,
-                  close_error_status: :saved_with_error, backup_class: Backup) do |connector|
-            backup = connector.backup(path: destination)
-            if backup.is_a?(Backup) && backup.change == :created && previous_digest
-              backup.with(previous_sha256: previous_digest,
-                          change: backup.sha256 == previous_digest ? :unchanged : :changed)
-            else
-              backup
+          Storage::BackupLock.synchronize(destination, host: device.host) do |path_lock|
+            Storage::SafeFile.open(destination, missing: true) { |_file, _stat| nil }
+            run_one(device, log_directory, policy, success_status: :backed_up,
+                    close_error_status: :saved_with_error, backup_class: Backup) do |connector|
+              path_lock.with_delegated_lock { connector.backup(path: destination) }
             end
           end
         end
 
         # 隔离单台设备的凭据、连接、操作和关闭异常。
-        def run_one(device, log_directory, success_status:, close_error_status:, backup_class:)
-          connection_settings = @credentials.call(device)
-          return outcome(device, :missing_credentials) if connection_settings.nil?
+        def run_one(device, log_directory, policy, success_status:, close_error_status:, backup_class:)
+          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) &&
                  connection_settings[:username].is_a?(String) && !connection_settings[:username].empty? &&
                  !connection_settings.key?(:host)
             raise ArgumentError, "credential resolver must return settings with username and without host"
           end
 
+          connection_settings = policy.connection_options(device.vendor).merge(connection_settings)
           log_name = device.host.tr(":", "_")
           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 }
+          return build_outcome(device, success_status, backup: backup) unless failure
+
+          build_outcome(device, backup ? close_error_status : :failed, backup: backup, error: failure)
+        rescue StandardError => error
+          build_outcome(device, :failed, error: error)
+        end
+
+        # 仅信任库定义且产物类型匹配的提交后错误；普通第三方异常上的 backup 字段不代表完成。
+        def perform_one(connector, backup_class)
           backup = nil
           failure = nil
           begin
-            result = yield connector
+            result = yield
             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
@@ -200,11 +234,7 @@ module Net
               failure ||= error
             end
           end
-          return outcome(device, success_status, backup: backup) unless failure
-
-          outcome(device, backup ? close_error_status : :failed, backup: backup, error: failure)
-        rescue StandardError => error
-          outcome(device, :failed, error: error)
+          [backup, failure]
         end
       end
     end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    module Netdisco
+      # 每次 devices 调用独占一个预算，认证、分页和兼容查询不得重置已用资源或期限。
+      class InventoryBudget
+        def initialize(options, clock:)
+          @options = options
+          @clock = clock
+          @deadline = @clock.call + options.fetch(:inventory_timeout)
+          @bytes = 0
+          @devices = 0
+        end
+
+        def remaining
+          seconds = @deadline - @clock.call
+          raise Client::InventoryTimeout, cause: nil if seconds <= 0
+
+          seconds
+        end
+
+        # 在追加正文前计数；不能靠 Content-Length 或 JSON 解析后的大小限制内存。
+        def consume_bytes(size, response_bytes:)
+          remaining
+          check_limit!(:max_response_bytes, response_bytes + size)
+          check_limit!(:max_inventory_bytes, @bytes + size)
+          @bytes += size
+        end
+
+        # 去重前的记录同样占用清单内存；兼容查询也使用这个累计计数。
+        def consume_devices(size)
+          remaining
+          check_limit!(:max_devices, @devices + size)
+          @devices += size
+        end
+
+        private
+
+        def check_limit!(name, value)
+          return if value <= @options.fetch(name)
+
+          raise Client::Error.new("Netdisco inventory exceeded #{name}", code: name), cause: nil
+        end
+      end
+      private_constant :InventoryBudget
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "batch"
+
+module Net
+  module Connector
+    module Netdisco
+      # 唯一的批量报告契约，分开呈现成功策略、清单覆盖和受控诊断。
+      class Report
+        extend Forwardable
+        SUCCESS = %i[backed_up reported_uploaded].freeze
+        ATTEMPTED = [*SUCCESS, :failed, :saved_with_error, :reported_with_error].freeze
+        IGNORABLE = %i[filtered sample_limit].freeze
+        private_constant :SUCCESS, :ATTEMPTED, :IGNORABLE
+
+        attr_reader :batch, :policy, :duration_ms, :report_diagnostic
+        def_delegators :@batch, *Batch.members, :success?, :status, :counts
+
+        def self.validate_policy!(policy)
+          raise ArgumentError, "success_policy must be strict or selected" unless %i[strict selected].include?(policy)
+
+          policy
+        end
+
+        def initialize(batch, policy: :strict, duration_ms: nil, report_diagnostic: nil)
+          self.class.validate_policy!(policy)
+          raise ArgumentError, "report requires a Batch" unless batch.instance_of?(Batch)
+          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
+          unless report_diagnostic.nil? || report_diagnostic.instance_of?(Diagnostic)
+            raise ArgumentError, "report_diagnostic must be a Diagnostic"
+          end
+
+          @batch, @policy, @duration_ms, @report_diagnostic = batch, policy, duration_ms, report_diagnostic
+          freeze
+        end
+
+        # 严格完成情况与所选成功策略分别保留，未知状态不能当作可忽略跳过。
+        def policy_success?
+          return batch.success? if policy == :strict
+          return false unless callback_errors.empty? && report_error.nil?
+
+          outcomes.any? { |item| SUCCESS.include?(item.status) } &&
+            outcomes.all? { |item| SUCCESS.include?(item.status) || IGNORABLE.include?(item.status) }
+        end
+
+        def with(**attributes)
+          self.class.new(batch.with(**attributes), policy: policy, duration_ms: duration_ms,
+                          report_diagnostic: report_diagnostic)
+        end
+
+        def with_report_error(error, location: nil)
+          diagnostic = Diagnostic.from(error, phase: :report)
+          self.class.new(batch.with(report_location: location, report_error: diagnostic.error_type),
+                          policy: policy, duration_ms: duration_ms, report_diagnostic: diagnostic)
+        end
+
+        # 手工构造的批次同样经过诊断白名单，不序列化任意异常内容。
+        def summary
+          data = batch_summary
+          data.merge(
+            schema_version: 2, policy: policy, policy_success: policy_success?, duration_ms: duration_ms,
+            coverage: { complete: !outcomes.empty? && outcomes.all? { |item| ATTEMPTED.include?(item.status) },
+                        attempted: outcomes.count { |item| ATTEMPTED.include?(item.status) },
+                        skipped: outcomes.count { |item| !ATTEMPTED.include?(item.status) } },
+            devices: device_summaries(data.fetch(:devices)),
+            callback_errors: callback_errors.map { |entry| { host: entry[:host], error_type: ErrorMetadata.type(entry[:error_type]) } },
+            report_location: report_location, report_error: ErrorMetadata.type(report_error),
+            report_diagnostic: report_diagnostic&.to_h
+          )
+        end
+
+        def inspect = "#<#{self.class} policy=#{policy} status=#{status} policy_success=#{policy_success?}>"
+
+        private
+
+        # 生成可写入报告及供命令行展示的结构化摘要。
+        def batch_summary
+          {
+            mode: mode, status: status, started_at: started_at.iso8601, finished_at: finished_at.iso8601,
+            total: outcomes.size,
+            succeeded: outcomes.count(&:success?),
+            partial: outcomes.count(&:partial?),
+            failed: outcomes.count { |item| item.status == :failed },
+            skipped: outcomes.count(&:skipped?),
+            counts: counts,
+            callback_errors: callback_errors,
+            devices: outcomes.map do |item|
+              { host: item.device.host || item.device.source_ip, name: item.device.name,
+                vendor: item.device.vendor,
+                status: item.status, path: item.backup&.path,
+                bytes: item.backup.is_a?(Backup) ? item.backup.bytes : nil,
+                sha256: item.backup.is_a?(Backup) ? item.backup.sha256 : nil,
+                change: item.backup.is_a?(Backup) ? item.backup.change : nil,
+                previous_sha256: item.backup.is_a?(Backup) ? item.backup.previous_sha256 : nil,
+                started_at: item.started_at&.iso8601, finished_at: item.finished_at&.iso8601,
+                duration_ms: item.duration_ms,
+                error_code: item.error_code, error_type: item.error_type }
+            end
+          }
+        end
+
+        def device_summaries(entries)
+          entries.zip(outcomes).map do |entry, item|
+            diagnostic = item.diagnostic || Diagnostic.new(error_code: item.error_code, error_type: item.error_type)
+            entry.merge(error_code: diagnostic.error_code, error_type: diagnostic.error_type,
+                        diagnostic: diagnostic.to_h.except(:error_code, :error_type))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 require "json"
 require "fileutils"
 require "securerandom"
-require_relative "../operations/private_file"
+require_relative "../storage/private_file"
 
 module Net
   module Connector
@@ -17,7 +17,7 @@ module Net
             FileUtils.mkdir_p(destination, mode: 0o700)
             filename = "netdisco-#{batch.mode}-#{batch.started_at.strftime("%Y%m%dT%H%M%SZ")}-#{SecureRandom.hex(4)}.json"
             path = File.join(destination, filename)
-            Operations::PrivateFile.write(path, JSON.pretty_generate(batch.summary))
+            Storage::PrivateFile.write(path, JSON.pretty_generate(batch.summary)).path
           end
         end