netstack 0.1.1 → 0.2.0

data/lib/netstack/vxlan/collector.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Netstack
+  # Fabric 证据、审计与网段意图；NX-OS 语法保留在 CiscoNxos 中。
+  module Vxlan
+    # 顺序读取明确的目标，保留失败情况与预期覆盖范围。
+    # 配置完整性与运行状态维度分别作为证据记录。
+    class Collector
+      DEFAULT_DIMENSIONS = %i[configuration nve_peers nve_vnis bgp_neighbors].freeze
+
+      def initialize(connector: Connector, clock: -> { Time.now.utc })
+        @connector = connector
+        @clock = clock
+      end
+
+      def collect(targets:, fabric_key:, connection_options: {}, dimensions: DEFAULT_DIMENSIONS)
+        unless targets.is_a?(Array) && !targets.empty? && targets.all?(Target) && targets.map(&:key).uniq.size == targets.size
+          Validation.invalid!("collection needs a nonempty Array of unique Targets")
+        end
+        supported = [:configuration, *CiscoNxos::RuntimeParser::COMMANDS.keys]
+        unless dimensions.is_a?(Array) && !dimensions.empty? && dimensions.uniq == dimensions && (dimensions - supported).empty?
+          Validation.invalid!("unknown or duplicate VXLAN dimensions")
+        end
+        Validation.invalid!("connection_options must be a Hash") unless connection_options.is_a?(Hash)
+        nodes = []
+        runtime = {}
+        collection = {}
+        targets.each do |target|
+          runtime[target.key] = {}
+          if target.platform != "cisco_nxos"
+            collection[target.key] = :unsupported
+            dimensions.reject { |dimension| dimension == :configuration }.each do |dimension|
+              runtime[target.key][dimension] = RuntimeResult.new(dimension: dimension, status: :unsupported)
+            end
+            next
+          end
+          collection[target.key] = :complete
+          begin
+            @connector.open(:cisco_nxos, **connection_options, host: target.host) do |session|
+              dimensions.each do |dimension|
+                command = dimension == :configuration ? "show running-config" : CiscoNxos::RuntimeParser::COMMANDS.fetch(dimension)
+                result = session.execute_script([command])
+                successful = result.success? && result.steps.size == 1
+                unless successful
+                  collection[target.key] = :partial
+                  runtime[target.key][dimension] =
+                    RuntimeResult.new(dimension: dimension, status: :failed, issues: [{ code: result.error&.code || :collection_failed }])
+                  next
+                end
+                output = result.steps.first.output
+                if dimension == :configuration
+                  node = CiscoNxos::ConfigParser.new.parse(output, target: target, complete: true)
+                  nodes << node
+                  collection[target.key] = :partial unless node.complete?
+                else
+                  parsed = CiscoNxos::RuntimeParser.new.parse(dimension, output, complete: true)
+                  runtime[target.key][dimension] = parsed
+                  collection[target.key] = :partial unless parsed.complete?
+                end
+              end
+            end
+          rescue StandardError => e
+            collection[target.key] = nodes.any? { |node| node.key == target.key } || runtime[target.key].any? ? :partial : :failed
+            dimensions.each do |dimension|
+              next if runtime[target.key].key?(dimension) || (dimension == :configuration && nodes.any? { |node| node.key == target.key })
+
+              runtime[target.key][dimension] = RuntimeResult.new(dimension: dimension, status: :failed,
+                                                                 issues: [{ code: e.respond_to?(:code) ? e.code : :collection_failed }])
+            end
+          end
+        end
+        Snapshot.new(fabric: Fabric.new(key: fabric_key, nodes: nodes, expected_node_keys: targets.map(&:key)),
+          runtime: runtime, collection: collection, observed_at: @clock.call)
+      end
+    end
+  end
+end

