vxlan 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c96781edce4b5dcc8990ced65d1287cfb86ee2c431ee3c0b0714365513955d75
-  data.tar.gz: '0187135b1f3cff8988732b9fb3ed58633e780b3538b569b1ea611f87d09af08a'
+  metadata.gz: 3a0904488ebdedf6f5983003bf51724e3e0c5442b2347fb6433041da8f858394
+  data.tar.gz: 8c1b2e0ba07891754cb6074e5da60a2174b6a96508309836bdc4db333ce7414e
 SHA512:
-  metadata.gz: a5386c55fa4f48e6e121ac63dbca3c8148754857df0fa68841d345301aadf6f1678dc682d86713030110203de4fc8f7f22ed2d2fbb44135bebb9e39157df6386
-  data.tar.gz: 5c1434eb7eac8ea5649e136523020579c1abf6d0ae57309ee20335989c164922789e70ca62322d55de1775752eb5902b805c50ef80d7cf48151e1968a449d3fe
+  metadata.gz: a51c259e1059d12babf19d1789e6ae9e3dba5fdaae8b612aad552aca488665b44f2ca2d25e7cec825b781b39ad8b887ee5c71b648a12da03fd6dc4b5f3d7561a
+  data.tar.gz: 6d37d517bcc3d7c8e8f143917449bbe450d2f79c54ca64c9032ace956f8db265ed86fbb4ee6e76f4fdf88ea68f74155408cecbf0f14aee20f5e297818b82f07e

data/CHANGELOG.md

@@ -4,6 +4,10 @@ Changes to the public contract are recorded here. Versions follow Semantic Versi
 
 ## Unreleased
 
+## 0.8.0 (2026-10-30)
+
+- Adopt schema 4 Target/Source contracts and shared configuration read/write sessions. Validate target platform before opening a connector. Normalize BGP to `peer_address`, `afi_safi`, `received_prefixes` and symbolic states; CDP uses `local_interface`, `remote_interface`, `remote_name`. Require connector 0.21 for collection.
+
 ## 0.7.0 (2026-10-29)
 
 - Compose the shared snapshot contract and remove the synthetic collection observation. Whitelist public target identities and validate timestamps and dimensions.

data/README.md

@@ -146,8 +146,12 @@ Offline review requires `snapshot.target.host` to match the canonical device hos
 
 ## API migration
 
