vxlan 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c114dcb0645a2b10176e8a6cc68cdea2b517edd069c166d20b02046dddaf766a
-  data.tar.gz: edccf86d53afb7ad825c2fd468dcaba21ebda26a7b2330233fc2461840ba220f
+  metadata.gz: 3a0904488ebdedf6f5983003bf51724e3e0c5442b2347fb6433041da8f858394
+  data.tar.gz: 8c1b2e0ba07891754cb6074e5da60a2174b6a96508309836bdc4db333ce7414e
 SHA512:
-  metadata.gz: 34c6082ad93884802d028f56cb2821cb8ae057537ba4618d7dab6e9edb3d73d27dfaebf8a6e99e502f334aecd9617e5aacc0c579070121e7c2364a5a78e3c185
-  data.tar.gz: 51864b6ddf301c26c41f3eb3fb77b46a2baa32d8047f0f806595a839ef20e32e976c022843bc7bf208794ec54ac12ed31ee2b158f9647cf1e824c191b5bd9fb1
+  metadata.gz: a51c259e1059d12babf19d1789e6ae9e3dba5fdaae8b612aad552aca488665b44f2ca2d25e7cec825b781b39ad8b887ee5c71b648a12da03fd6dc4b5f3d7561a
+  data.tar.gz: 6d37d517bcc3d7c8e8f143917449bbe450d2f79c54ca64c9032ace956f8db265ed86fbb4ee6e76f4fdf88ea68f74155408cecbf0f14aee20f5e297818b82f07e

data/CHANGELOG.md

@@ -4,6 +4,17 @@ 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.
+- Normalize OSPF process_id, router_id, neighbor_address, symbolic state and neighbor_role while retaining priority and uptime.
+- Delegate interactive apply to ctx_cli, resolving credentials through net-connector, including empty overrides and platform enable passwords.
+- Use schema 3 reports and named checksummed plans. Older files must be regenerated.
+
 ## 0.6.0 (2026-10-29)
 
 - Require RuntimeParser platform at construction and add parse_many. Rename Snapshot Ruby members to observations/observation while retaining dimensions in persisted reports. Use Catalog and shared Credentials in CLI; reject selected duplicate addresses across platforms before connecting.

data/README.md