data/lib/netstack/vxlan/fabric.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Vxlan
+    class Fabric
+      attr_reader :key, :nodes, :expected_node_keys
+
+      def initialize(key:, nodes:, expected_node_keys: nil)
+        @key = Validation.name(key, "fabric key")
+        Validation.invalid!("nodes must be an Array of Node") unless nodes.is_a?(Array) && nodes.all?(Node)
+        Validation.invalid!("fabric contains duplicate node keys") unless nodes.map(&:key).uniq.size == nodes.size
+        expected_node_keys = nodes.map(&:key) if expected_node_keys.nil?
+        Validation.invalid!("expected_node_keys must be an Array") unless expected_node_keys.is_a?(Array)
+        @expected_node_keys = expected_node_keys.map { |name| Validation.name(name, "expected node key") }.freeze
+        Validation.invalid!("fabric contains duplicate expected node keys") unless @expected_node_keys.uniq.size == @expected_node_keys.size
+        Validation.invalid!("fabric contains an unexpected node") unless (nodes.map(&:key) - @expected_node_keys).empty?
+        @nodes = nodes.dup.freeze
+        freeze
+      end
+
+      def vteps = nodes.select(&:vtep?).freeze
+      def spines = nodes.select { |node| node.role == :spine }.freeze
+      def node(key) = nodes.find { |entry| entry.key == key }
+      def complete? = !nodes.empty? && nodes.size == expected_node_keys.size && nodes.all?(&:complete?)
+      def digest = Validation.fingerprint(expected_node_keys: expected_node_keys.sort, nodes: nodes.sort_by(&:key).map { |node| [node.key, node.config_digest] })
+      def to_h = { key: key, nodes: nodes.map(&:to_h), expected_node_keys: expected_node_keys, digest: digest }
+    end
+  end
+end

data/lib/netstack/vxlan/finding.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Vxlan
+    class Finding
+      attr_reader :code, :severity, :node_keys, :message, :details
+
+      def initialize(code:, severity:, message:, node_keys: [], details: {})
+        @code = code.to_sym
+        @severity = severity.to_sym
+        @message = message.dup.freeze
+        @node_keys = Values.copy(node_keys)
+        @details = Values.copy(details)
+        freeze
+      end
+
+      def to_h = { code: code, severity: severity, node_keys: node_keys, message: message, details: details }
+    end
+  end
+end

data/lib/netstack/vxlan/node.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Vxlan
+    # Parsed configuration facts. Missing facts stay absent, with completeness explicit.
+    class Node
+      attr_reader :key, :hostname, :management_ip, :role, :features, :interfaces, :vlan_vnis,
+                  :vrfs, :nve, :evpn, :bgp, :vpc_domain, :acls, :prefix_lists, :route_maps,
+                  :segments, :anycast_mac, :issues, :complete, :config_digest
+
+      def initialize(key:, hostname: nil, management_ip: nil, role: :unknown, features: [], interfaces: {},
+                     vlan_vnis: {}, vrfs: {}, nve: {}, evpn: {}, bgp: {}, vpc_domain: nil,
+                     acls: {}, prefix_lists: {}, route_maps: {}, segments: [], anycast_mac: nil,
+                     complete: false, issues: [], config_digest: nil)
+        @key = Validation.name(key, "node key")
+        @hostname = hostname && Values.text(hostname, name: "hostname").dup.freeze
+        @management_ip = management_ip && Validation.address(management_ip, "management_ip")
+        Validation.invalid!("unknown VXLAN node role") unless %i[leaf border spine unknown].include?(role)
+        Validation.invalid!("complete must be true or false") unless [true, false].include?(complete)
+        @role = role
+        @complete = complete
+        Validation.invalid!("vpc_domain must be a VpcDomain or nil") unless vpc_domain.nil? || vpc_domain.is_a?(VpcDomain)
+        @vpc_domain = vpc_domain
+        @anycast_mac = anycast_mac&.dup&.freeze
+        { features: features, interfaces: interfaces, vlan_vnis: vlan_vnis, vrfs: vrfs, nve: nve,
+          evpn: evpn, bgp: bgp, acls: acls, prefix_lists: prefix_lists, route_maps: route_maps,
+          issues: issues }.each do |name, value|
+          expected = %i[features issues].include?(name) ? Array : Hash
+          Validation.invalid!("#{name} must be a #{expected}") unless value.is_a?(expected)
+          instance_variable_set("@#{name}", Values.copy(value))
+        end
+        Validation.invalid!("segments must be an Array of Segment") unless segments.is_a?(Array) && segments.all?(Segment)
+        @segments = segments.dup.freeze
+        @config_digest = (config_digest || Validation.fingerprint(configuration)).freeze
+        freeze
+      end
+
+      def vtep? = %i[leaf border].include?(role) || !nve.empty?
+      def complete? = complete
+      def segment(vlan_id) = segments.find { |entry| entry.vlan_id == vlan_id }
+
+      def configuration
+        { hostname: hostname, role: role, features: features, interfaces: interfaces, vlan_vnis: vlan_vnis,
+          vrfs: vrfs, nve: nve, evpn: evpn, bgp: bgp, vpc_domain: vpc_domain&.to_h, acls: acls,
+          prefix_lists: prefix_lists, route_maps: route_maps, segments: segments.map(&:to_h), anycast_mac: anycast_mac }
+      end
+
+      def to_h = { key: key, management_ip: management_ip, complete: complete, issues: issues, config_digest: config_digest, **configuration }
+    end
+  end
+end