-`RuntimeParser.new(platform:, model: nil)` fixes the platform for `parse(name, text, complete: false, command: nil)` and `parse_many(names, text, complete: false, command: nil)`. Snapshots use `observations:` and expose `observations` / `observation(name)`; the old Ruby `dimensions` member and Wireless `dimension` accessor are removed. Known missing dimensions return `not_requested`; unknown names raise `ArgumentError`. Persisted schema 3 JSON uses `observations` and an independent `collection_status`; regenerate older reports.
+`RuntimeParser.new(platform:, model: nil)` fixes the platform for `parse(name, text, complete: false, command: nil)` and `parse_many(names, text, complete: false, command: nil)`. Snapshots use `observations:` and expose `observations` / `observation(name)`; the old Ruby `dimensions` member and Wireless `dimension` accessor are removed. Known missing dimensions return `not_requested`; unknown names raise `ArgumentError`. Persisted schema 4 JSON uses `observations` and an independent `collection_status`; regenerate older reports.
 
 Dynamic inventory uses `Netdisco::Catalog`. Any duplicate row for a selected address, including another platform, prevents connection; excluded conflicts retain safe diagnostics. `NC_<PLATFORM>_ENABLE_PASSWORD` takes precedence over `NC_ENABLE_PASSWORD`.
 
 本次契约升级要求重新生成旧报告和计划；Ruby 快照使用 `observations`、`collection_status` 和 `Time`，JSON 通过 `CtxRunner::Document` 输出 UTC ISO8601（解析基础库仅提供 `Result`）。跨模块约定见 [ctx_runner 契约迁移](https://github.com/gatework/ctx_runner/blob/main/docs/contracts-2026-10-29.md)。
+
+## Domain contract migration (2026-10-30)
+
+Adopt schema 4 Target/Source contracts and shared configuration read/write sessions. Validate target platform before opening a connector. Normalize BGP to `peer_address`, `afi_safi`, `received_prefixes` and symbolic states; CDP uses `local_interface`, `remote_interface`, `remote_name`. Require connector 0.21 for collection. See the [schema 4 migration and module contracts](https://github.com/gatework/ctx_runner/blob/main/docs/contracts-2026-10-30.md). Regenerate old collection reports and change plans; changing only their version number is not supported.

data/lib/vxlan/cisco_nxos/parsers/show_bgp_l2vpn_evpn_summary.rb

@@ -8,13 +8,13 @@ module Vxlan
       # 从 BGP 汇总解析 EVPN 邻居状态及可选路由类型统计。
       class ShowBgpL2vpnEvpnSummary < Parser
         EMPTY = "(?:BGP )?neighbors"
-        IDENTITY = %i[vrf address_family peer_ip].freeze
+        IDENTITY = %i[vrf afi_safi peer_address].freeze
         BOUNDARY = /^\s*BGP summary information for VRF /
         SCOPE = /\ABGP summary information for VRF (\S+), address family (.+)\z/
         ROUTER = /\ABGP router identifier (\S+), local AS number (\S+)\z/
         HEADER = /\ANeighbor\s+V\s+AS\s+MsgRcvd\s+MsgSent\s+TblVer\s+InQ\s+OutQ\s+Up\/Down\s+State\/PfxRcd\z/i
         ROW = /\A([\da-f:.]+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.+)\z/i
-        FIELDS = %i[peer_ip version remote_as messages_received messages_sent table_version input_queue output_queue uptime state].freeze
+        FIELDS = %i[peer_address version remote_as messages_received messages_sent table_version input_queue output_queue uptime state].freeze
         INTEGERS = %i[version remote_as messages_received messages_sent table_version input_queue output_queue].freeze
         PREFIX_TYPES = %i[type1 type2 type3 type4 type5 type6 type7 type8 type12].freeze
         TABLE = /\ABGP table version is \d+(?:, L2VPN EVPN config peers (\d+), capable peers (\d+))?\z/i
@@ -29,7 +29,7 @@ module Vxlan
           scope, identities, invalid = nil, {}, {}
           text.each_line("\n") do |line|
             if (match = SCOPE.match(line.strip))
-              scope = match.captures
+              scope = [ match[1], match[2] == "L2VPN EVPN" ? "l2vpn_evpn" : match[2] ]
             elsif (match = ROUTER.match(line.strip))
               identity = router_identity(match)
               if !identity
@@ -42,10 +42,10 @@ module Vxlan
             end
           end
           invalid.each do |key, code|
-            issue = { code: code, vrf: key&.first, address_family: key&.last }
+            issue = { code: code, vrf: key&.first, afi_safi: key&.last }
             @issues << issue unless @issues.include?(issue)
           end
-          @rows.reject! { |row| invalid.key?(row.values_at(:vrf, :address_family)) }
+          @rows.reject! { |row| invalid.key?(row.values_at(:vrf, :afi_safi)) }
         end
 
         # ASDOT 与 ASPLAIN 用同一数值比较；无效身份不能附着到完整邻居事实。
@@ -67,8 +67,8 @@ module Vxlan
               @header = true
               prefix_columns = nil
             elsif (match = SCOPE.match(line))
-              scope = { vrf: match[1], address_family: match[2] }
-              unparsed_records(number) unless scope[:address_family] == "L2VPN EVPN"
+              scope = { vrf: match[1], afi_safi: match[2] == "L2VPN EVPN" ? "l2vpn_evpn" : match[2] }
+              unparsed_records(number) unless scope[:afi_safi] == "l2vpn_evpn"
               prefix_columns = nil
             elsif (match = ROUTER.match(line))
               scope.merge!(router_id: match[1], local_as: match[2])
@@ -89,7 +89,7 @@ module Vxlan
               if statistics && !prefix_seen.key?(statistics.first.object_id)
                 peer, counts = statistics
                 # 路由类型是总前缀的子集；未展示的类型允许存在，已展示之和不能超过总数。
-                if peer[:prefixes_received] && counts.sum > peer[:prefixes_received]
+                if peer[:received_prefixes] && counts.sum > peer[:received_prefixes]
                   @issues << { code: :inconsistent_prefix_statistics, line: number }
                 else
                   peer[:prefixes_by_type] = prefix_columns.zip(counts).to_h
@@ -106,7 +106,7 @@ module Vxlan
               end
               @rows << row
               # 统计表按完整作用域查找；重复邻居仍由最终身份检查整体隔离。
-              peers[row.values_at(:vrf, :address_family, :peer_ip)] ||= row
+              peers[row.values_at(:vrf, :afi_safi, :peer_address)] ||= row
             else
               unparsed_records(number)
             end
@@ -125,25 +125,30 @@ module Vxlan
             count_mismatch(configured, @rows.size)
             @issues << { code: :invalid_peer_counts, configured: configured, capable: capable } if capable > configured
           end
-          @empty = true if values == [ [ 0, 0 ] ] && @rows.empty? && scope[:address_family] == "L2VPN EVPN"
+          @empty = true if values == [ [ 0, 0 ] ] && @rows.empty? && scope[:afi_safi] == "l2vpn_evpn"
         end
 
         # AS 0 只表示尚未建立邻居的未知身份；数值前缀总数始终表示已建立会话。
         def neighbor_record(match, scope)
           row = FIELDS.zip(match.captures).to_h.merge(scope)
           INTEGERS.each { |key| row[key] = row[key].to_i }
-          return unless row[:vrf] && row[:address_family] == "L2VPN EVPN" && ip_address?(row[:peer_ip]) && row[:version] == 4 &&
+          return unless row[:vrf] && row[:afi_safi] == "l2vpn_evpn" && ip_address?(row[:peer_address]) && row[:version] == 4 &&
             (0..4_294_967_295).cover?(row[:remote_as]) && STATE.match?(row[:state])
 
-          row[:prefixes_received] = row[:state].match?(/\A\d+\z/) ? row[:state].to_i : nil
+          row[:received_prefixes] = row[:state].match?(/\A\d+\z/) ? row[:state].to_i : nil
           row[:remote_as] = row[:remote_as].nonzero?
-          return if row[:prefixes_received] && row[:remote_as].nil?
+          return if row[:received_prefixes] && row[:remote_as].nil?
 
-          row[:peer_ip] = CtxParser::Values.ip_address(row[:peer_ip], allow_zone: true)
-          row[:state] = row[:prefixes_received] ? "established" : row[:state].downcase.tr(" ", "_")
+          row[:peer_address] = CtxParser::Values.ip_address(row[:peer_address], allow_zone: true)
+          row[:state] = row[:received_prefixes] ? :established : state_value(row[:state])
           row
         end
 
+        def state_value(value)
+          return :shutdown if /admin|shutdown/i.match?(value)
+          value.downcase.to_sym
+        end
+
         # 从末尾读取类型计数，保留多词状态，并按主表身份与总数关联统计。
         def prefix_record(line, scope:, peers:, columns:, total:)
           words = line.split(" ")
@@ -154,14 +159,14 @@ module Vxlan
           return unless ip_address?(address) && %w[I E].include?(kind) && asn.match?(/\A\d+\z/) && counts.all? { |value| value.match?(/\A\d+\z/) }
 
           address = CtxParser::Values.ip_address(address, allow_zone: true)
-          peer = peers[[ scope[:vrf], scope[:address_family], address ]]
+          peer = peers[[ scope[:vrf], scope[:afi_safi], address ]]
           return unless peer && peer[:remote_as] == asn.to_i.nonzero?
 
           if total
             value = words.join(" ")
             return unless STATE.match?(value)
-            observed = value.match?(/\A\d+\z/) ? value.to_i : value.downcase.tr(" ", "_")
-            return unless observed == (peer[:prefixes_received] || peer[:state])
+            observed = value.match?(/\A\d+\z/) ? value.to_i : state_value(value)
+            return unless observed == (peer[:received_prefixes] || peer[:state])
           else
             return unless words.empty?
           end

data/lib/vxlan/cisco_nxos/parsers/show_cdp_neighbors_detail.rb

@@ -8,7 +8,7 @@ module Vxlan
       # 在所属邻居记录内解释 CDP 详细字段。
       class ShowCdpNeighborsDetail < Parser
         EMPTY = "(?:CDP neighbors|CDP entries|neighbors|entries)".freeze
-        IDENTITY = %i[device_id interface neighbor_interface].freeze
+        IDENTITY = %i[device_id local_interface remote_interface].freeze
 
         private
 
@@ -39,7 +39,7 @@ module Vxlan
             end
             case line
             when /\A--More--/i then unparsed_records(number)
-            when /\ASystem Name:\s*(\S.*)\z/i then assign_field(row, :neighbor_name, $1, number)
+            when /\ASystem Name:\s*(\S.*)\z/i then assign_field(row, :remote_name, $1, number)
             when /\AInterface address\(es\):(?:\s+\d+)?\z/i then scope = :interface_addresses
             when /\AMgmt address\(es\):(?:\s+\d+)?\z/i then scope = :management_addresses
             when /\AIP(?:v[46])? Address:\s*(\S+)\z/i
@@ -55,9 +55,9 @@ module Vxlan
               assign_field(row, :capabilities, capabilities, number)
               scope = nil
             when /\AInterface:\s*(\S+),\s*Port ID \(outgoing port\):\s*(\S.*)\z/i
-              interface, neighbor_interface = $1, $2
-              assign_field(row, :interface, interface, number)
-              assign_field(row, :neighbor_interface, neighbor_interface, number)
+              interface, remote_interface = $1, $2
+              assign_field(row, :local_interface, interface, number)
+              assign_field(row, :remote_interface, remote_interface, number)
               scope = nil
             when /\AHoldtime:\s*(\d+) sec\z/i then assign_field(row, :holdtime, $1.to_i, number)
             when /\AVersion:\z/i
@@ -81,10 +81,10 @@ module Vxlan
           totals.each { |total| count_mismatch(total, @rows.size) }
           @empty = true if totals == [ 0 ] && @rows.empty?
           @rows.reject! do |entry|
-            next true if @field_conflicts.fetch(entry, {}).keys.intersect?(%i[neighbor_name interface neighbor_interface])
+            next true if @field_conflicts.fetch(entry, {}).keys.intersect?(%i[remote_name local_interface remote_interface])
 
-            entry[:neighbor_name] ||= entry[:device_id].sub(/\([^)]*\)\z/, "").split(".").first
-            if entry.values_at(:neighbor_name, :interface, :neighbor_interface).any? { |value| value.nil? || value.empty? }
+            entry[:remote_name] ||= entry[:device_id].sub(/\([^)]*\)\z/, "").split(".").first
+            if entry.values_at(:remote_name, :local_interface, :remote_interface).any? { |value| value.nil? || value.empty? }
               @issues << { code: :incomplete_cdp_neighbor }
               true
             end

