ctx_checker 0.1.0

data/lib/ctx_checker/radware_alteon/parsers/stats_sys_ntp.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "../../parsers/base"
+require "ctx_parser/result_set"
+
+module CtxChecker
+  module RadwareAlteon
+    module Parsers
+      # 累计 NTP 请求与更新次数不能证明当前同步状态。
+      class StatsSysNtp < CtxChecker::Parsers::Base
+        COUNTERS = { "Requests Sent" => "requests_sent", "Responses Received" => "responses_received", "Updates" => "updates" }.freeze
+
+        private
+
+        # 计数器完整性独立于当前 NTP 状态是否可用。
+        def parse_output(text, complete:)
+          source = clean(text)
+          rows, headers, sections, time_fields = [], 0, [], []
+          counter_issues, ntp_issues, section = [], [], nil
+          source.each_line.with_index(1) do |raw, number|
+            line = raw.strip
+            next if line.empty? || /\A-+\z/.match?(line)
+
+            if line == "NTP server statistics:"
+              headers += 1
+            elsif (match = /\A(Primary|Secondary) Server:\z/.match(line))
+              section = match[1].downcase
+              sections << section
+            elsif (match = /\A(Requests Sent|Responses Received|Updates):\s*(.*?)\z/.match(line))
+              row = counter(section, match[1], match[2], number, counter_issues)
+              rows << row if row
+            elsif /\ALast update based on response from (?:primary|secondary) server\.\z/.match?(line)
+              time_fields << :server
+            elsif (match = /\A(Last update time|Current system time):\s*(.*?)\z/.match(line))
+              field = match[1] == "Last update time" ? :last_update : :current_time
+              time_fields << field
+              ntp_issues << { code: :invalid_ntp_time, field: field, line: number } unless valid_time?(match[2])
+            else
+              issue = { code: :unrecognized_ntp_line, line: number }
+              counter_issues << issue
+              ntp_issues << issue
+            end
+          end
+          counter_issues << { code: :missing_ntp_statistics_header } unless headers == 1
+          %w[primary secondary].each do |peer|
+            counter_issues << { code: :incomplete_ntp_counter_section, component: peer } unless sections.count(peer) == 1 && rows.count { |row| row[:component] == "ntp/#{peer}" } == COUNTERS.size
+          end
+          ntp_issues << { code: :ntp_system_status_unavailable }
+          ntp_issues << { code: :ntp_last_sync_offset_unknown } if time_fields.include?(:last_update)
+          %i[server last_update current_time].each do |field|
+            ntp_issues << { code: :ambiguous_ntp_time_field, field: field, count: time_fields.count(field) } unless time_fields.count(field) == 1
+          end
+          ntp_rows = headers.positive? ? [ { component: "system", synchronized: nil, last_sync_status: :unknown, last_sync_at: nil } ] : []
+          CtxParser::ResultSet.new(results: {
+            ntp: build_result(ntp_rows, complete: complete, recognized: headers.positive?, issues: ntp_issues, identity: [ :component ]),
+            device_counters: build_result(rows, complete: complete, recognized: rows.any?, issues: counter_issues, identity: %i[component metric])
+          })
+        end
+
+        # 仅暴露具名整数计数器，不通过运算推导故障或重置次数。
+        def counter(section, label, raw, number, issues)
+          unless section
+            issues << { code: :ntp_counter_section_missing, line: number }
+            return
+          end
+          value = /\A\d+\z/.match?(raw) ? Integer(raw, 10) : nil
+          issues << { code: :invalid_ntp_counter, line: number } unless value
+          { component: "ntp/#{section}", metric: COUNTERS.fetch(label), category: :informational,
+            value: value, discontinuity: nil, sampled_at: nil }
+        end
+
+        # 校验本地时间戳，不虚构时区偏移或同步尝试结果。
+        def valid_time?(text)
+          match = /\A(\d{2}:\d{2}:\d{2}) (Sun|Mon|Tue|Wed|Thu|Fri|Sat) ([A-Z][a-z]{2}) (\d{1,2}), (\d{4})\z/.match(text)
+          return false unless match && match[1].split(":").map(&:to_i).zip([ 24, 60, 60 ]).all? { |value, limit| value < limit }
+
+          date = Date.strptime("#{match[3]} #{match[4]} #{match[5]}", "%b %d %Y")
+          Date::ABBR_DAYNAMES[date.wday] == match[2]
+        rescue ArgumentError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ctx_checker/radware_alteon/port_counter_parser.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "../parsers/base"
+
+module CtxChecker
+  module RadwareAlteon
+    # 动态端口查询绑定预期身份，不仅依赖命令回显确认目标。
+    class PortCounterParser < CtxChecker::Parsers::Base
+      # 各发现命令的目标绑定到其解析器类，避免共享可变状态。
+      def self.for_port(number)
+        raise ArgumentError, "Expected port must be a positive integer" unless number.is_a?(Integer) && number.positive?
+
+        Class.new(self) { define_method(:expected_port) { "port#{number}" } }
+      end
+
+      private
+
+      # 未绑定目标的解析器仍可用于已保存回显及独立格式回归。
+      def expected_port = nil
+
+      # 其他端口的响应不能算作请求端口的覆盖证据。
+      def build_port_result(rows, complete:, recognized:, issues:)
+        if expected_port
+          mismatched = rows.reject { |row| row[:interface] == expected_port }
+          if mismatched.any?
+            issues << { code: :counter_port_mismatch, interface: expected_port }
+            rows -= mismatched
+          end
+        end
+        build_result(rows, complete: complete, recognized: recognized, issues: issues, identity: %i[interface metric])
+      end
+    end
+  end
+end