data/lib/netstack/vxlan/route_policy.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Vxlan
+    # Evaluates supported prefix-list/route-map predicates in device order.
+    class RoutePolicy
+      def advertisement(node, segment)
+        family = node.bgp.fetch(:vrfs, {}).dig(segment.vrf, :address_families, "ipv4 unicast")
+        return :missing unless family && family[:advertise_evpn]
+
+        rules = family.fetch(:redistribute, []).select { |rule| %w[direct connected].include?(rule[:protocol]) }
+        return :missing if rules.empty?
+
+        decisions = rules.map { |rule| rule[:route_map] ? route_map(node, rule[:route_map], segment.prefix) : :permitted }
+        return :permitted if decisions.include?(:permitted)
+
+        decisions.include?(:unknown) ? :unknown : :denied
+      end
+
+      def route_map(node, name, prefix)
+        entries = node.route_maps[name]
+        return :unknown unless entries
+
+        entries.sort_by { |entry| entry[:sequence] }.each do |entry|
+          return :unknown if entry[:additional_matches].any?
+
+          decisions = entry[:prefix_lists].map { |list| prefix_list(node, list, prefix) }
+          return :unknown if decisions.include?(:unknown)
+          next unless decisions.empty? || decisions.include?(:permitted)
+
+          return entry[:action] == :permit ? :permitted : :denied
+        end
+        :denied
+      end
+
+      def prefix_list(node, name, prefix)
+        entries = node.prefix_lists[name]
+        return :unknown unless entries
+
+        network = IPAddr.new(prefix)
+        length = Integer(prefix.split("/").last, 10)
+        entries.sort_by { |entry| entry[:sequence] }.each do |entry|
+          parent = IPAddr.new(entry[:prefix])
+          bits = Integer(entry[:prefix].split("/").last, 10)
+          minimum = entry[:ge] || bits
+          maximum = entry[:le] || (entry[:ge] ? 32 : bits)
+          next unless parent.include?(network) && length.between?(minimum, maximum)
+
+          return entry[:action] == :permit ? :permitted : :denied
+        end
+        :denied
+      rescue ArgumentError
+        :unknown
+      end
+    end
+  end
+end

data/lib/netstack/vxlan/runtime_result.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Vxlan
+    class RuntimeResult
+      STATUSES = %i[complete partial unsupported failed not_requested].freeze
+      attr_reader :dimension, :status, :records, :issues
+
+      def initialize(dimension:, status:, records: [], issues: [])
+        Validation.invalid!("invalid runtime result status") unless STATUSES.include?(status)
+        Validation.invalid!("dimension must be a Symbol or String") unless dimension.is_a?(Symbol) || dimension.is_a?(String)
+        Validation.invalid!("runtime records and issues must be arrays") unless records.is_a?(Array) && issues.is_a?(Array)
+        @dimension = dimension.to_sym
+        @status = status
+        @records = Values.copy(records)
+        @issues = Values.copy(issues)
+        freeze
+      end
+
+      def complete? = status == :complete
+      def to_h = { dimension: dimension, status: status, records: records, issues: issues }
+    end
+  end
+end