data/lib/vxlan/cisco_nxos/parsers/show_nve_peers.rb

@@ -8,10 +8,10 @@ module Vxlan
       # 解析 NVE 端点及路由器 MAC，支持终端换行记录。
       class ShowNvePeers < Parser
         EMPTY = "peers"
-        IDENTITY = %i[interface peer_ip].freeze
+        IDENTITY = %i[interface peer_address].freeze
         HEADER = /\AInterface\s+Peer-IP\s+State\s+LearnType\s+Uptime\s+Router-Mac\z/i
         ROW = /\A(nve\d+)\s+(\d+(?:\.\d+){3})\s+(Up|Down)\s+(\S+)\s+(\S+)\s+([\da-f]{4}(?:\.[\da-f]{4}){2}|n\/a)\z/i
-        FIELDS = %i[interface peer_ip state learn_type uptime router_mac].freeze
+        FIELDS = %i[interface peer_address state learn_type uptime router_mac].freeze
 
         private
 

data/lib/vxlan/cli/apply.rb

@@ -4,34 +4,18 @@ require "ctx_cli/apply"
 require "ctx_runner/document"
 require "ctx_runner/evidence"
 require "ctx_runner/execution"
+require "ctx_runner/configuration_session"
 require "vxlan"
 require_relative "report"
 require_relative "../change_plan"
 
 module Vxlan
   module CLI
