vxlan 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cd74f1778008071770a76681129f64d7fc8d803ca27336fbac450147e33cd01
-  data.tar.gz: d4ba8a592e430b4e8c2a81e2218fe65f70c617d5fce7f60744d893a734a80b53
+  metadata.gz: c96781edce4b5dcc8990ced65d1287cfb86ee2c431ee3c0b0714365513955d75
+  data.tar.gz: '0187135b1f3cff8988732b9fb3ed58633e780b3538b569b1ea611f87d09af08a'
 SHA512:
-  metadata.gz: e45e95ed6294d0f1ae0014d60ef13b1f8fad1f60a5832815b46966e1159d35b63159700410afe0f1191cb05155806b0ee5ad73050f27019e76646dfc462a5d63
-  data.tar.gz: 84d292f0dc18f67f949a73cd545293556d5e24722d995a9c161eb5a2889a89bc5cbf4afce379da9660c8bf803741a74b6b5e1ec63d47e9adac2d6214bfc65cfc
+  metadata.gz: a5386c55fa4f48e6e121ac63dbca3c8148754857df0fa68841d345301aadf6f1678dc682d86713030110203de4fc8f7f22ed2d2fbb44135bebb9e39157df6386
+  data.tar.gz: 5c1434eb7eac8ea5649e136523020579c1abf6d0ae57309ee20335989c164922789e70ca62322d55de1775752eb5902b805c50ef80d7cf48151e1968a449d3fe

data/CHANGELOG.md

@@ -4,6 +4,17 @@ Changes to the public contract are recorded here. Versions follow Semantic Versi
 
 ## Unreleased
 
+## 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.
+
 ## 0.5.1 (2026-10-24)
 
 - Validate EVPN configured-peer totals within each VRF and address-family block, retain administrative shutdown and unknown AS identities, and preserve state-valued prefix totals.

data/README-zh.md

@@ -45,7 +45,7 @@ output = <<~CLI
   Neighbor ID Pri State Up Time Address Interface
   192.0.2.2 1 FULL/ - 1d 192.0.2.3 Eth1/1
 CLI
-observation = Vxlan::RuntimeParser.new.parse(:ospf_neighbors, output, complete: true)
+observation = Vxlan::RuntimeParser.new(platform: :cisco_nxos).parse(:ospf_neighbors, output, complete: true)
 puts "OSPF parse status: #{observation.status}"
 puts "Neighbors: #{observation.records.size}"
 observation.records.each { |record| p record }
@@ -136,3 +136,10 @@ MIT，见 [LICENSE](LICENSE)。
 `vxlan collect` 默认输出逐设备诊断，使用 `--scripts` 可选导出配置建议；`vxlan review --batch DIR` 可离线补生成既有报告的候选配置、条件回退和只读验收命令。导出不会执行变更；独立 `apply --plan FILE --item ID` 必须在真实终端明确确认，配置漂移或失败即停止。详见[修复建议说明](docs/remediation.md)。 业务分层、会话所有权与执行边界见[架构说明](docs/architecture-zh.md)。
 
 报告阅读顺序与 net-connector topology 一致：`summary.txt` → `devices/*.txt` → `scripts/*.cfg`。不生成 Markdown 报告。所有可执行增量汇总于带 SHA256 校验的 `plan.json`，通过 `vxlan apply --plan plan.json --item ID` 选择一项并交互确认。
+
+
+## API 迁移
+
+`RuntimeParser.new(platform:, model: nil)` 固定解析平台；`parse(name, text, complete: false, command: nil)` 与 `parse_many(names, text, complete: false, command: nil)` 返回领域 Observation。`Snapshot.new(observations: ...)`、`#observations`、`#observation(name)` 是统一 Ruby API，旧 `dimensions` 成员及 Wireless `dimension` 入口已移除。已知未请求维度返回 `not_requested`，未知名称抛出 `ArgumentError`；持久化 JSON 仍保留 `dimensions` 字段。
+
+动态清单使用 `Netdisco::Catalog`；选中地址的任何重复记录（包括另一平台）都会阻止连接。范围外冲突只输出安全诊断。平台 `NC_<PLATFORM>_ENABLE_PASSWORD` 优先于 `NC_ENABLE_PASSWORD`。

data/README.md

@@ -45,7 +45,7 @@ output = <<~CLI
   Neighbor ID Pri State Up Time Address Interface
   192.0.2.2 1 FULL/ - 1d 192.0.2.3 Eth1/1
 CLI
-observation = Vxlan::RuntimeParser.new.parse(:ospf_neighbors, output, complete: true)
+observation = Vxlan::RuntimeParser.new(platform: :cisco_nxos).parse(:ospf_neighbors, output, complete: true)
 puts "OSPF parse status: #{observation.status}"
 puts "Neighbors: #{observation.records.size}"
 observation.records.each { |record| p record }