data/lib/netstack/vxlan/segment.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Vxlan
+    # A routed L2 segment; IDs and gateway are explicit, never guessed from a name.
+    class Segment
+      attr_reader :vlan_id, :vni, :vrf, :prefix, :gateway, :anycast, :acl_bindings
+
+      def initialize(vlan_id:, vni:, vrf:, prefix:, gateway:, anycast: true, acl_bindings: {})
+        @vlan_id = Validation.integer(vlan_id, "vlan_id", 1..4094)
+        @vni = Validation.integer(vni, "vni", 1..16_777_215)
+        @vrf = Validation.name(vrf, "vrf")
+        @prefix = Validation.prefix(prefix)
+        @gateway = Validation.address(gateway, "gateway")
+        network = IPAddr.new(@prefix)
+        ip = IPAddr.new(@gateway)
+        Validation.invalid!("gateway must be inside prefix") unless network.ipv4? && ip.ipv4? && network.include?(ip)
+        Validation.invalid!("gateway cannot be the network or broadcast address") if prefix_length < 31 && [network.to_range.first,
+                                                                                                            network.to_range.last].include?(ip)
+        Validation.invalid!("anycast must be true or false") unless [true, false].include?(anycast)
+        Validation.invalid!("acl_bindings must map in/out to ACL names") unless acl_bindings.is_a?(Hash) && (acl_bindings.keys - %i[in out]).empty?
+        acl_bindings.each_value { |value| Validation.name(value, "ACL name") }
+        @anycast = anycast
+        @acl_bindings = Values.copy(acl_bindings)
+        freeze
+      end
+
+      def prefix_length = Integer(prefix.split("/").last, 10)
+      def interface_address = "#{gateway}/#{prefix_length}"
+      def identity = [vrf, prefix].freeze
+      def to_h = { vlan_id: vlan_id, vni: vni, vrf: vrf, prefix: prefix, gateway: gateway, anycast: anycast, acl_bindings: acl_bindings }
+      def ==(other) = other.is_a?(Segment) && to_h == other.to_h
+    end
+  end
+end

data/lib/netstack/vxlan/segment_plan.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Vxlan
+    class SegmentPlan
+      attr_reader :segment, :plans, :status, :fabric_key, :baseline_digest, :target_count, :complete_count
+
+      def initialize(segment:, plans:, status:, fabric_key:, baseline_digest:, target_count:, complete_count:)
+        @segment = segment
+        @plans = plans.dup.freeze
+        @status = status
+        @fabric_key = fabric_key.dup.freeze
+        @baseline_digest = baseline_digest.dup.freeze
+        @target_count = target_count
+        @complete_count = complete_count
+        freeze
+      end
+
+      def to_h
+        { segment: segment.to_h, plans: plans.map(&:payload), status: status, fabric_key: fabric_key,
+          baseline_digest: baseline_digest, target_count: target_count, complete_count: complete_count }
+      end
+    end
+  end
+end