-    # 原生会话适配：读取使用固定查询提示符，写入由连接器识别配置模式提示符。
-    class ApplySession
-      # 借用一次已连接且独占的会话，不重连、不重放。
+    # 领域仅声明准备命令及配置语法，共享会话维护回执和读取边界。
+    class ApplySession < CtxRunner::ConfigurationSession
       def initialize(native)
-        @native = native
-      end
-
-      # 读回完整配置并交给现有解析器；部分证据不能参与前置检查或验收。
-      def read_configuration
-        [ "terminal length 0", "terminal width 511" ].each { |command| write(command) }
-        capture = CtxDriver::Reader.new(session: @native).read("show running-config")
-        raise IOError, "Configuration readback failed" unless capture.success?
-        observation = Vxlan::Config.new.parse(capture.body, complete: true)
-        raise ArgumentError, "Configuration evidence is incomplete" unless observation.complete? && observation.records.one?
-        CtxRunner::Document.call(observation.records.first)
-      end
-
-      # 每次只发一条命令；失败立即交还宿主，原始输出不进入终端和日志报告。
-      def write(command)
-        result = @native.execute_command(command.strip, output_sensitive: true)
-        raise IOError, "Device command is unconfirmed" unless result.success? && result.steps.one? && result.steps.first.command.text == command.strip
-        true
+        super(session: CtxDriver::Session.new(native), preparation_commands: [ "terminal length 0", "terminal width 511" ],
+          configuration_command: "show running-config", parser: Vxlan::Config.new)
       end
     end
 

data/lib/vxlan/cli/collect.rb

@@ -34,7 +34,7 @@ module Vxlan
       def load_network
         require "net/connector"
       rescue LoadError
-        raise LoadError, "Online collection requires net-connector >= 0.20.0; add it to the host Gemfile or run gem install net-connector", cause: nil
+        raise LoadError, "Online collection requires net-connector >= 0.21.0; add it to the host Gemfile or run gem install net-connector", cause: nil
       end
 
       # YAML 静态设备或显式 Netdisco 来源二选一；选中地址的所有冲突记录在连接前拒绝。

data/lib/vxlan/cli/options.rb

@@ -6,7 +6,7 @@ require "optparse"
 require "ctx_cli/options"
 require "ctx_cli/terminal"
 require "ctx_cli/initializer"
-gem "net-connector", "~> 0.20.0"
+gem "net-connector", "~> 0.21.0"
 require "net/connector/inventory/filters"
 require "yaml"
 require "ipaddr"
@@ -67,7 +67,7 @@ module Vxlan
         @environment = @files.environment
         @config, @env_file = @files.config, @files.env_file
       rescue LoadError
-        raise LoadError, "Collection configuration requires net-connector >= 0.20.0; reading .env also requires dotenv", cause: nil
+        raise LoadError, "Collection configuration requires net-connector >= 0.21.0; reading .env also requires dotenv", cause: nil
       end
 
       # 公共与专用文件先合并，进程值和 CLI 最后覆盖；数组不追加设备。
@@ -211,12 +211,12 @@ module Vxlan
 
       # 设备身份只接受公开字段，拒绝隐藏在 YAML 中的密码或连接参数。
       def normalize_device(row)
-        unless row.is_a?(Hash) && (row.keys - %w[host name model]).empty? && row["host"].is_a?(String) && !row["host"].include?("/")
+        unless row.is_a?(Hash) && (row.keys - %w[host name model platform]).empty? && (!row.key?("platform") || row["platform"] == "cisco_nxos") && row["host"].is_a?(String) && !row["host"].include?("/")
           raise ArgumentError, "devices accepts only host, name and model; host must be a single IP address"
         end
         host = IPAddr.new(row.fetch("host")).to_s
         %w[name model].each { |key| raise ArgumentError, "Device #{key} must be a nonempty string" if row.key?(key) && !row[key].nil? && (!row[key].is_a?(String) || row[key].strip.empty?) }