@@ -142,3 +142,12 @@ Review output follows the net-connector topology layout: `summary.txt`, `summary
 Apply returns `2` on failure and `130` on interruption even if stderr cannot accept diagnostics. Existing execution journals retain uncertain device effects; commands are never replayed automatically. Unexpected positional arguments are rejected, including after `--help`.
 
 Offline review requires `snapshot.target.host` to match the canonical device host. Reports without target identity must be collected again; the unbound legacy format is no longer accepted.
+
+
+## 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.
+
+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)。

data/examples/offline.rb

@@ -9,7 +9,7 @@ output = <<~CLI
   Neighbor ID Pri State Up Time Address Interface
   192.0.2.2 1 FULL/ - 1d 192.0.2.3 Eth1/1
 CLI
-observation = Vxlan::RuntimeParser.new.parse(:ospf_neighbors, output, complete: true)
+observation = Vxlan::RuntimeParser.new(platform: :cisco_nxos).parse(:ospf_neighbors, output, complete: true)
 puts "OSPF parse status: #{observation.status}"
 puts "Neighbors: #{observation.records.size}"
 observation.records.each { |record| p record }

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/cli/apply.rb

@@ -1,14 +1,9 @@
 # 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 "vxlan"
 require_relative "report"
 require_relative "../change_plan"
@@ -35,100 +30,44 @@ module Vxlan
       # 每次只发一条命令；失败立即交还宿主，原始输出不进入终端和日志报告。
       def write(command)
         result = @native.execute_command(command.strip, output_sensitive: true)
-        raise IOError, "Device command is unconfirmed" unless result.success? && result.steps.one?
+        raise IOError, "Device command is unconfirmed" unless result.success? && result.steps.one? && result.steps.first.command.text == command.strip
         true
       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 +76,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,17 +34,27 @@ module Vxlan
       def load_network
         require "net/connector"
       rescue LoadError
-        raise LoadError, "Online collection requires net-connector >= 0.18.0; add it to the host Gemfile or run gem install net-connector", cause: nil
+        raise LoadError, "Online collection requires net-connector >= 0.20.0; add it to the host Gemfile or run gem install net-connector", cause: nil
       end
 
-      # YAML 静态设备或显式 Netdisco 来源二选一；所有重复地址在连接前拒绝。
+      # YAML 静态设备或显式 Netdisco 来源二选一；选中地址的所有冲突记录在连接前拒绝。
       def inventory(options, progress:)
         values = options.values
+        selection = Net::Connector::Inventory::Filters.selection(values)
         rows = if options.dynamic_inventory?
           progress.reading_inventory
           settings = options.netdisco_settings
-          Net::Connector::Netdisco::Fleet.new(settings: settings).devices.filter_map do |device|
-            next unless device.ready? && device.vendor == :cisco_nxos
+          policy = settings.snapshot(mode: :inventory)
+          devices = Net::Connector::Netdisco::Catalog.new(settings: settings).devices(policy: policy)
+          devices.filter_map(&:issue).tally.each { |code, count| progress.notice("Inventory: #{code}=#{count}") }
+          devices.filter_map do |device|
+            next unless device.vendor == :cisco_nxos
+            platform = "cisco_nxos"
+            if device.issue == :duplicate_host && policy.rules.selected?(device.host, device.vendor, name: device.name, model: device.model) &&
+                selection.selected?(device.host, platform, name: device.name || device.host, model: device.model)
+              raise CtxCli::Collection::Error, "Duplicate management address in selected inventory"
+            end
+            next unless device.ready?
             { "host" => device.host, "name" => device.name || device.host, "model" => device.model }
           end
         else
@@ -52,7 +62,6 @@ module Vxlan
         end
         targets = options.normalize_devices(rows)
         total = targets.size
-        selection = Net::Connector::Inventory::Filters.selection(values)
         selected = targets.select do |device|
           selection.selected?(device.fetch("host"), "cisco_nxos", name: device["name"], model: device["model"])
         end
@@ -86,16 +95,10 @@ module Vxlan
 
       # 缺失用户名时不尝试连接；密码允许省略以支持明确的 SSH key/agent。
       def credentials!(options)
-        username = secret(options, "NC_CISCO_NXOS_USERNAME") || secret(options, "NC_DEVICE_USERNAME")
-        raise CtxCli::Collection::Error, "Set NC_DEVICE_USERNAME or NC_CISCO_NXOS_USERNAME; provide a password through the environment or use an SSH key/agent" unless username
-        options.values.fetch("ssh").transform_keys(&:to_sym).merge(username: username,
-          password: secret(options, "NC_CISCO_NXOS_PASSWORD") || secret(options, "NC_DEVICE_PASSWORD"), enable_password: secret(options, "NC_ENABLE_PASSWORD"))
-      end
-
-      # 空白环境值视为缺失，不修改或回显凭据。
-      def secret(options, name)
-        value = options.environment[name]
-        value unless value.nil? || value.strip.empty?
+        require "net/connector/credentials"
+        credentials = Net::Connector::Credentials.new(env: options.environment).resolve(platform: :cisco_nxos)
+        raise CtxCli::Collection::Error, "Set NC_DEVICE_USERNAME or platform NC_*_USERNAME; provide a password through the environment or use an SSH key/agent" unless credentials
+        options.values.fetch("ssh").transform_keys(&:to_sym).merge(credentials)
       end
 
       # 每个任务使用独立 Collector 和会话；公共执行器负责有界并发和线程回收。
@@ -114,7 +117,7 @@ module Vxlan
         snapshot
       end
 
-      private :load_network, :credentials!, :secret
+      private :load_network, :credentials!
     end
   end
 end

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.18.0"
+gem "net-connector", "~> 0.20.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.18.0; reading .env also requires dotenv", cause: nil
+        raise LoadError, "Collection configuration requires net-connector >= 0.20.0; reading .env also requires dotenv", cause: nil
       end
 
       # 公共与专用文件先合并，进程值和 CLI 最后覆盖；数组不追加设备。

data/lib/vxlan/cli/parse.rb

@@ -37,7 +37,7 @@ module Vxlan
         observation = if options[:dimension] == :configuration
           Vxlan::Config.new(model: options[:model]).parse(body, complete: options[:complete])
         else
-          Vxlan::RuntimeParser.new(model: options[:model]).parse(options[:dimension], body, complete: options[:complete])
+          Vxlan::RuntimeParser.new(platform: :cisco_nxos, model: options[:model]).parse(options[:dimension], body, complete: options[:complete])
         end
         if options[:json]
           @output.json(observation.to_h)

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"
 
@@ -37,7 +38,7 @@ module Vxlan
         name = self.class.device_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"

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"
@@ -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", device: document.fetch("device"), 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,10 +66,10 @@ 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"
           summary[:plan_sha256] = Digest::SHA256.hexdigest(body)
@@ -113,7 +114,7 @@ module Vxlan
           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|

data/lib/vxlan/cli/review.rb

@@ -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.snapshot(target)
       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,7 +44,10 @@ 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.snapshot(target)
+      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
@@ -60,7 +63,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 +78,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, dimensions: 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"
@@ -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

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", device: @document["device"],
         observed_at: @document.dig("snapshot", "observed_at"), items: items, counts: items.map { |item| item[:status] }.tally }
     end
 

data/lib/vxlan/runtime_parser.rb

@@ -7,16 +7,24 @@ module Vxlan
   # 将纯平台解析事实封装为对应 VXLAN 维度观测。
   class RuntimeParser
     # 按请求的平台和型号选择运行解析行为。
-    def initialize(platform: :cisco_nxos, model: nil)
+    def initialize(platform:, model: nil)
       @profile = ParserRegistry.fetch(platform, model: model)
     end
 
     # 拒绝配置维度，仅解析所选 VXLAN 运行查询。
-    def parse(name, text, complete: false)
-      raise ArgumentError, "Unsupported runtime dimension" if name == :configuration || !@profile.commands.key?(name)
+    def parse(name, text, complete: false, command: nil)
+      parse_many([ name ], text, complete: complete, command: command).fetch(name)
+    end
 
-      result = @profile.parse(name, text, complete: complete)
-      Observation.new(name: name, **result.to_h)
+    # 单条正文只允许投影属于同一声明命令的运行维度。
+    def parse_many(names, text, complete: false, command: nil)
+      unless names.is_a?(Array) && names.any? && names.uniq == names &&
+          names.all? { |name| name.is_a?(Symbol) && name != :configuration && @profile.commands.key?(name) }
+        raise ArgumentError, "Unsupported runtime dimensions"
+      end
+      @profile.parse_many(names, text, complete: complete, command: command).to_h do |name, result|
+        [ name, Observation.new(name: name, **result.to_h) ]
+      end
     end
   end
 end

data/lib/vxlan/snapshot.rb

@@ -1,32 +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, :dimensions, :observed_at) do
-    # 事实由不可变领域观测持有；仅复制维度选择，不重复复制事实。
-    def initialize(target:, fabric_key:, dimensions:, observed_at:)
-      unless dimensions.is_a?(Hash) && dimensions.all? { |name, value| value.is_a?(Observation) && value.name == name }
-        raise ArgumentError, "Dimensions must match their observations"
-      end
-
-      super(target: CtxParser::Immutable.copy(target), fabric_key: CtxParser::Immutable.copy(fabric_key),
-        dimensions: dimensions.to_h { |name, value| [ name, value ] }.freeze, observed_at: observed_at&.dup&.freeze)
-    end
+  # 领域组合公共快照，身份、维度、时间及采集结论共用同一契约。
+  class Snapshot
+    include CtxRunner::Document::Value
+    extend Forwardable
+    def_delegators :@snapshot, :target, :observations, :observed_at, :issues, :collection_status,
+      :observation, :complete?, :same_target?
+    attr_reader :fabric_key
 
-    # 判断所有已选事实是否都有完整证据支持。
-    def complete?
-      selected = dimensions.values.reject { |dimension| dimension.status == :not_requested }
-      selected.any? && selected.all?(&:complete?)
+    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
+      @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
 
-    # 展示对象身份与状态，避免泄露原始回显或凭据。
-    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.5.1"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vxlan
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.7.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,48 +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.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: ctx_runner
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: ctx_parser
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: ctx_driver
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: digest
   requirement: !ruby/object:Gem::Requirement