data/lib/netstack/vxlan/segment_planner.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Vxlan
+    # 基于传入的 Fabric 进行纯增量规划；冲突或不完整的基线
+    # 会阻止命令生成；已经存在的组件不重复改写。
+    class SegmentPlanner
+      def plan(fabric:, segment:, target_keys: nil, replication: :bgp, multicast_group: nil, prefix_list: nil)
+        Validation.invalid!("fabric and segment must be VXLAN domain objects") unless fabric.is_a?(Fabric) && segment.is_a?(Segment)
+        Validation.invalid!("replication must be bgp or multicast") unless %i[bgp multicast].include?(replication)
+        if replication == :multicast
+          multicast_group = Validation.address(multicast_group, "multicast_group")
+          Validation.invalid!("multicast group must be in 224.0.0.0/4") unless IPAddr.new("224.0.0.0/4").include?(IPAddr.new(multicast_group))
+        end
+        Validation.name(prefix_list, "prefix-list") if prefix_list
+        nodes = selected_nodes(fabric, target_keys)
+        validate_conflicts!(fabric, segment)
+        plans = []
+        complete_count = 0
+        observed_count = 0
+        nodes.each do |node|
+          validate_node!(node, segment)
+          components = missing_components(node, segment, replication, multicast_group, prefix_list)
+          observed_count += 1 if node.vlan_vnis.key?(segment.vlan_id) || node.nve.fetch(:members, {}).key?(segment.vni)
+          if components.empty?
+            complete_count += 1
+            next
+          end
+          sequence = prefix_list && next_sequence(node, prefix_list)
+          commands = CiscoNxos::SegmentRenderer.new.render(segment: segment, components: components, nve_interface: node.nve.fetch(:interface),
+                                                           replication: replication, multicast_group: multicast_group,
+                                                           prefix_list: prefix_list, prefix_sequence: sequence)
+          target = Target.new(key: node.key, host: node.management_ip, platform: :cisco_nxos, attributes: { role: node.role, fabric_key: fabric.key })
+          expected = { segment: segment.to_h, replication: replication, multicast_group: multicast_group, prefix_list: prefix_list }
+          step = Deployment::Step.new(id: "segment-#{segment.vlan_id}-#{segment.vni}", action: "vxlan_segment",
+                                      parameters: { commands: commands, components: components }, expected: expected)
+          plans << Deployment::Plan.new(target: target, steps: [step], preconditions: { config_digest: node.config_digest, hostname: node.hostname },
+                                        metadata: { domain: "vxlan", fabric_key: fabric.key, baseline_digest: fabric.digest,
+                                                    prefix: segment.prefix, vrf: segment.vrf })
+        end
+        SegmentPlan.new(segment: segment, plans: plans, status: if plans.empty?
+                                                                  :existing
+                                                                else
+                                                                  observed_count.positive? ? :partial : :new
+                                                                end,
+                        fabric_key: fabric.key, baseline_digest: fabric.digest, target_count: nodes.size, complete_count: complete_count)
+      end
+
+      private
+
+      def selected_nodes(fabric, keys)
+        Validation.invalid!("fabric evidence must be complete before planning", code: :incomplete_snapshot) unless fabric.complete?
+        keys ||= fabric.vteps.map(&:key)
+        Validation.invalid!("target_keys must be unique nonempty node keys") unless keys.is_a?(Array) && !keys.empty? && keys.uniq.size == keys.size
+        nodes = keys.map { |key| fabric.node(key) }
+        Validation.invalid!("all selected targets must be VTEPs") unless nodes.all? { |node| node&.vtep? }
+        nodes
+      end
+
+      def validate_conflicts!(fabric, segment)
+        network = IPAddr.new(segment.prefix)
+        fabric.nodes.each do |node|
+          existing_vni = node.vlan_vnis[segment.vlan_id]
+          conflict!(node, :vlan_conflict) if existing_vni && existing_vni != segment.vni
+          conflict!(node, :vni_conflict) if node.vlan_vnis.any? { |vlan, vni| vni == segment.vni && vlan != segment.vlan_id }
+          conflict!(node, :vni_conflict) if node.vrfs.values.any? { |vrf| vrf[:vni] == segment.vni }
+          node.segments.each do |existing|
+            same_address = existing.vrf == segment.vrf && existing.prefix == segment.prefix && existing.gateway == segment.gateway
+            conflict!(node, :segment_conflict) if existing.vlan_id == segment.vlan_id && !same_address
+            next unless existing.vrf == segment.vrf
+
+            other = IPAddr.new(existing.prefix)
+            conflict!(node, :prefix_conflict) if (network.include?(other) || other.include?(network)) && existing.vlan_id != segment.vlan_id
+          end
+        end
+      end
+
+      def validate_node!(node, segment)
+        Validation.invalid!("management IP is required", code: :management_ip_missing, details: { node_key: node.key }) unless node.management_ip
+        conflict!(node, :nve_missing) unless node.nve[:interface] && node.nve[:source_interface] && node.nve[:host_reachability] == "bgp"
+        vrf = node.vrfs[segment.vrf]
+        conflict!(node, :vrf_prerequisite_missing) unless vrf && vrf[:vni] && node.nve.fetch(:members, {}).dig(vrf[:vni], :associate_vrf)
+        conflict!(node, :anycast_mac_missing) if segment.anycast && !node.anycast_mac
+        segment.acl_bindings.each_value { |name| conflict!(node, :acl_missing) unless node.acls.key?(name) }
+        existing = node.interfaces["Vlan#{segment.vlan_id}"] || node.interfaces["vlan#{segment.vlan_id}"]
+        return unless existing
+
+        conflict!(node, :svi_vrf_conflict) if existing[:vrf] && existing[:vrf] != segment.vrf
+        conflict!(node, :svi_address_conflict) if existing[:addresses].any? && existing[:addresses] != [segment.interface_address]
+        existing[:acl_bindings].each do |direction, name|
+          conflict!(node, :acl_conflict) if segment.acl_bindings[direction] && segment.acl_bindings[direction] != name
+        end
+        conflict!(node, :anycast_conflict) if existing[:anycast] && !segment.anycast
+      end
+
+      def missing_components(node, segment, replication, multicast_group, prefix_list)
+        missing = []
+        missing << :vlan unless node.vlan_vnis[segment.vlan_id] == segment.vni
+        interface = node.interfaces["Vlan#{segment.vlan_id}"] || {}
+        missing << :svi_vrf unless interface[:vrf] == segment.vrf
+        missing << :svi_address unless interface[:addresses] == [segment.interface_address]
+        missing << :svi_enable if interface.empty? || interface[:shutdown] == true
+        missing << :svi_anycast if segment.anycast && !interface[:anycast]
+        segment.acl_bindings.each { |direction, name| missing << :"svi_acl_#{direction}" unless interface.fetch(:acl_bindings, {})[direction] == name }
+        member = node.nve.fetch(:members, {})[segment.vni]
+        if member
+          incompatible = member[:associate_vrf] || (member[:replication] && member[:replication] != replication)
+          incompatible ||= member[:multicast_group] && member[:multicast_group] != multicast_group
+          conflict!(node, :nve_member_conflict) if incompatible
+        end
+        missing << :nve unless member && (replication == :bgp ? member[:replication] == :bgp : member[:multicast_group] == multicast_group)
+        evpn = node.evpn[segment.vni]
+        if evpn
+          conflict!(node, :evpn_type_conflict) unless evpn[:type] == :l2
+          targets = evpn[:route_targets]
+          directions = targets.flat_map { |target| target[:direction] == :both ? %i[import export] : [target[:direction]] }
+          unless evpn[:rd] && (%i[import export] - directions).empty?
+            conflict!(node, :evpn_policy_conflict) if targets.any? { |target| target[:target] != "auto" } || (evpn[:rd] && evpn[:rd] != "auto")
+            missing << :evpn
+          end
+        else
+          missing << :evpn
+        end
+        if prefix_list && RoutePolicy.new.advertisement(node, segment) != :permitted
+          validate_advertisement!(node, segment, prefix_list)
+          missing << :advertisement
+        end
+        missing
+      end
+
+      def validate_advertisement!(node, segment, prefix_list)
+        family = node.bgp.fetch(:vrfs, {}).dig(segment.vrf, :address_families, "ipv4 unicast")
+        conflict!(node, :advertisement_prerequisite_missing) unless family && family[:advertise_evpn]
+        routes = family[:redistribute].select { |rule| %w[direct connected].include?(rule[:protocol]) && rule[:route_map] }
+        matching = routes.any? do |rule|
+          entries = node.route_maps[rule[:route_map]]
+          entries && entries.size == 1 && entries.first[:action] == :permit &&
+            entries.first[:additional_matches].empty? && entries.first[:prefix_lists] == [prefix_list]
+        end
+        conflict!(node, :advertisement_policy_unsupported) unless matching && node.prefix_lists.key?(prefix_list)
+        # An earlier deny would shadow an appended permit; do not claim remediation.
+        trial = node.prefix_lists[prefix_list]
+        conflict!(node, :advertisement_policy_conflict) if trial.any? { |entry| entry[:action] == :deny }
+      end
+
+      def next_sequence(node, prefix_list)
+        value = node.prefix_lists.fetch(prefix_list, []).map { |entry| entry[:sequence] }.max.to_i + 5
+        Validation.integer(value, "prefix-list sequence", 1..4_294_967_294)
+      end
+
+      def conflict!(node, code)
+        Validation.invalid!("VXLAN planning prerequisite or conflict: #{code}", code: code, details: { node_key: node.key })
+      end
+    end
+  end
+end