-        { "host" => host, "name" => row["name"] || host, "model" => row["model"] }.freeze
+        { "platform" => "cisco_nxos", "host" => host, "name" => row["name"] || host, "model" => row["model"] }.freeze
       rescue IPAddr::Error
         raise ArgumentError, "Invalid device host", cause: nil
       end

data/lib/vxlan/cli/report.rb

@@ -28,20 +28,20 @@ module Vxlan
       def write_execution(state) = @report.write_execution(state)
 
       # 采集和离线审查共用稳定名称，保留 IPv6 地址并避免设备名成为路径。
-      def self.device_basename(device)
+      def self.target_basename(device)
         "#{device.fetch('name').gsub(/[^A-Za-z0-9_.-]/, '_')[0, 100]}-#{device.fetch('host').gsub(/[^A-Za-z0-9_.-]/, '_')}"
       end
 
       # 每台完成后立即原子保存，即使批次随后取消仍可读取已完成证据。
       def write(result, snapshot: nil)
-        device = result.fetch(:device)
-        name = self.class.device_basename(device)
+        device = result.fetch(:target)
+        name = self.class.target_basename(device)
         # 保存状态属于批次宿主；不能让正在发布的文件预先声明自身已保存。
         body = result.reject { |key, _| key == :report_saved }.merge(snapshot: snapshot && snapshot.to_h)
         document = CtxRunner::Evidence.wrap(body, kind: "collection")
         advice = report_advice(Recommendations.new(document).call)
         document = document.merge("recommendations" => advice)
-        json = JSON.pretty_generate(document) + "\n"
+        json = JSON.pretty_generate(document, max_nesting: 128) + "\n"
         prepare_directory(File.join(directory, "evidence"))
         publish("evidence/#{name}.json", json)
         write_review(document, basename: name, source: File.join(directory, "evidence", "#{name}.json"), source_sha256: Digest::SHA256.hexdigest(json), advice: advice)
@@ -61,7 +61,7 @@ module Vxlan
           text << "Progress output error: #{summary['output_error']['error_type']}; device results retained" if summary["output_error"]
           summary.fetch("devices").each do |r|
             saved = r["report_saved"] == true ? "saved" : "persistence unconfirmed"
-            text << "#{r['device']['host']}\t#{r['device']['name']}\t#{r['status']}\t#{saved}\t#{r['error']}"
+            text << "#{r['target']['host']}\t#{r['target']['name']}\t#{r['status']}\t#{saved}\t#{r['error']}"
           end
           pending.each { |device| text << "#{device['host']}\t#{device['name']}\tnot collected" }
           text.join("\n") + "\n"

data/lib/vxlan/cli/review/fabric.rb

@@ -12,7 +12,7 @@ module Vxlan
       module Fabric
         # 相同事实合并展示；规则版本保持匹配顺序，完整证据由聚合计划保存。
         def fabric_text(audit, documents)
-          by_host = documents.to_h { |document| [ document.fetch("device").fetch("host"), document ] }
+          by_host = documents.to_h { |document| [ document.fetch("target").fetch("host"), document ] }
           lines = [ "Fabric shared-service consistency", "Scope: compare shared VNIs within explicit Fabrics and roles; compare Leaf and Border separately, and check Spine for service-bearing configuration.", "Deployment facts combine VLAN/NVE/EVPN evidence; incomplete deployment does not mean absence. Deployment scope differences are retained.", "ACL comparison includes ordered rules and dependencies; a majority without an ACL is not grounds for removal.", "" ]
           inventory = audit[:inventory]
           if inventory
@@ -23,7 +23,7 @@ module Vxlan
                 services = audit[:coverage].select { |entry| entry[:fabric] == fabric && entry[:role] == role }
                 partial = services.select { |entry| entry[:incomplete].any? }
                 lines << "  #{role}: deployed services #{services.size}, services shared across devices #{services.count { |entry| entry[:deployed].size >= 2 }}, incomplete associations #{partial.size}."
-                partial.each { |entry| lines << "    VNI #{entry[:vni]} missing: #{entry[:incomplete].map { |host| by_host.dig(host, 'device', 'name') || host }.join(', ')}" }
+                partial.each { |entry| lines << "    VNI #{entry[:vni]} missing: #{entry[:incomplete].map { |host| by_host.dig(host, 'target', 'name') || host }.join(', ')}" }
               end
             end
             lines << ""
@@ -39,14 +39,14 @@ module Vxlan
               common = defined.reduce { |all, members| all & members } || []
               lines << "  Members common to defined versions (not an approved baseline): #{common.empty? ? 'none' : common.join(', ')}"
               evidence.group_by { |row| row[:value] }.each do |members, rows|
-                names = rows.map { |row| by_host.dig(row[:host], "device", "name") || row[:host] }
+                names = rows.map { |row| by_host.dig(row[:host], "target", "name") || row[:host] }
                 value = members ? "#{members.size} members; outside the common set: #{(members - common).empty? ? 'none' : (members - common).join(', ')}" : "No definition provided or object evidence not collected"
                 lines.concat([ "  #{names.join(', ')}", "    #{value}" ])
               end
               next
             end
             unless evidence.is_a?(Array) && evidence.all? { |row| row.is_a?(Hash) }