@@ -146,6 +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 JSON keeps its `dimensions` field.
+`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_ip_ospf_neighbors.rb

@@ -8,11 +8,11 @@ module Vxlan
       # 逐进程、VRF 独立核对 OSPF 邻居总数。
       class ShowIpOspfNeighbors < Parser
         EMPTY = "(?:OSPF )?neighbors"
-        IDENTITY = %i[process vrf neighbor_id interface].freeze
+        IDENTITY = %i[process_id vrf router_id interface].freeze
         BOUNDARY = /^\s*OSPF Process ID /
         HEADER = /\ANeighbor ID\s+Pri\s+State\s+Up Time\s+Address\s+Interface\z/i
         ROW = /\A([\d.]+)\s+(\d+)\s+(\S+(?:\/\s*\S+)?)\s+(\S+)\s+([\d.]+)\s+(\S+)\z/
-        FIELDS = %i[neighbor_id priority state uptime address interface].freeze
+        FIELDS = %i[router_id priority state uptime neighbor_address interface].freeze
 
         private
 
@@ -23,18 +23,20 @@ module Vxlan
             if HEADER.match?(line)
               @header = true
             elsif (match = /\AOSPF Process ID (\S+) VRF (\S+)\z/i.match(line))
-              scope = { process: match[1], vrf: match[2] }
+              scope = { process_id: match[1], vrf: match[2] }
             elsif (match = /\ATotal number of neighbors:\s*(\d+)\z/i.match(line))
               totals << match[1].to_i
             elsif (match = ROW.match(line))
               row = FIELDS.zip(match.captures).to_h.merge(scope)
               row[:priority] = row[:priority].to_i
-              unless ip_address?(row[:neighbor_id]) && ip_address?(row[:address]) && (0..255).cover?(row[:priority]) &&
+              unless ip_address?(row[:router_id]) && ip_address?(row[:neighbor_address]) && (0..255).cover?(row[:priority]) &&
                 row[:state].match?(/\A(?:DOWN|ATTEMPT|INIT|2WAY|EXSTART|EXCHANGE|LOADING|FULL)\/(?:\s*(?:DR|BDR|DROTHER|-))\z/i)
                 unparsed_records(number)
                 next
               end
-              @rows << row.merge(state: row[:state].downcase.delete(" "))
+              state, role = row[:state].downcase.delete(" ").split("/", 2)
+              @rows << row.merge(state: state == "2way" ? :two_way : state.to_sym,
+                neighbor_role: role == "-" ? :unknown : role.to_sym)
             else
               unparsed_records(number)
             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

@@ -1,134 +1,57 @@
 # frozen_string_literal: true
 
-require "ctx_cli/command"
-require "ctx_cli/terminal"
-require "ctx_cli/input"
-require "ctx_cli/output"
-require "json"
+require "ctx_cli/apply"
 require "ctx_runner/document"
-require "digest"
+require "ctx_runner/evidence"
 require "ctx_runner/execution"
-require "ipaddr"
+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?
-        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
 
-    # 交互式单设备下发：展示、确认、重新读取、记录意图、执行、回读，禁止无人值守确认。
+    # 领域适配器只维护计划类型、凭据来源与独占设备会话。
     class Apply
-      # 注入连接工厂仅用于宿主集成和离线失败测试。
       def initialize(env: ENV, out: $stdout, error: $stderr, input: $stdin, connector_factory: nil, discovery: {})
-        @env, @out, @error, @input, @factory = env, out, error, input, connector_factory
-        @discovery = discovery
-        @output = CtxCli::Output.new(out: out, error: error)
+        @env, @factory, @discovery = env, connector_factory, discovery
+        @entry = CtxCli::Apply.new(adapter: self, execution: CtxRunner::Execution, name: "vxlan", out: out, error: error, input: input)
       end
 
-      # 没有 --yes 或自动回退；零退出码只确认配置回读，不声称业务已验收。
-      def run(argv)
-        @store, @execution = nil, nil
-        command = CtxCli::Command.new(banner: "Usage: vxlan apply --plan FILE --item ID [--env-file FILE] (requires explicit confirmation in an interactive terminal)",
-          defaults: { directory: File.join(Dir.pwd, "vxlan-executions"), port: 22 }, out: @out) do |p, options|
-          p.on("--plan FILE", "Batch plan.json; requires a SHA256 checksum file in the same directory") { |value| options[:plan] = value }
-          p.on("--item ID", "Explicitly select one change from the batch plan; bulk execution is prohibited") { |value| options[:item] = value }
-          p.on("--env-file FILE", "Explicit credentials file; process environment takes precedence") { |value| options[:env_file] = value }
-          p.on("--directory DIR", "Private execution log directory") { |value| options[:directory] = value }
-          p.on("--port N", Integer, "SSH port, default 22") { |value| options[:port] = value }
-          p.on("-h", "--help", "Show help without connecting to devices") { options[:help] = true }
-        end
-        options = command.parse(argv)
-        return 0 if command.informational?
-        terminal = CtxCli::Terminal.new(input: @input, out: @out)
-        terminal.require_tty!(@error)
-        raise ArgumentError, "A single plan is required" unless options[:plan] && options[:port].between?(1, 65_535)
-        body = CtxCli::Input.read(path: options[:plan])
-        hash = Digest::SHA256.hexdigest(body)
-        plan = CtxParser::Immutable.copy(select_plan(JSON.parse(body), options, hash))
-        change = validate_plan(plan)
-        host = plan.fetch("device").fetch("host")
-        @out.puts "Target: #{plan['device']['name']}(#{host}); #{plan['scope']}; #{plan['title']}"
-        @out.puts "Impact: #{plan['impact']}"
-        @out.puts Array(plan["prerequisites"]).map { |value| "Prerequisite: #{value}" }
-        @out.puts "Plan SHA256: #{hash}\nProposed commands:\n#{change.commands.join("\n")}\nConditional rollback (not executed automatically):\n#{change.rollback.join("\n")}"
-        token = "APPLY #{host} #{hash[0, 12]} #{options[:item]}"
-        confirmed = terminal.confirm(token: token, prompt: "After confirming the service policy and maintenance window, enter #{token}; any other input cancels: ")
-        return @out.puts("Cancelled; no device connection opened.") || 1 unless confirmed
-        settings = credentials(options)
-        @store = Report.new(options[:directory])
-        @execution = CtxRunner::Execution.new(plan: plan, change: change, journal: @store, plan_sha256: hash, item: options[:item])
-        @execution.run { |operation| with_session(plan["device"], settings, &operation) }
-        @out.puts "Configuration readback confirmed; service acceptance is still required. Configuration was not saved to startup configuration. Log: #{@store.directory}/execution.json"
-        0
-      rescue Interrupt
-        report_journal_failure
-        @output.diagnostic "Operation interrupted; #{@execution&.started? ? 'Device effects may be incomplete; read back and verify before proceeding. Do not replay commands.' : 'No service configuration was sent.'}"
-        130
-      rescue StandardError, LoadError => error
-        report_journal_failure
-        @output.diagnostic "Apply stopped (#{error.class.name}); #{@execution&.started? ? 'Effects are not fully confirmed; read back first. No automatic replay or rollback.' : 'No service configuration was sent; check the terminal, plan, credentials and current configuration for consistency.'}"
-        2
-      end
+      def run(argv) = @entry.run(argv)
 
-      private
-
-      # 聚合文件必须校验哈希并选中唯一动作；绝不隐式选择第一项或循环执行。
-      def select_plan(document, options, hash)
-        id = options[:item]
-        unless document.is_a?(Hash) && document["schema_version"] == 2 && document["platform"] == "cisco_nxos" && document["changes"].is_a?(Hash) &&
-            id.is_a?(String) && id.match?(/\A[A-Za-z0-9_.-]+\z/) && document["changes"].key?(id)
-          raise ArgumentError, "A batch plan and valid --item are required"
-        end
-        raise ArgumentError, "Plan checksum verification failed" unless CtxCli::Input.read(path: "#{options[:plan]}.sha256", max_bytes: 128).strip == hash
-        document["changes"].fetch(id)
+      def select_plan(document, item:)
+        CtxRunner::Evidence.plan(document, item: item, platform: "cisco_nxos")
       end
 
-      # 不信任文件中的命令，重新从有限动作渲染并逐字核对，拒绝额外命令。
+      # 从类型化增量重新生成命令，拒绝修改后的任意脚本。
       def validate_plan(plan)
-        raise ArgumentError, "Plan type mismatch" unless plan.is_a?(Hash) && plan["schema_version"] == 1 && plan["platform"] == "cisco_nxos"
-        host = plan.fetch("device").fetch("host")
-        raise ArgumentError, "Invalid target address" unless host.is_a?(String) && !host.include?("/") && IPAddr.new(host).to_s == host
-        raise ArgumentError, "Invalid configuration fingerprint" unless plan["expected_config_sha256"].is_a?(String) && plan["expected_config_sha256"].match?(/\A[0-9a-f]{64}\z/)
         change = ChangePlan.build(plan.fetch("change"))
-        raise ArgumentError, "Plan commands were modified" unless change.commands == plan["commands"] && change.rollback == plan["rollback"]
+        unless change.commands == plan["commands"] && change.rollback == plan["rollback"]
+          raise ArgumentError, "Plan commands were modified"
+        end
         change
       end
 
-      # 共用分层环境加载器，显式文件最高、进程环境优先；凭据不进入计划或日志。
       def credentials(options)
         require "net/connector/config"
+        require "net/connector/credentials"
         env = Net::Connector::Config.new(name: "vxlan", env: @env, env_file: options[:env_file], **@discovery).load_environment.environment
-        username = env["NC_CISCO_NXOS_USERNAME"] || env["NC_DEVICE_USERNAME"]
-        raise ArgumentError, "Device username is missing" unless username.is_a?(String) && !username.strip.empty?
-        { username: username, password: env["NC_CISCO_NXOS_PASSWORD"] || env["NC_DEVICE_PASSWORD"], enable_password: env["NC_ENABLE_PASSWORD"],
-          port: options[:port], host_key_policy: "strict", command_timeout: 60, login_timeout: 15 }
+        credentials = Net::Connector::Credentials.new(env: env).resolve(platform: :cisco_nxos)
+        raise ArgumentError, "Device username is missing" unless credentials
+        credentials.merge(port: options[:port], host_key_policy: "strict", command_timeout: 60, login_timeout: 15)
       end
 
-      # 原生会话只打开一次，读写处于同一操作租约中。
+      def report(options) = Report.new(options.fetch(:directory))
+
       def with_session(device, settings, &operation)
         return @factory.call(device, settings, &operation) if @factory
         require "net/connector"
@@ -137,13 +60,9 @@ module Vxlan
         end
       end
 
-      # 公共执行器保存失败状态；CLI 只呈现持久性尚未确认的诊断。
-      def report_journal_failure
-        return unless @execution&.journal_failed?
-        @output.diagnostic "Execution log finalization is unconfirmed; existing checkpoints retained. Do not replay configuration based on this state."
-      rescue Interrupt
-        nil
-      end
+      def inspect = "#<#{self.class.name}>"
+      alias to_s inspect
+      def pretty_print(printer) = printer.text(inspect)
     end
   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.19.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.19.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.19.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

@@ -4,6 +4,7 @@ require "json"
 require "time"
 require "ctx_runner/report"
 require "ctx_runner/document"
+require "ctx_runner/evidence"
 require_relative "review/report"
 require_relative "review/fabric"
 
@@ -27,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::Document.call(body)
+        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)
@@ -60,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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "ctx_runner/evidence"
 require "digest"
 require "ctx_runner/fingerprint"
 require_relative "../../recommendations"
@@ -17,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)
@@ -31,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
@@ -42,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: 1, 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
@@ -65,16 +66,16 @@ module Vxlan
         def finish_review(entries, source_batch:, standalone: true)
           counts = entries.each_with_object(Hash.new(0)) { |entry, total| entry[:counts].each { |key, count| total[key] += count } }
           public_entries = entries.map { |entry| entry.reject { |key, _| %i[advice changes].include?(key) } }
-          summary = { layout_version: 3, mode: "review", status: "incomplete", review_only: true, devices: entries.size, counts: counts, source_batch: source_batch,
+          summary = { schema_version: CtxRunner::Evidence::VERSION, kind: "review", layout_version: 3, mode: "review", status: "incomplete", review_only: true, devices: entries.size, counts: counts, source_batch: source_batch,
             reports: public_entries, plan: "plan.json", plan_sha256: nil, fabric_findings: @fabric_audit ? @fabric_audit[:findings].size : 0 }
           checkpoint("summary.json", summary) if standalone
-          plan = { schema_version: 2, platform: "cisco_nxos", mode: "review", devices: public_entries, audits: entries.map { |entry| entry[:advice] },
+          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
@@ -109,17 +110,17 @@ 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"]
-          configuration_time = document.dig("snapshot", "dimensions", "configuration", "evidence", 0, "observed_at")
+          configuration_time = document.dig("snapshot", "observations", "configuration", "evidence", 0, "observed_at")
           lines << "Configuration evidence time: #{configuration_time}" if configuration_time
           lines << "No current rules matched; this does not establish network health." if advice[:items].empty?
           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]}"
@@ -145,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
@@ -53,7 +53,7 @@ module Vxlan
 
       # 先校验公共证据外壳，再验证领域记录。
       def validate(document)
-        CtxRunner::Evidence.validate(document) { |record, dimension| validate_record(record, dimension) }
+        CtxRunner::Evidence.validate(document, names: CiscoNxos::Profile::COMMANDS.keys) { |record, dimension| validate_record(record, dimension) }
       end
 
       # 在输出目录创建前验证所有会参与建议生成的嵌套字段。

data/lib/vxlan/collector.rb

@@ -21,6 +21,7 @@ module Vxlan
 
     # 通过调用方持有的连接器顺序采集请求维度。
     def collect(connector:, target:, fabric_key:, model: nil, dimensions: COMMANDS.keys)
+      target = CtxRunner::Target.coerce(target).to_h
       target, fabric_key, dimensions, profile = request(target, fabric_key, dimensions, connector.platform, model)
 
       observations = {}
@@ -29,9 +30,8 @@ module Vxlan
       if collection.failure
         code = collection.failure.fetch(:code)
         dimensions.each { |name| observations[name] ||= failure(name, code) }
-        observations[:collection] = failure(:collection, code)
       end
-      snapshot(target, fabric_key, observations)
+      snapshot(target, fabric_key, observations, issues: collection.failure ? [ collection.failure ] : [])
     end
 
     # 借用已打开的会话；调用方负责连接和关闭，本方法不重连、不提权。
@@ -44,11 +44,18 @@ module Vxlan
 
     # 连接前固定请求数据，生命周期入口和借用会话入口共用相同校验。
     def request(target, fabric_key, dimensions, platform, model)
-      raise ArgumentError, "Target must be a hash" unless target.is_a?(Hash)
+      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) ]
@@ -60,7 +67,6 @@ module Vxlan
       reader = CtxDriver::Reader.new(session: session, clock: @clock)
       if (code = prepare_terminal(reader))
         dimensions.each { |name| observations[name] = failure(name, code) }
-        observations[:collection] = failure(:collection, code)
         return observations
       end
       ordered = dimensions.include?(:configuration) ? [ :configuration, *dimensions.reject { |name| name == :configuration } ] : dimensions
@@ -76,16 +82,8 @@ module Vxlan
     end
 
     # 汇总证据完整性，不将查询成功解释为 Fabric 健康。
-    def snapshot(target, fabric_key, observations)
-      status = if observations.values.all?(&:complete?)
-        :complete
-      elsif observations.values.any? { |value| %i[complete partial].include?(value.status) }
-        :partial
-      else
-        :failed
-      end
-      observations[:collection] ||= Observation.new(name: :collection, status: status, completed_at: @clock.call)
-      Snapshot.new(target: target, fabric_key: fabric_key, observations: observations, observed_at: @clock.call)
+    def snapshot(target, fabric_key, observations, issues: [])
+      Snapshot.new(target: target, fabric_key: fabric_key, observations: observations, observed_at: @clock.call, issues: issues)
     end
 
     # 采集设备回显前，禁用分页并归一化终端宽度。

data/lib/vxlan/config/evidence.rb

@@ -6,7 +6,7 @@ module Vxlan
     module Evidence
       # 外层采集成功不能覆盖记录层的部分解析或多份配置歧义。
       def self.complete_record(document)
-        observation = document&.dig("snapshot", "dimensions", "configuration")
+        observation = document&.dig("snapshot", "observations", "configuration")
         return unless observation && observation["status"] == "complete"
         records = observation["records"]
         return unless records.is_a?(Array) && records.one?

data/lib/vxlan/fabric/review.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "ctx_runner/evidence"
 require "ipaddr"
 require "json"
 require "digest"
@@ -17,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
@@ -43,7 +44,7 @@ module Vxlan
           @role = nil
           review_subnets(fabric, configs)
         end
-        { schema_version: 2, scope: "same_role_same_deployed_vni", inventory: inventory, findings: @findings, device_items: @items.to_h, coverage: @coverage }
+        { schema_version: CtxRunner::Evidence::VERSION, kind: "fabric_review", scope: "same_role_same_deployed_vni", inventory: inventory, findings: @findings, device_items: @items.to_h, coverage: @coverage }
       end
 
       private
@@ -176,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
@@ -298,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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "ctx_runner/evidence"
 require_relative "cisco_nxos/profile"
 require_relative "config/evidence"
 
@@ -35,7 +36,7 @@ module Vxlan
     # 输入为报告 JSON 的字符串键结构，离线与实时报告共用此边界。
     def initialize(document)
       @document = document
-      @dimensions = document.dig("snapshot", "dimensions") || {}
+      @dimensions = document.dig("snapshot", "observations") || {}
     end
 
     # 建议与采集完整性分开；没有命中规则并不代表网络健康。
@@ -47,7 +48,7 @@ module Vxlan
         items.concat(undefined_acl_items(config))
       end
       items.concat(runtime_tasks)
-      { schema_version: 1, 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

@@ -1,44 +1,32 @@
 # frozen_string_literal: true
 
-require "ctx_parser/immutable"
+require "forwardable"
+require "ctx_runner/snapshot"
 require_relative "observation"
 require_relative "parser_registry"
 
 module Vxlan
-  # 携带单设备 Fabric 身份及观测结果，不管理资产清单。
-  Snapshot = Data.define(:target, :fabric_key, :observations, :observed_at) do
-    # 事实由不可变领域观测持有；仅复制维度选择，不重复复制事实。
-    def initialize(target:, fabric_key:, observations:, observed_at:)
-      unless observations.is_a?(Hash) && observations.all? { |name, value| value.is_a?(Observation) && value.name == name }
-        raise ArgumentError, "Dimensions must match their observations"
+  # 领域组合公共快照，身份、维度、时间及采集结论共用同一契约。
+  class Snapshot
+    include CtxRunner::Document::Value
+    extend Forwardable
+    def_delegators :@snapshot, :target, :observations, :observed_at, :issues, :collection_status,
+      :observation, :records, :complete?, :same_target?
+    attr_reader :fabric_key
+
+    def initialize(target:, fabric_key:, observations:, observed_at:, issues: [])
+      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
-
-      super(target: CtxParser::Immutable.copy(target), fabric_key: CtxParser::Immutable.copy(fabric_key),
-        observations: observations.to_h { |name, value| [ name, value ] }.freeze, observed_at: observed_at&.dup&.freeze)
-    end
-
-    # 未请求的已知维度保留明确状态；未知维度属于调用错误。
-    def observation(name)
-      unless name == :collection || CiscoNxos::Profile::COMMANDS.key?(name)
-        raise ArgumentError, "Unknown VXLAN dimension"
-      end
-      observations.fetch(name) { Observation.new(name: name, status: :not_requested) }
+      @fabric_key = fabric_key.dup.freeze
+      @snapshot = CtxRunner::Snapshot.new(target: target, observations: observations, observed_at: observed_at,
+        names: CiscoNxos::Profile::COMMANDS.keys, issues: issues)
+      freeze
     end
 
-    # 报告格式独立于 Ruby 成员命名，已有离线证据继续使用 dimensions。
-    def to_h = super.except(:observations).merge(dimensions: observations)
-
-    # 判断所有已选事实是否都有完整证据支持。
-    def complete?
-      selected = observations.values.reject { |dimension| dimension.status == :not_requested }
-      selected.any? && selected.all?(&:complete?)
-    end
-
-    # 展示对象身份与状态，避免泄露原始回显或凭据。
-    def inspect = "#<#{self.class.name} fabric=#{fabric_key.inspect} complete=#{complete?}>"
+    def to_h = @snapshot.to_h.merge(fabric_key: fabric_key)
+    def inspect = "#<#{self.class.name} collection_status=#{collection_status}>"
     alias to_s inspect
-
-    # PP 默认展开 Data 成员，显式沿用脱敏展示。
     def pretty_print(printer) = printer.text(inspect)
   end
 end

data/lib/vxlan/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vxlan
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Gatework contributors
@@ -10,7 +10,7 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: ctx_cli
+  name: forwardable
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -23,66 +23,86 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ctx_cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: ctx_runner
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.5.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.5.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: ctx_parser
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: ctx_driver
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.5.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.5.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: digest
   requirement: !ruby/object:Gem::Requirement