data/lib/netstack/vxlan/snapshot.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Netstack
+  module Vxlan
+    class Snapshot
+      attr_reader :fabric, :runtime, :collection, :observed_at
+
+      def initialize(fabric:, runtime: {}, collection: {}, observed_at: Time.now.utc)
+        Validation.invalid!("fabric must be a Fabric") unless fabric.is_a?(Fabric)
+        Validation.invalid!("runtime and collection must be hashes") unless runtime.is_a?(Hash) && collection.is_a?(Hash)
+        @fabric = fabric
+        @collection = Values.copy(collection)
+        @runtime = runtime.to_h do |key, dimensions|
+          Validation.invalid!("runtime dimensions must contain RuntimeResult values") unless dimensions.is_a?(Hash) && dimensions.values.all?(RuntimeResult)
+          [key.dup.freeze, dimensions.dup.freeze]
+        end.freeze
+        @observed_at = observed_at.is_a?(Time) ? observed_at.getutc.iso8601(6).freeze : Time.iso8601(observed_at).getutc.iso8601(6).freeze
+        freeze
+      end
+
+      def complete?
+        fabric.complete? && collection.values.all? { |value| value == :complete } && runtime.values.all? { |dimensions| dimensions.values.all?(&:complete?) }
+      end
+
+      def to_h
+        { fabric: fabric.to_h, runtime: runtime.transform_values do |dimensions|
+          dimensions.transform_values(&:to_h)
+        end, collection: collection, observed_at: observed_at }
+      end
+    end
+  end
+end