data/lib/ctx_checker/radware_alteon/profile.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "ctx_parser/profile"
+require_relative "../observation"
+require_relative "parsers/info_link"
+require_relative "parsers/info_l3_ip"
+require_relative "parsers/info_transceiver"
+require_relative "parsers/info_l2_trunk"
+require_relative "parsers/info_l2_lacp_dump"
+require_relative "parsers/stats_port_if"
+require_relative "parsers/stats_port_ether"
+require_relative "parsers/info_l3_bgp_summary"
+require_relative "parsers/info_l3_ospf_nbr"
+require_relative "parsers/stats_mp_cpu"
+require_relative "parsers/stats_mp_mem"
+require_relative "parsers/stats_sp_allutils"
+require_relative "parsers/info_sys_temp"
+require_relative "parsers/info_sys_fan"
+require_relative "parsers/info_sys_ps"
+require_relative "parsers/info_sys_general"
+require_relative "parsers/stats_sys_ntp"
+
+module CtxChecker
+  module RadwareAlteon
+    # Alteon 菜单查询独立于其他 Radware 产品系列。
+    class Profile < CtxParser::Profile
+      MAX_DISCOVERED_PORTS = 256
+      CATALOG = CtxParser::CommandCatalog.new([
+        { dimensions: [ :interfaces ], command: "/info/link", parser: Parsers::InfoLink },
+        { dimensions: [ :interfaces ], command: "/info/l3/ip", parser: Parsers::InfoL3Ip },
+        { dimensions: [ :aggregation ], command: "/info/l2/trunk", parser: Parsers::InfoL2Trunk },
+        { dimensions: [ :aggregation ], command: "/info/l2/lacp/dump", parser: Parsers::InfoL2LacpDump },
+        { dimensions: [ :bgp ], command: "/info/l3/bgp/summary", parser: Parsers::InfoL3BgpSummary },
+        { dimensions: [ :ospf ], command: "/info/l3/ospf/nbr", parser: Parsers::InfoL3OspfNbr },
+        { dimensions: [ :cpu ], command: "/stats/mp/cpu", parser: Parsers::StatsMpCpu },
+        { dimensions: [ :memory ], command: "/stats/mp/mem", parser: Parsers::StatsMpMem },
+        { dimensions: %i[cpu memory], command: "/stats/sp 1/allutils", parser: Parsers::StatsSpAllutils },
+        { dimensions: [ :temperature ], command: "/info/sys/temp", parser: Parsers::InfoSysTemp },
+        { dimensions: [ :environment ], command: "/info/sys/fan", parser: Parsers::InfoSysFan },
+        { dimensions: [ :power ], command: "/info/sys/ps", parser: Parsers::InfoSysPs },
+        { dimensions: [ :clock ], command: "/info/sys/general", parser: Parsers::InfoSysGeneral },
+        { dimensions: %i[ntp device_counters], command: "/stats/sys/ntp", parser: Parsers::StatsSysNtp }
+      ], multi_command: true)
+      COMMANDS = CATALOG.commands
+      PARSERS = CATALOG.parsers
+
+      # 打开连接器前，拒绝已知不兼容的产品系列。
+      def initialize(model: nil)
+        super
+        raise ArgumentError, "DefensePro requires a separate checker profile" if /defen[cs]e[\s_-]*pro/i.match?(model.to_s)
+
+        @catalog = CATALOG
+      end
+
+      # 扩展后的实例保留不可变命令与实现索引。
+      def commands = @catalog.commands
+
+      # 绑定端口的解析器复用基础型号覆盖及命令选择契约。
+      def parsers = @catalog.parsers
+
+      # 已知光模块命令缺陷根据固件事实判断，不依据型号名称猜测。
+      def with_software_version(value)
+        raise ArgumentError, "Software version must be text" unless value.nil? || value.is_a?(String)
+
+        entries = @catalog.entries.reject { |entry| entry[:dimensions].include?(:optics) }
+        if transceiver_fixed?(value)
+          entries += [ { dimensions: [ :optics ], command: "/info/transceiver", parser: Parsers::InfoTransceiver } ]
+        end
+        expanded = dup
+        expanded.instance_variable_set(:@catalog, CtxParser::CommandCatalog.new(entries, multi_command: true))
+        expanded
+      end
+
+      # Alteon 不提供全端口叶级查询，计数器采集必须依赖完整端口清单。
+      def discovery_dimensions(requested)
+        requested.include?(:counters) ? [ :interfaces ] : []
+      end
+
+      # 仅为经过校验的清单端口生成查询；发现不完整时不猜测端口。
+      def expand(observations, dimensions:)
+        return self unless dimensions.include?(:counters) && !commands.key?(:counters)
+
+        interfaces = observations[:interfaces]
+        return self unless physical_source_complete?(interfaces)
+
+        ports = discovered_ports(interfaces)
+        return self if ports.empty?
+
+        additions = ports.flat_map do |port|
+          [ { dimensions: [ :counters ], command: "/stats/port #{port}/if", parser: Parsers::StatsPortIf.for_port(port) },
+            { dimensions: [ :counters ], command: "/stats/port #{port}/ether", parser: Parsers::StatsPortEther.for_port(port) } ]
+        end
+        expanded = dup
+        expanded.instance_variable_set(:@catalog, CtxParser::CommandCatalog.new(@catalog.entries + additions, multi_command: true))
+        expanded
+      end
+
+      # 每个发现端口均需标准计数器和以太网错误计数器证据。
+      def counter_metrics = %i[in_errors out_errors in_discards out_discards crc_errors out_carrier_errors].freeze
+
+      private
+
+      # 官方修复版本为 30.5.9.0、31.0.6.0、32.1.0.0；其他版本分支保持不可用。
+      def transceiver_fixed?(value)
+        return false unless /\A(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\z/.match?(value.to_s)
+
+        major, minor, patch, build = value.split(".").map { |part| Integer(part, 10) }
+        case [ major, minor ]
+        when [ 30, 5 ] then ([ patch, build ] <=> [ 9, 0 ]) >= 0
+        when [ 31, 0 ] then ([ patch, build ] <=> [ 6, 0 ]) >= 0
+        else major == 32 && minor >= 1
+        end
+      end
+
+      # 逻辑接口证据失败不能使完整物理接口清单失效。
+      def physical_source_complete?(interfaces)
+        return false unless interfaces.is_a?(Observation) && interfaces.name == :interfaces && %i[complete partial].include?(interfaces.status)
+
+        sources = interfaces.evidence.select { |entry| entry[:command] == "/info/link" }
+        sources.one? && sources.first[:status] == :complete && interfaces.records.all? do |row|
+          !row[:name].start_with?("port") || row[:source_complete] == true
+        end
+      end
+
+      # 限制动态查询范围，不将数字后缀视为任意 CLI 文本。
+      def discovered_ports(interfaces)
+        ports = interfaces.records.filter_map do |row|
+          next unless row[:kind] == :physical
+          name = row[:name]
+          next unless name.start_with?("port")
+
+          match = /\Aport([1-9]\d*)\z/.match(name)
+          port = Integer(match[1], 10) if match
+          unless port && port <= MAX_DISCOVERED_PORTS
+            raise ArgumentError, "Invalid discovered Alteon port identity"
+          end
+          port
+        end.uniq.sort
+        raise ArgumentError, "Alteon port discovery exceeds the query limit" if ports.size > MAX_DISCOVERED_PORTS
+
+        ports
+      end
+    end
+  end
+end

data/lib/ctx_checker/radware_alteon.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CtxChecker
+  # 打开厂商命名空间时，不从子解析器提前加载平台策略。
+  module RadwareAlteon
+    autoload(:Profile, File.expand_path("radware_alteon/profile", __dir__)) unless const_defined?(:Profile, false)
+  end
+end

data/lib/ctx_checker/report.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "snapshot"
+require_relative "finding"
+require "json"
+
+module CtxChecker
+  # 提供紧凑、可序列化的结果，独立保留采集覆盖率与故障信息。
+  class Report
+    attr_reader :snapshot, :findings, :counts, :commands
+
+    # 冻结报告证据与检查结果，便于复现评估。
+    def initialize(snapshot:, findings:)
+      raise ArgumentError, "Report requires a snapshot" unless snapshot.is_a?(Snapshot)
+      raise ArgumentError, "Report requires findings" unless findings.is_a?(Array) && findings.all?(Finding)
+      @snapshot, @findings = snapshot, findings.dup.freeze
+      @counts = %i[pass fail unknown not_applicable].to_h { |state| [ state, findings.count { |row| row.status == state } ] }.freeze
+      @commands = CtxParser::Immutable.copy(command_results)
+      freeze
+    end
+
+    # 判断所有已选事实是否都有完整证据支持。
+    def complete? = counts[:unknown].zero? && snapshot.issues.empty? && snapshot.observations.values.all? { |row| %i[complete not_requested not_applicable].include?(row.status) }
+    # 仅在覆盖充分且无失败检查时声明健康。
+    def healthy? = complete? && counts[:pass].positive? && counts[:fail].zero?
+    # 推导汇总状态，避免将证据缺失当作成功。
+    def status = counts[:fail].positive? ? :fail : healthy? ? :pass : :unknown
+
+    # 独立衡量已评估证据的覆盖情况，不与设备是否通过混淆。
+    def coverage
+      applicable = counts[:pass] + counts[:fail] + counts[:unknown]
+      applicable.zero? ? 0.0 : ((counts[:pass] + counts[:fail]) * 100.0 / applicable).round(2)
+    end
+
+    # 返回公开的数据结构，并保留状态与诊断信息。
+    def to_h = { status: status, complete: complete?, healthy: healthy?, coverage: coverage, counts: counts, commands: commands, snapshot: snapshot.to_h, findings: findings.map(&:to_h) }
+
+    # 持久化摘要避免展开全部观测和测量值。
+    def summary
+      { status: status, complete: complete?, healthy: healthy?, coverage: coverage, counts: counts,
+        target: snapshot.target, observed_at: snapshot.observed_at.iso8601(6), commands: commands,
+        observations: snapshot.observations.transform_values do |row|
+          details = { status: row.status, records: row.records.size, issues: row.issues }
+          row.covered_scopes.empty? ? details : details.merge(covered_scopes: row.covered_scopes)
+        end,
+        issues: snapshot.issues, findings: findings.map { |row| row.to_h.reject { |key, _| %i[actual expected].include?(key) } } }
+    end
+
+    # 生成易读报告，区分已知故障与证据缺失。
+    def to_text
+      [ "Health: #{status} | coverage: #{coverage}% | pass=#{counts[:pass]} fail=#{counts[:fail]} unknown=#{counts[:unknown]} not_applicable=#{counts[:not_applicable]}",
+        *commands.reject { |entry| entry[:status] == :complete }.map { |entry| command_text(entry) },
+        *findings.map do |row|
+          details = [ "#{row.status.to_s.ljust(14)} #{display(row.id)} #{display(row.entity)} (#{row.reason})" ]
+          details << "actual=#{display(row.actual)}" unless row.actual.nil?
+          details << "expected=#{display(row.expected)}" unless row.expected.nil?
+          details.join(" | ")
+        end ].join("\n")
+    end
+
+    private
+
+    # 分别保留命令覆盖率、归并维度的健康与完整性。
+    def command_results
+      grouped = {}
+      snapshot.observations.each_value do |observation|
+        sources = observation.evidence.filter_map { |entry| entry[:command] }.uniq
+        observation.evidence.each do |evidence|
+          command = evidence[:command]
+          next unless command
+
+          issues = observation.issues.select { |issue| issue[:command] == command || !issue[:command] && sources.one? }
+          state = issues.any? { |issue| issue[:skipped] } ? :skipped : evidence.fetch(:status, observation.status)
+          entry = grouped[command] ||= { command: command, dimensions: {}, issues: [] }
+          entry[:dimensions][observation.name] = command_status([ entry[:dimensions][observation.name], state ].compact)
+          entry[:issues].concat(issues.map { |issue| issue.merge(dimension: observation.name) })
+        end
+      end
+      grouped.each_value do |entry|
+        entry[:status] = command_status(entry[:dimensions].values)
+        entry[:issues].uniq!
+      end
+      grouped.values
+    end
+
+    # 共享查询可以同时产生一个有效视图和一个不可用视图。
+    def command_status(states)
+      unique = states.uniq
+      return unique.first if unique.one?
+      return :partial if unique.any? { |state| %i[complete partial].include?(state) }
+
+      :failed
+    end
+
+    # 展示安全失败代码，不包含异常消息或原始响应。
+    def command_text(entry)
+      dimensions = entry[:dimensions].map { |name, state| "#{name}:#{state}" }.join(",")
+      diagnostics = entry[:issues].map do |issue|
+        code = [ issue[:stage], issue[:code] ].compact.join(":")
+        issue[:error_type] ? "#{code} (#{issue[:error_type]})" : code
+      end.uniq
+      [ "Command: #{entry[:status]}", display(entry[:command]), "dimensions=#{dimensions}", *diagnostics.map { |value| display(value) } ].join(" | ")
+    end
+
+    # 结构化测量保持可读，同时限制报告单元格的换行与长度。
+    def display(value)
+      text = value.is_a?(String) ? value : JSON.generate(value)
+      text = text.gsub(/[\x00-\x1f\x7f]/) { |character| format("\\u%04x", character.ord) }
+      text.length > 512 ? "#{text[0, 509]}..." : text
+    end
+  end
+end

data/lib/ctx_checker/runtime_parser.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "parser_registry"
+require_relative "observation"
+require_relative "observation_merger"
+require_relative "parsers/base"
+require_relative "failure"
+
+module CtxChecker
+  # 离线与实时采集使用同一解析入口，每条命令回显仅解析一次。
+  class RuntimeParser
+    DIMENSIONS = Observation::NAMES
+    MAX_DISCOVERED_QUERIES = 512
+    attr_reader :profile, :platform
+
+    # 按请求的平台和型号选择运行解析行为。
+    def initialize(platform:, model: nil, software_version: nil)
+      @platform = ParserRegistry.canonical(platform)
+      @profile = ParserRegistry.fetch(@platform, model: model, software_version: software_version)
+      @discovery_observations = {}.freeze
+      validate_profile!
+    end
+
+    # 通过所选平台与命令策略解析单个运行维度。
+    def parse(name, text, complete: false, command: nil)
+      parse_many([ name ], text, complete: complete, command: command).fetch(name)
+    end
+
+    # 共享命令仅解析一次，再投影各请求维度。
+    def parse_many(names, text, complete: false, command: nil)
+      self.class.validate_dimensions!(names)
+      raise ArgumentError, "CLI output must be text" unless text.is_a?(String)
+      raise ArgumentError, "Completeness must be boolean" unless [ true, false ].include?(complete)
+
+      unavailable = names - profile.commands.keys
+      if unavailable.any?
+        raise ArgumentError, "One output must belong to one supported command" unless unavailable == names
+
+        return names.to_h { |name| [ name, unavailable_observation(name) ] }
+      end
+      candidates = names.map { |name| profile.commands_for(name) }.reduce(:&)
+      command ||= candidates.first if candidates.one?
+      raise ArgumentError, "Select one declared command or use parse_outputs for multiple sources" unless candidates.include?(command)
+      implementation = profile.parser_for(names.first, command: command)
+      command_counts = names.to_h { |name| [ name, profile.commands_for(name).size ] }
+      evidence = [ { command: command, sha256: Digest::SHA256.hexdigest(text), bytes: text.bytesize } ]
+      source = begin
+        normalized = CtxParser::Input.text(text, encoding: :transcode, newlines: :lf, max_bytes: Parsers::Base::MAX_BYTES)
+        if /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.match?(normalized)
+          raise ArgumentError, "CLI body contains terminal control bytes"
+        end
+        normalized
+      rescue ArgumentError, EncodingError => error
+        return names.to_h do |name|
+          [ name, Failure.observation(name, code: :invalid_output, stage: :parse, command: command, error: error, evidence: evidence) ]
+        end
+      end
+
+      result = begin
+        implementation.parse(source, complete: complete)
+      rescue StandardError => error
+        return names.to_h do |name|
+          [ name, Failure.observation(name, code: :parser_error, stage: :parse, command: command, error: error, evidence: evidence) ]
+        end
+      end
+      names.to_h do |name|
+        [ name, project(name, result, command: command, command_count: command_counts.fetch(name), evidence: evidence) ]
+      end
+    end
+
+    # 离线调用方逐条提供命令正文，并显式声明完整性。
+    def parse_outputs(name, outputs, complete: false)
+      self.class.validate_dimensions!([ name ])
+      raise ArgumentError, "Completeness must be boolean" unless [ true, false ].include?(complete)
+      unless profile.commands.key?(name)
+        raise ArgumentError, "Outputs must map declared commands to their bodies" unless outputs.is_a?(Hash) && outputs.empty?
+        return unavailable_observation(name)
+      end
+      unless outputs.is_a?(Hash) && (outputs.keys - profile.commands_for(name)).empty?
+        raise ArgumentError, "Outputs must map declared commands to their bodies"
+      end
+      combine(name, outputs.map { |command, body| parse(name, body, complete: complete, command: command) })
+    end
+
+    # 实时采集与离线组装遵循相同的来源及指标覆盖契约。
+    def combine(name, observations)
+      metrics = name == :counters && profile.respond_to?(:counter_metrics) ? profile.counter_metrics : []
+      ObservationMerger.call(name, observations, commands: profile.commands_for(name), required_metrics: metrics)
+    end
+
+    # 按命令归组所选维度，避免重复执行共享查询。
+    def queries(names)
+      self.class.validate_dimensions!(names)
+      profile.queries(profile.commands.keys & names)
+    end
+
+    # 可选发现依赖仅来自固定平台命令，不递归生成查询。
+    def discovery_dimensions(names)
+      self.class.validate_dimensions!(names)
+      return [] unless profile.respond_to?(:discovery_dimensions)
+
+      dependencies = profile.discovery_dimensions(names)
+      unless profile.respond_to?(:expand) && dependencies.is_a?(Array) && dependencies.uniq == dependencies &&
+          (dependencies - DIMENSIONS).empty? && (dependencies - profile.commands.keys).empty?
+        raise ArgumentError, "Discovery requires unique fixed dimensions and an expansion method"
+      end
+      dependencies.dup.freeze
+    end
+
+    # 扩展有界不可变查询目录前，由平台策略校验来源证据完整性。
+    def expand(observations, dimensions:)
+      dependencies = discovery_dimensions(dimensions)
+      unless observations.is_a?(Hash) && observations.all? { |name, value| value.is_a?(Observation) && value.name == name }
+        raise ArgumentError, "Discovery requires named observations"
+      end
+      return self if dependencies.empty?
+
+      discovered = observations.slice(*dependencies).freeze
+      expanded = dup
+      expanded.instance_variable_set(:@discovery_observations, discovered)
+      candidate = profile.expand(discovered, dimensions: dimensions)
+      validate_expansion!(candidate, dimensions)
+      expanded.instance_variable_set(:@profile, candidate)
+      expanded.send(:validate_profile!)
+      expanded
+    end
+
+    # 发现不可用时保留实际来源错误及证据，不据此声称硬件不受支持。
+    def unavailable_observation(name, discoveries: @discovery_observations, error: nil, code: nil, stage: :discovery)
+      dependencies = discovery_dimensions([ name ])
+      if dependencies.empty?
+        return Observation.new(name: name, status: :unsupported, issues: [ { code: :unsupported_dimension } ])
+      end
+      sources = discoveries.values_at(*dependencies).compact
+      issue = { code: code || (error ? :discovery_expansion_failed : :discovery_unavailable), stage: stage }
+      if error
+        type = error.class.name
+        issue[:error_type] = type.is_a?(String) && Observation::ERROR_TYPE_PATTERN.match?(type) ? type : "StandardError"
+      end
+      Observation.new(name: name, status: :failed, issues: [ issue, *sources.flat_map(&:issues) ].uniq,
+        evidence: sources.flat_map(&:evidence).uniq)
+    end
+
+    # 拒绝空、重复或不支持的观测选择。
+    def self.validate_dimensions!(names)
+      unless names.is_a?(Array) && names.any? && names.uniq == names && (names - DIMENSIONS).empty?
+        raise ArgumentError, "Dimensions must be a nonempty unique list of supported symbols"
+      end
+    end
+
+    private
+
+    # 发现结果仅可在边界内增加请求维度，不能替换已有命令契约。
+    def validate_expansion!(candidate, dimensions)
+      unless candidate.is_a?(CtxParser::Profile) && candidate.commands.is_a?(Hash)
+        raise ArgumentError, "Discovery must return a parser profile"
+      end
+      added = candidate.commands.keys - profile.commands.keys
+      allowed = dimensions.select { |name| discovery_dimensions([ name ]).any? }
+      raise ArgumentError, "Discovery added an unrelated dimension" unless (added - allowed).empty?
+      profile.commands.each_key do |name|
+        unless candidate.commands.key?(name) && candidate.commands_for(name) == profile.commands_for(name) &&
+            profile.commands_for(name).all? { |command| candidate.parser_for(name, command: command) == profile.parser_for(name, command: command) }
+          raise ArgumentError, "Discovery cannot replace existing commands or parsers"
+        end
+      end
+      original = profile.commands.keys.flat_map { |name| profile.commands_for(name) }.uniq
+      if added.any? { |name| (candidate.commands_for(name) & original).any? }
+        raise ArgumentError, "Discovery cannot reuse an existing command for a new dimension"
+      end
+      expanded = candidate.commands.keys.flat_map { |name| candidate.commands_for(name) }.uniq
+      raise ArgumentError, "Discovery exceeds the command limit" if (expanded - original).size > MAX_DISCOVERED_QUERIES
+    end
+
+    # 目录和型号错误在打开连接器前抛出，不进入运行失败隔离逻辑。
+    def validate_profile!
+      unless profile.commands.is_a?(Hash) && profile.commands.any? && (profile.commands.keys - DIMENSIONS).empty?
+        raise ArgumentError, "Checker profile must declare supported dimensions"
+      end
+      profile.commands.each_key do |name|
+        profile.commands_for(name).each do |command|
+          implementation = profile.parser_for(name, command: command)
+          unless implementation.is_a?(Class) && implementation < CtxParser::Parser
+            raise ArgumentError, "Command parser must inherit from Parser"
+          end
+        end
+      end
+    end
+
+    # 单个投影缺失不能使同一回显的其他视图失效。
+    def project(name, result, command:, command_count:, evidence:)
+      if result.is_a?(CtxParser::ResultSet)
+        begin
+          result = result.fetch(name)
+        rescue StandardError => error
+          code = error.is_a?(KeyError) ? :missing_parser_view : :parser_projection_failed
+          return Failure.observation(name, code: code, stage: :project, command: command, error: error, evidence: evidence)
+        end
+      end
+      build_observation(name, result, command: command, command_count: command_count, evidence: evidence)
+    end
+
+    # 来源状态归属于单个脚本，即使归并维度仅部分完整也独立保留。
+    def build_observation(name, result, command:, command_count:, evidence:)
+      raise ArgumentError, "Command parser must return a Result or ResultSet" unless result.is_a?(CtxParser::Result)
+
+      status, issues = result.status, result.issues.dup
+      # 仅明确的全功能声明可证明不适用；局部空邻居表不能证明。
+      inactive = %i[aggregation bgp ospf].include?(name) && result.status == :partial && result.records.empty? && result.issues.any? &&
+        result.issues.all? { |issue| %i[protocol_disabled aggregation_not_configured].include?(issue[:code]) }
+      inactive ||= name == :aggregation && result.complete? && result.records.empty?
+      if inactive && command_count == 1
+        issues = [ { code: :aggregation_not_configured } ] if issues.empty?
+        return Observation.new(name: name, status: :not_applicable, issues: issues,
+          evidence: evidence.map { |entry| entry.merge(status: :complete) })
+      end
+      issues += [ { code: :incomplete_command_output } ] if status == :partial && issues.empty?
+      if command_count > 1
+        issues += [ { code: :incomplete_command_set, count: command_count - 1 } ]
+        status = :partial if status == :complete
+      end
+      metadata = { source_complete: result.complete? }
+      metadata[:source_command] = command if name == :counters
+      defaults = name == :counters ? { unit: :packets, scope: :interface } : {}
+      records = result.records.map { |record| defaults.merge(record).merge(metadata) }
+      Observation.new(name: name, status: status, records: records, issues: issues,
+        covered_scopes: result.is_a?(Parsers::ScopedResult) ? result.covered_scopes : [],
+        evidence: evidence.map { |entry| entry.merge(status: result.status) })
+    rescue StandardError => error
+      Failure.observation(name, code: :invalid_observation, stage: :validate, command: command, error: error, evidence: evidence)
+    end
+  end
+end

data/lib/ctx_checker/snapshot.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "observation"
+
+module CtxChecker
+  # 快照绑定目标及采样时刻；缺少的维度明确保持未请求。
+  class Snapshot
+    attr_reader :target, :observed_at, :observations, :issues
+
+    # 冻结设备身份、观测结果与采样时间。
+    def initialize(target:, observed_at:, observations:, issues: [])
+      unless target.is_a?(Hash) && (target.keys - %i[host platform model software_version id]).empty? &&
+          %i[host platform].all? { |key| target[key].is_a?(String) && !target[key].strip.empty? } &&
+          target.all? { |key, value| value.nil? || value.is_a?(String) && !/[\x00-\x1f\x7f]/.match?(value) || key == :id && value.is_a?(Integer) && value >= 0 }
+        raise ArgumentError, "Target requires host and platform without connection secrets"
+      end
+      unless observations.is_a?(Hash) && observations.all? { |name, row| Observation::NAMES.include?(name) && row.is_a?(Observation) && row.name == name }
+        raise ArgumentError, "Snapshot observations must match their dimensions"
+      end
+      unless issues.is_a?(Array) && issues.all? { |issue| Observation.valid_issue?(issue) }
+        raise ArgumentError, "Snapshot issues require safe codes"
+      end
+      @observed_at = case observed_at
+      when Time then observed_at.getutc.freeze
+      when String then Time.iso8601(observed_at).getutc.freeze
+      else raise ArgumentError, "Observation time must be Time or ISO8601"
+      end
+      @target = CtxParser::Immutable.copy(target)
+      @issues = CtxParser::Immutable.copy(issues)
+      @observations = Observation::NAMES.to_h { |name| [ name, observations.fetch(name) { Observation.new(name: name, status: :not_requested) } ] }.freeze
+      freeze
+    end
+
+    # 返回请求的观测，不虚构不可用记录。
+    def observation(name) = observations.fetch(name)
+    # 检查两次采样是否指向同一设备与平台。
+    def same_target?(other) = other.is_a?(Snapshot) && %i[host platform id].all? { |key| target[key] == other.target[key] }
+    # 返回公开的数据结构，并保留状态与诊断信息。
+    def to_h = { target: target, observed_at: observed_at.iso8601(6), observations: observations.transform_values(&:to_h), issues: issues }
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class} observations=#{observations.size}>"
+  end
+end