-              lines << JSON.pretty_generate(evidence)
+              lines << JSON.pretty_generate(evidence, max_nesting: 128)
               next
             end
             grouped = evidence.group_by do |row|
@@ -59,12 +59,12 @@ module Vxlan
               [ row[:vlan] || row[:interface] || "shared", display_fabric_value(value) ]
             end
             grouped.each do |(vlan, value), members|
-              names = members.map { |row| row[:name] || by_host.dig(row[:host], "device", "name") || row[:host] }
+              names = members.map { |row| row[:name] || by_host.dig(row[:host], "target", "name") || row[:host] }
               lines.concat([ "  VLAN/interface #{vlan}: #{value}", "    #{names.join(', ')}" ])
             end
             if evidence.any? { |row| row[:semantics] }
               evidence.group_by { |row| row[:semantics] }.each_with_index do |(rules, members), variant|
-                lines << "  Rule version #{variant + 1}: #{members.map { |row| by_host.dig(row[:host], 'device', 'name') || row[:host] }.join(', ')}"
+                lines << "  Rule version #{variant + 1}: #{members.map { |row| by_host.dig(row[:host], 'target', 'name') || row[:host] }.join(', ')}"
                 lines.concat(rules.map { |rule| "    #{rule['action']} #{rule['expression']}" })
               end
             end
@@ -94,7 +94,7 @@ module Vxlan
         def review_collected_fabric(policy)
           sources = Dir[File.join(directory, "evidence", "*.json")].sort.map do |path|
             body = CtxCli::Input.read(path: path)
-            [ File.expand_path(path), body, JSON.parse(body) ]
+            [ File.expand_path(path), body, JSON.parse(body, max_nesting: 128) ]
           end
           build_review(sources, policy: policy, standalone: false) unless sources.empty?
         end

data/lib/vxlan/cli/review/report.rb

@@ -18,10 +18,10 @@ module Vxlan
           @fabric_text = @fabric_audit && fabric_text(@fabric_audit, documents)
           entries = sources.map do |path, body, document, initial|
             advice = initial || Recommendations.new(document).call
-            additions = @fabric_audit && @fabric_audit[:device_items][document["device"]["host"]]
+            additions = @fabric_audit && @fabric_audit[:device_items][document["target"]["host"]]
             advice = Recommendations.combine(advice, additions)
-            device = document.fetch("device")
-            basename = CLI::Report.device_basename(device)
+            device = document.fetch("target")
+            basename = CLI::Report.target_basename(device)
             write_review(document, basename: basename, source: path, source_sha256: Digest::SHA256.hexdigest(body), advice: advice)
           end
           finish_review(entries, source_batch: File.dirname(File.dirname(sources.first[0])), standalone: standalone)
@@ -32,7 +32,7 @@ module Vxlan
           raise ArgumentError, "Invalid report name" unless basename.match?(/\A[A-Za-z0-9_.-]+\z/)
           advice = report_advice(advice || Recommendations.new(document).call).merge(source: source, source_sha256: source_sha256)
           advice[:items] = advice[:items].map(&:dup)