data/lib/netstack/vxlan/validation.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "digest"
+require "json"
+
+module Netstack
+  module Vxlan
+    # Validation and canonical fingerprints shared by the VXLAN value objects.
+    module Validation
+      module_function
+
+      def integer(value, name, range)
+        invalid!("#{name} must be an Integer in #{range}") unless value.is_a?(Integer) && range.cover?(value)
+        value
+      end
+
+      def name(value, field)
+        invalid!("#{field} must be a nonempty CLI identifier") unless value.is_a?(String) && /\A[a-zA-Z0-9_.:-]+\z/.match?(value)
+        value.dup.freeze
+      end
+
+      def address(value, field = "address")
+        invalid!("#{field} must be an IP address") unless value.is_a?(String) && !value.include?("/")
+        IPAddr.new(value).to_s.freeze
+      rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+        invalid!("#{field} must be an IP address")
+      end
+
+      def prefix(value)
+        invalid!("prefix must be an IPv4 network in CIDR notation") unless value.is_a?(String) && %r{\A\d+(?:\.\d+){3}/\d+\z}.match?(value)
+        network = IPAddr.new(value)
+        bits = Integer(value.split("/").last, 10)
+        invalid!("prefix must specify a network address") unless network.ipv4? && bits.between?(0, 32) && network.to_s == value.split("/").first
+        "#{network}/#{bits}".freeze
+      rescue IPAddr::InvalidAddressError
+        invalid!("prefix must be an IPv4 network in CIDR notation")
+      end
+
+      def fingerprint(value)
+        Digest::SHA256.hexdigest(JSON.generate(canonical(value)))
+      end
+
+      def canonical(value)
+        case value
+        when Hash then value.keys.sort_by(&:to_s).to_h { |key| [key.to_s, canonical(value.fetch(key))] }
+        when Array then value.map { |item| canonical(item) }
+        when Symbol then value.to_s
+        else value.respond_to?(:to_h) ? canonical(value.to_h) : value
+        end
+      end
+
+      def invalid!(message, code: :invalid_vxlan_input, details: {})
+        raise InputError.new(message, code: code, stage: :validation, details: details)
+      end
+    end
+  end
+end