-          entry = { device: advice[:device], counts: advice[:counts], basename: basename, report: "devices/#{basename}.txt", source: source,
+          entry = { target: advice[:target], counts: advice[:counts], basename: basename, report: "devices/#{basename}.txt", source: source,
             source_sha256: source_sha256, script: nil, script_sha256: nil, plans: [], changes: {}, advice: advice }
           config = Config::Evidence.complete_record(document)
           config_sha256 = nil
@@ -43,7 +43,7 @@ module Vxlan
             change = plan.to_h
             id = [ basename, change["kind"], "vlan#{change['vlan']}", change["direction"], CtxRunner::Fingerprint.call(change)[0, 12] ].compact.join("--")
             config_sha256 ||= CtxRunner::Fingerprint.call(config)
-            entry[:changes][id] = { schema_version: CtxRunner::Evidence::VERSION, kind: "change", platform: "cisco_nxos", device: document.fetch("device"), expected_config_sha256: config_sha256,
+            entry[:changes][id] = { schema_version: CtxRunner::Evidence::VERSION, kind: "change", platform: "cisco_nxos", target: document.fetch("target"), expected_config_sha256: config_sha256,
               source: source, source_sha256: source_sha256, change: change, commands: plan.commands, rollback: plan.rollback,
               scope: item[:scope], title: item[:title], prerequisites: item[:prerequisites], impact: item[:impact], verify: item[:verify] }
             item[:plan_id] = id
@@ -71,11 +71,11 @@ module Vxlan
           checkpoint("summary.json", summary) if standalone
           plan = { schema_version: CtxRunner::Evidence::VERSION, kind: "change_plan", platform: "cisco_nxos", mode: "review", devices: public_entries, audits: entries.map { |entry| entry[:advice] },
             changes: entries.each_with_object({}) { |entry, all| all.merge!(entry[:changes]) }, fabric: @fabric_audit && @fabric_audit.reject { |key, _| key == :device_items } }
-          body = JSON.pretty_generate(plan) + "\n"
+          body = JSON.pretty_generate(plan, max_nesting: 128) + "\n"
           summary[:plan_sha256] = Digest::SHA256.hexdigest(body)
           publish("plan.json", body)
           publish("plan.json.sha256", summary[:plan_sha256] + "\n")
-          events = public_entries.map { |entry| JSON.generate(event: "device_reviewed", reviewed_at: Time.now.utc.iso8601(6), host: entry[:device]["host"], source_sha256: entry[:source_sha256], counts: entry[:counts], report: entry[:report], script: entry[:script], executed: false) }
+          events = public_entries.map { |entry| JSON.generate(event: "device_reviewed", reviewed_at: Time.now.utc.iso8601(6), host: entry[:target]["host"], source_sha256: entry[:source_sha256], counts: entry[:counts], report: entry[:report], script: entry[:script], executed: false) }
           publish("events.jsonl", events.join("\n") + (events.empty? ? "" : "\n"))
           text = summary_text(summary)
           if standalone
@@ -110,7 +110,7 @@ module Vxlan
 
         # 文本按设备、证据、问题、动作顺序组织，完整跨设备证据位于聚合计划。
         def device_text(entry, document)
-          advice, device = entry.values_at(:advice, :device)
+          advice, device = entry.values_at(:advice, :target)
           lines = [ "Device: #{device['name']} (#{device['host']})", "Mode: diagnostics and planning; no device configuration executed", "Evidence time: #{advice[:observed_at] || 'unknown'}", "Source: #{entry[:source]}", "Source file SHA256: #{entry[:source_sha256]}",
             "Recommendations: #{entry[:counts]}", "Command file: #{entry[:script] || 'not generated'}", "Command SHA256: #{entry[:script_sha256] || 'none'}", "Plan file: plan.json; interactive plan items: #{entry[:plans].size} items", "" ]
           lines << "Collection status: #{document['status']}" if document["status"]
@@ -120,7 +120,7 @@ module Vxlan
           advice[:items].each_with_index do |item, index|
             lines.concat([ "", "#{index + 1}. #{item[:scope]} — #{item[:title]}", "Status: #{item[:status]}; rule: #{item[:code]}", "Impact: #{item[:impact]}" ])
             evidence = item[:category] == "fabric" ? Array(item[:evidence]).select { |row| row[:host] == device["host"] } : item[:evidence]
-            lines.concat([ "Local evidence: ", JSON.pretty_generate(evidence) ])
+            lines.concat([ "Local evidence: ", JSON.pretty_generate(evidence, max_nesting: 128) ])
             lines << "Cross-device comparison: summary.txt; full raw comparison: audits / fabric in plan.json." if item[:category] == "fabric"
             if item[:plan_id]
               lines << "Interactive plan item: #{item[:plan_id]}"
@@ -146,8 +146,8 @@ module Vxlan
             "Read in order: summary.txt -> devices/<device>.txt -> scripts/<device>.cfg -> the selected plan item in plan.json.",
             "evidence/ stores collection evidence used by the program; routine review does not require opening it. devices/ contains readable diagnostics only.",
             "plan.json.sha256 verifies the aggregate plan; events.jsonl records this offline review, not device sessions or execution receipts.", "Applying requires selecting one --item, interactive confirmation, configuration readback and fingerprint verification; there is no automatic bulk execution.", "" ]
-          entries.sort_by { |entry| [ entry[:counts].values.sum.positive? ? 0 : 1, entry[:device]["name"].to_s ] }.each do |entry|
-            lines.concat([ "#{entry[:device]['host']} #{entry[:device]['name']} unresolved=#{entry[:counts].fetch('blocked', 0)} candidates=#{entry[:counts].fetch('candidate', 0)} investigations=#{entry[:counts].fetch('investigate', 0)}",
+          entries.sort_by { |entry| [ entry[:counts].values.sum.positive? ? 0 : 1, entry[:target]["name"].to_s ] }.each do |entry|
+            lines.concat([ "#{entry[:target]['host']} #{entry[:target]['name']} unresolved=#{entry[:counts].fetch('blocked', 0)} candidates=#{entry[:counts].fetch('candidate', 0)} investigations=#{entry[:counts].fetch('investigate', 0)}",
               "  Device report: #{entry[:report]}", "  Command file: #{entry[:script] || 'not generated'}; executable plans: #{entry[:plans].size} items" ])
           end
           lines.concat([ "", @fabric_text ]) if @fabric_text

data/lib/vxlan/cli/review.rb

@@ -34,8 +34,8 @@ module Vxlan
           validate(entry[2])
           entry << Recommendations.new(entry[2]).call
         end
-        hosts = documents.map { |entry| entry[2]["device"]["host"] }
-        names = documents.map { |entry| CLI::Report.device_basename(entry[2].fetch("device")) }
+        hosts = documents.map { |entry| entry[2]["target"]["host"] }
+        names = documents.map { |entry| CLI::Report.target_basename(entry[2].fetch("target")) }
         raise ArgumentError, "Duplicate device identity or output name" unless hosts.uniq == hosts && names.uniq == names
         policy = options[:fabric_policy] && YAML.safe_load(CtxCli::Input.read(path: options[:fabric_policy]), aliases: false)
         Vxlan::Fabric::Scope.new(policy) if policy

data/lib/vxlan/collector.rb

@@ -21,7 +21,7 @@ module Vxlan
 
     # 通过调用方持有的连接器顺序采集请求维度。
     def collect(connector:, target:, fabric_key:, model: nil, dimensions: COMMANDS.keys)
-      target = CtxRunner::Target.snapshot(target)
+      target = CtxRunner::Target.coerce(target).to_h
       target, fabric_key, dimensions, profile = request(target, fabric_key, dimensions, connector.platform, model)
 
       observations = {}
@@ -44,14 +44,18 @@ module Vxlan
 
     # 连接前固定请求数据，生命周期入口和借用会话入口共用相同校验。
     def request(target, fabric_key, dimensions, platform, model)
-      target = CtxRunner::Target.snapshot(target)
+      target = CtxRunner::Target.coerce(target).to_h
       unless fabric_key.is_a?(String) && !fabric_key.strip.empty? && !/[\x00-\x1f\x7f]/.match?(fabric_key)
         raise ArgumentError, "Fabric identity must be nonempty text"
       end
       unless dimensions.is_a?(Array) && dimensions.any? && dimensions.uniq == dimensions && (dimensions - COMMANDS.keys).empty?
         raise ArgumentError, "Unknown or duplicate VXLAN dimensions"
       end
-      raise ArgumentError, "VXLAN requires Cisco NX-OS" unless platform.to_s == "cisco_nxos"
+      platform = ParserRegistry.canonical(platform).to_s
+      if target[:platform] && ParserRegistry.canonical(target[:platform]).to_s != platform
+        raise ArgumentError, "Target platform differs from the connector"
+      end
+      target = target.merge(platform: platform)
 
       [ CtxParser::Immutable.copy(target), CtxParser::Immutable.copy(fabric_key), dimensions.dup.freeze,
         ParserRegistry.fetch(platform, model: model) ]

data/lib/vxlan/fabric/review.rb

@@ -18,7 +18,7 @@ module Vxlan
     class Review
       # 比较范围由业务策略统一验证，审查器只负责组织规则与建议。
       def initialize(documents, policy)
-        @documents = documents.to_h { |document| [ document.fetch("device").fetch("host"), document ] }
+        @documents = documents.to_h { |document| [ document.fetch("target").fetch("host"), document ] }
         raise ArgumentError, "Duplicate device identity" unless @documents.size == documents.size
         @scope = Scope.new(policy)
       end
@@ -177,7 +177,7 @@ module Vxlan
           index = (@subnet_indexes[host] ||= SubnetIndex.new(config))
           excluded = except&.first == host ? except.last : nil
           index.conflicts(address: change["address"], vrf: change["vrf"], vni: change["vni"], except_interface: excluded).map do |entry|
-            { host: host, name: @documents[host]["device"]["name"], **entry }
+            { host: host, name: @documents[host]["target"]["name"], **entry }
           end
         end
       end
@@ -299,7 +299,7 @@ module Vxlan
 
       # 观察附带设备名、地址及本地 VLAN，报告可直接定位配置入口。
       def observations(rows)
-        rows.map { |row| { host: row[:host], name: @documents[row[:host]]["device"]["name"], vlan: row[:vlan], value: yield(row) } }
+        rows.map { |row| { host: row[:host], name: @documents[row[:host]]["target"]["name"], vlan: row[:vlan], value: yield(row) } }
       end
 
       # 按业务问题计数，不把证据行数当作问题数量。

data/lib/vxlan/recommendations.rb

@@ -48,7 +48,7 @@ module Vxlan
         items.concat(undefined_acl_items(config))
       end
       items.concat(runtime_tasks)
-      { schema_version: CtxRunner::Evidence::VERSION, kind: "recommendations", review_only: true, health_assessment: "not_performed", device: @document["device"],
+      { schema_version: CtxRunner::Evidence::VERSION, kind: "recommendations", review_only: true, health_assessment: "not_performed", target: @document["target"],
         observed_at: @document.dig("snapshot", "observed_at"), items: items, counts: items.map { |item| item[:status] }.tally }
     end
 

data/lib/vxlan/snapshot.rb

@@ -11,7 +11,7 @@ module Vxlan
     include CtxRunner::Document::Value
     extend Forwardable
     def_delegators :@snapshot, :target, :observations, :observed_at, :issues, :collection_status,
-      :observation, :complete?, :same_target?
+      :observation, :records, :complete?, :same_target?
     attr_reader :fabric_key
 
     def initialize(target:, fabric_key:, observations:, observed_at:, issues: [])

data/lib/vxlan/version.rb

@@ -2,5 +2,5 @@
 
 module Vxlan
   # 公开包版本，供 RubyGems 元数据和运行时调用方共用。
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vxlan
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Gatework contributors
@@ -29,40 +29,40 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: 0.5.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: 0.5.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: ctx_runner
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: 0.5.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: 0.5.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: ctx_parser
   requirement: !ruby/object:Gem::Requirement
@@ -89,20 +89,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: 0.5.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: 0.5.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: digest
   requirement: !ruby/object:Gem::Requirement