data/lib/netstack/vxlan/verifier.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Vxlan
+    # 根据解析后的回读确认配置意图；不证明实际流量转发成功。
+    # 证据不完整或不匹配时保留未知状态，不能据此授权重放。
+    class Verifier
+      def verify(node:, expected:)
+        return { status: :unknown, evidence: { reason: :configuration_incomplete } } unless node.complete?
+
+        expected = symbolize(expected)
+        segment = Segment.new(**expected.fetch(:segment))
+        actual = node.segment(segment.vlan_id)
+        missing = []
+        missing << :vlan unless node.vlan_vnis[segment.vlan_id] == segment.vni
+        unless actual && actual.vrf == segment.vrf && actual.prefix == segment.prefix && actual.gateway == segment.gateway && actual.anycast == segment.anycast
+          missing << :svi
+        end
+        # SVI 标志和引用不能证明依赖仍存在；回读须保持规划时要求的前提。
+        missing << :anycast_mac if segment.anycast && !node.anycast_mac
+        missing << :acl unless actual && segment.acl_bindings.all? { |direction, name| actual.acl_bindings[direction] == name && node.acls.key?(name) }
+        missing << :svi_shutdown if node.interfaces.dig("Vlan#{segment.vlan_id}", :shutdown) == true
+        member = node.nve.fetch(:members, {})[segment.vni]
+        replication_ok = if expected[:replication].to_sym == :bgp
+                           member && member[:replication] == :bgp
+                         else
+                           member && member[:multicast_group] == expected[:multicast_group]
+                         end
+        missing << :nve unless member && !member[:associate_vrf] && replication_ok
+        evpn = node.evpn[segment.vni]
+        directions = if evpn
+                       evpn[:route_targets].flat_map { |target| target[:direction] == :both ? %i[import export] : [target[:direction]] }
+                     else
+                       []
+                     end
+        missing << :evpn unless evpn && evpn[:type] == :l2 && evpn[:rd] && (%i[import export] - directions).empty?
+        missing << :advertisement if expected[:prefix_list] && RoutePolicy.new.advertisement(node, segment) != :permitted
+        { status: missing.empty? ? :verified : :unknown, evidence: { config_digest: node.config_digest, missing: missing } }
+      end
+
+      private
+
+      def symbolize(value)
+        case value
+        when Hash then value.to_h { |key, entry| [key.to_sym, symbolize(entry)] }
+        when Array then value.map { |entry| symbolize(entry) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/netstack/vxlan/vpc_domain.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Netstack
+  module Vxlan
+    class VpcDomain
+      attr_reader :id, :peer_keepalive, :peer_links, :member_ports, :peer_gateway
+
+      def initialize(id:, peer_keepalive: {}, peer_links: [], member_ports: {}, peer_gateway: false)
+        @id = Validation.integer(id, "vPC domain", 1..1000)
+        @peer_keepalive = Values.copy(peer_keepalive)
+        @peer_links = Values.copy(peer_links)
+        @member_ports = Values.copy(member_ports)
+        @peer_gateway = peer_gateway
+        freeze
+      end
+
+      def to_h = { id: id, peer_keepalive: peer_keepalive, peer_links: peer_links, member_ports: member_ports, peer_gateway: peer_gateway }
+    end
+  end
+end