specproof 0.1.0

data/lib/specproof/coverage.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module SpecProof
+  # Tracks whether planned input obligations have been observed at runtime.
+  # It keeps aggregate counters and a small set of invalid-input witnesses,
+  # never an event trace.
+  class Coverage
+    WITNESS_LIMIT = 1
+    REASON_LIMIT = 20
+
+    def initialize(obligations:, specifications:)
+      @specifications = specifications.to_h { |specification| [specification.target, specification] }.freeze
+      @obligations = obligations.dup.freeze
+      @hits = @obligations.to_h { |obligation| [obligation.id, 0] }
+      @spaces = specifications.filter_map do |specification|
+        next unless specification.respond_to?(:combination_group) && specification.combination_group
+
+        space = PartitionSpace.for_specification(specification)
+        [specification.target, space]
+      end.to_h.freeze
+      @outside_counts = Hash.new(0)
+      @outside_witnesses = Hash.new { |hash, target| hash[target] = [] }
+      @outside_combination_counts = Hash.new(0)
+      @outside_combination_evidence = {}
+      @incomplete_reasons = Hash.new { |hash, target| hash[target] = [] }
+      @observed_targets = {}
+      @incomplete_targets = {}
+    end
+
+    # This command mutates coverage; its boolean reports acceptance, not state.
+    def observe(target:, arguments:) # rubocop:disable Naming/PredicateMethod
+      target = target.to_s
+      specification = @specifications[target]
+      return false unless specification
+
+      @observed_targets[target] = true
+      tuple = primitive_tuple(arguments)
+      unless valid_tuple?(specification, tuple)
+        record_outside(target, tuple)
+        return false
+      end
+      space = @spaces[target]
+      if space && !space.allowed?(tuple)
+        record_outside(target, tuple)
+        record_outside_combination(target, tuple, space.sources)
+        return false
+      end
+
+      @obligations.each do |obligation|
+        next unless obligation.target == target
+
+        if obligation.respond_to?(:inputs) && obligation.inputs
+          next unless obligation.inputs.all? do |name, value|
+            actual = tuple.fetch(name)
+            value.is_a?(PartitionLevel) ? value.include?(actual) : actual == value
+          end
+        else
+          next unless tuple.fetch(obligation.input) == obligation.value
+        end
+
+        @hits[obligation.id] += 1
+      end
+      true
+    end
+
+    def mark_incomplete(target:, reason:)
+      target = target.to_s
+      @incomplete_targets[target] = true
+      reasons = @incomplete_reasons[target]
+      value = primitive_string(reason)
+      reasons << value if reasons.length < REASON_LIMIT && !reasons.include?(value)
+      self
+    end
+
+    def missing
+      to_report.fetch(:missing)
+    end
+
+    def exercised
+      to_report.fetch(:exercised)
+    end
+
+    # Returns a compact projection suitable for wrapping in Report.envelope.
+    def to_report
+      projection = base_projection
+      projection.merge!(combination_projection) unless @spaces.empty?
+      projection
+    end
+
+    private
+
+    def base_projection
+      rows = obligation_rows
+      exercised_rows = rows.select { |row| row.fetch(:status) == "exercised" }
+      missing_rows = rows.select { |row| row.fetch(:status) == "not_observed" }
+      unknown_count = rows.count { |row| row.fetch(:status) == "unknown" }
+      not_observed_count = missing_rows.length
+      exercised = exercised_rows.length
+      incomplete_reasons = @incomplete_reasons.values.flatten.uniq
+      complete = @incomplete_targets.none?
+      observed = !@observed_targets.empty?
+      {
+        obligations: rows,
+        missing: missing_rows,
+        exercised: exercised_rows,
+        exercised_count: exercised,
+        obligation_count: rows.length,
+        missing_count: missing_rows.length,
+        unknown_count: unknown_count,
+        not_observed_count: not_observed_count,
+        completion_percent: completion_percent(rows, complete, observed, exercised),
+        status: if observed
+                  (complete ? "complete" : "incomplete")
+                else
+                  "not_observed"
+                end,
+        completeness: complete ? "complete" : "incomplete",
+        outside_domain: outside_domain_report,
+        incomplete_reasons: incomplete_reasons,
+        evidence_mode: "obligation_hits",
+        replay: false
+      }
+    end
+
+    def obligation_rows
+      @obligations.map do |obligation|
+        hits = @hits.fetch(obligation.id)
+        state = obligation_state(hits, obligation.target)
+        Report.obligation(obligation).merge(status: state, hits: hits)
+      end
+    end
+
+    def obligation_state(hits, target)
+      return "exercised" if hits.positive?
+      return "unknown" if @incomplete_targets[target]
+
+      "not_observed"
+    end
+
+    def outside_domain_report
+      @outside_counts.to_h do |target, count|
+        witness = @outside_witnesses.fetch(target).first
+        [target, { count: count, witness: typed_tuple(witness) }]
+      end
+    end
+
+    def combination_projection
+      {
+        outside_combinations: outside_combinations_report,
+        excluded_pairs: excluded_pairs_report
+      }
+    end
+
+    def outside_combinations_report
+      @outside_combination_counts.to_h do |target, count|
+        evidence = @outside_combination_evidence.fetch(target)
+        [target, { count: count, witness: typed_tuple(evidence.fetch(:witness)),
+                   sources: evidence.fetch(:sources).map { |item| Report.source(item) } }]
+      end
+    end
+
+    def excluded_pairs_report
+      @spaces.flat_map do |target, space|
+        space.excluded_pairs.map do |inputs|
+          { target: target, inputs: typed_inputs(inputs), reason: "no_allowed_completion",
+            sources: space.sources.map { |item| Report.source(item) } }
+        end
+      end
+    end
+
+    def completion_percent(rows, complete, observed, exercised)
+      return if rows.empty? || !complete || !observed
+
+      ((exercised * 100.0) / rows.length).round(2)
+    end
+
+    def valid_tuple?(specification, tuple)
+      return false unless tuple
+
+      expected = specification.inputs.keys
+      return false unless tuple.keys.sort_by(&:to_s) == expected.sort_by(&:to_s)
+
+      specification.inputs.all? do |name, input|
+        Domains.include?(input.domain, tuple.fetch(name))
+      end
+    end
+
+    def record_outside_combination(target, tuple, sources)
+      @outside_combination_counts[target] += 1
+      @outside_combination_evidence[target] ||= { witness: tuple, sources: sources.dup.freeze }.freeze
+    end
+
+    def typed_inputs(inputs)
+      inputs.to_h { |name, value| [name.to_s, Report.value(value)] }
+    end
+
+    def primitive_tuple(arguments)
+      return nil unless arguments.is_a?(Hash)
+
+      arguments.each_with_object({}) do |(key, value), normalized|
+        return nil unless key.is_a?(Symbol)
+
+        name = key
+        return nil unless Domains.primitive?(value)
+
+        normalized[name] = Domains.supported_string?(value) ? Domains.canonical_string(value) : value
+      rescue NoMethodError
+        return nil
+      end.freeze
+    end
+
+    def record_outside(target, tuple)
+      @outside_counts[target] += 1
+      witnesses = @outside_witnesses[target]
+      witnesses << tuple if witnesses.length < WITNESS_LIMIT && !witnesses.include?(tuple)
+    end
+
+    def typed_tuple(tuple)
+      return { kind: "invalid_tuple" } unless tuple
+
+      tuple.to_h { |key, value| [key.to_s, Report.value(value)] }
+    end
+
+    def primitive_string(value)
+      text = value.is_a?(String) || value.is_a?(Symbol) ? value.to_s : "incomplete collection"
+      text.encode("UTF-8", invalid: :replace, undef: :replace, replace: "?").byteslice(0, 240).to_s.freeze
+    end
+  end
+end

data/lib/specproof/coverage_report.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+module SpecProof
+  # Supplies stable validation failures to the report reader.
+  module CoverageReportErrors
+    private
+
+    def unsupported!(message) = raise ConfigurationError.new(message, code: "unsupported_coverage_report")
+
+    def incomplete!(message) = raise ConfigurationError.new(message, code: "incomplete_coverage_report")
+
+    def mismatch!(message) = raise ConfigurationError.new(message, code: "coverage_contract_mismatch")
+
+    def invalid!(message) = raise ConfigurationError.new(message, code: "invalid_coverage_report")
+  end
+
+  # Checks and owns the JSON-shaped data preserved by a validated report.
+  module CoverageReportJSON
+    private
+
+    def deep_copy_freeze(value)
+      case value
+      when Hash
+        value.to_h { |key, item| [key.dup.freeze, deep_copy_freeze(item)] }.freeze
+      when Array
+        value.map { |item| deep_copy_freeze(item) }.freeze
+      when String
+        value.dup.freeze
+      else
+        value.freeze
+      end
+    end
+
+    def json_object?(value)
+      value.is_a?(Hash) && value.keys.all?(String) &&
+        value.values.all? { |item| json_value?(item) }
+    end
+
+    def json_value?(value)
+      case value
+      when Hash then value.keys.all?(String) && value.values.all? { |item| json_value?(item) }
+      when Array then value.all? { |item| json_value?(item) }
+      when String, Integer, TrueClass, FalseClass, NilClass then true
+      when Float then value.finite?
+      else false
+      end
+    end
+  end
+
+  # Validates bounded runtime evidence against a freshly planned pairwise contract.
+  class CoverageReport
+    include CoverageReportErrors
+    include CoverageReportJSON
+
+    SCHEMA_VERSION = 1
+    KIND = "coverage"
+    CRITERION = "pairwise-finite-v1"
+    PARTITION_CRITERION = "pairwise-partitions-v1"
+    REQUIRED_SCOPE = {
+      "window" => "minitest_run",
+      "method_identity" => "direct_owner_definition",
+      "input_semantics" => "effective_bound_values",
+      "argument_presence" => "not_observed"
+    }.freeze
+    REQUIRED_FIELDS = %w[
+      schema_version kind errors contract_digest criterion run_id scope evidence_mode replay
+      obligations missing exercised exercised_count obligation_count missing_count unknown_count
+      not_observed_count completion_percent completion integrity tests_passed incomplete_reasons
+    ].freeze
+
+    attr_reader :contract_digest, :missing_ids, :run_id, :tests_passed, :scope, :scope_snapshot, :criterion
+
+    def initialize(report, specifications:, obligations:, criterion: CRITERION)
+      @specifications = specifications
+      @obligations = obligations
+      @criterion = criterion.is_a?(String) ? criterion.dup.freeze : criterion
+      validate_document!(report)
+      @contract_digest, @run_id = report.values_at("contract_digest", "run_id").map { |value| value.dup.freeze }
+      @scope = @scope_snapshot = deep_copy_freeze(report.fetch("scope"))
+      @tests_passed = report.fetch("tests_passed")
+      @missing_ids = report.fetch("missing").map { |row| row.fetch("id").dup.freeze }.freeze
+      freeze
+    end
+
+    private
+
+    def validate_document!(report)
+      invalid!("coverage report must be a JSON object") unless report.is_a?(Hash) && report.keys.all?(String)
+      missing_fields = REQUIRED_FIELDS - report.keys
+      invalid!("coverage report is missing required fields: #{missing_fields.join(", ")}") unless missing_fields.empty?
+      validate_identity!(report)
+      validate_completion!(report)
+      validate_rows!(report)
+      validate_projections!(report)
+      validate_counts!(report)
+      validate_completion_percent!(report)
+      validate_scope!(report.fetch("scope"))
+    end
+
+    def validate_identity!(report)
+      unless report["schema_version"].is_a?(Integer) && report["schema_version"] == SCHEMA_VERSION &&
+             report["kind"] == KIND && [CRITERION, PARTITION_CRITERION].include?(criterion) &&
+             report["criterion"] == criterion
+        unsupported!("coverage report schema, kind, or criterion is unsupported")
+      end
+      unless report["run_id"].is_a?(String) && !report["run_id"].empty?
+        invalid!("coverage report run_id must be a non-empty string")
+      end
+      return if report["contract_digest"] == Report.digest(@specifications)
+
+      mismatch!("coverage report contract digest does not match specifications")
+    end
+
+    def validate_completion!(report)
+      invalid!("coverage report completion must be a string") unless report["completion"].is_a?(String)
+      incomplete!("coverage report is not complete") unless report["completion"] == "completed"
+      invalid!("coverage report integrity must be boolean") unless [true, false].include?(report["integrity"])
+      incomplete!("coverage report integrity is false") unless report["integrity"]
+      invalid!("coverage report errors must be an array") unless report["errors"].is_a?(Array)
+      incomplete!("coverage report contains errors") unless report["errors"].empty?
+      invalid!("coverage report incomplete_reasons must be an array of strings") unless
+        report["incomplete_reasons"].is_a?(Array) && report["incomplete_reasons"].all?(String)
+      incomplete!("coverage report contains incomplete reasons") unless report["incomplete_reasons"].empty?
+      invalid!("coverage report evidence_mode must be a string") unless report["evidence_mode"].is_a?(String)
+      invalid!("coverage report replay must be boolean") unless [true, false].include?(report["replay"])
+      unless report["evidence_mode"] == "obligation_hits" && report["replay"] == false
+        incomplete!("coverage report does not contain direct obligation-hit evidence")
+      end
+      unless report["tests_passed"].equal?(true) || report["tests_passed"].equal?(false)
+        invalid!("coverage report tests_passed must be boolean")
+      end
+      invalid!("coverage report unknown_count must be an integer") unless report["unknown_count"].is_a?(Integer)
+      return if report["unknown_count"].zero?
+
+      incomplete!("coverage report contains unknown obligations")
+    end
+
+    def validate_scope!(scope)
+      invalid!("coverage report scope must be a JSON object") unless json_object?(scope)
+      REQUIRED_SCOPE.each do |key, value|
+        mismatch!("coverage report scope #{key} does not match the adapter") unless scope[key] == value
+      end
+      unless scope.key?("arguments") && scope["arguments"].is_a?(Array) && scope["arguments"].all?(String) &&
+             scope.key?("filter") && [String, NilClass].include?(scope["filter"].class) &&
+             scope.key?("exclude") && [String, NilClass].include?(scope["exclude"].class)
+        invalid!("coverage report scope arguments, filter, or exclude has an invalid type")
+      end
+      expected_targets = @specifications.map(&:target).sort
+      unless scope["targets"].is_a?(Array) && scope["targets"].all?(String)
+        invalid!("coverage report scope targets must be strings")
+      end
+      mismatch!("coverage report targets do not match specifications") unless scope["targets"].sort == expected_targets
+      expected_scope = Report.input_scope(@specifications)
+      actual_scope = scope["input_scope"]
+      invalid!("coverage report input_scope must be an array") unless actual_scope.is_a?(Array)
+      unless scope_projection(actual_scope) == scope_projection(expected_scope[:input_scope])
+        mismatch!("coverage report analyzed input scope does not match specifications")
+      end
+      unless scope["completeness_scope"] == "analyzed_inputs"
+        mismatch!("coverage report completeness scope does not match specifications")
+      end
+    rescue NoMethodError, ArgumentError, TypeError
+      mismatch!("coverage report scope does not match specifications")
+    end
+
+    def validate_rows!(report)
+      rows = report["obligations"]
+      invalid!("coverage report obligations must be an array") unless rows.is_a?(Array)
+      mismatch!("coverage report obligation denominator does not match plan") unless rows.length == @obligations.length
+
+      expected = @obligations.to_h { |obligation| [obligation.id, obligation] }
+      mismatch!("planned obligation IDs are not unique") unless expected.length == @obligations.length
+      seen = {}
+      rows.each do |row|
+        invalid!("coverage obligation row must be an object") unless row.is_a?(Hash) && row.keys.all?(String)
+        id = row["id"]
+        invalid!("coverage obligation ID must be a string") unless id.is_a?(String) && !id.empty?
+        invalid!("coverage obligation rows contain duplicate IDs") if seen[id]
+        obligation = expected[id]
+        mismatch!("coverage obligation IDs do not match plan") unless obligation
+        validate_row!(row, obligation)
+        seen[id] = true
+      end
+      mismatch!("coverage obligation IDs do not match plan") unless seen.length == expected.length
+    end
+
+    def validate_row!(row, obligation)
+      invalid!("coverage obligation hits must be an integer") unless row["hits"].is_a?(Integer)
+      invalid!("coverage obligation target must be a string") unless row["target"].is_a?(String)
+      unless row["inputs"].is_a?(Hash) && row["inputs"].keys.all?(String)
+        invalid!("coverage obligation inputs must be an object")
+      end
+      row["inputs"].each_value do |typed|
+        invalid!("coverage obligation input value is malformed") unless valid_typed_value?(typed)
+      end
+      unless row["status"].is_a?(String) && %w[exercised not_observed unknown].include?(row["status"])
+        invalid!("coverage obligation status is invalid")
+      end
+      incomplete!("coverage report contains unknown obligations") if row["status"] == "unknown"
+      unless row["target"].eql?(obligation.target) && row["inputs"].eql?(typed_inputs(obligation.inputs))
+        mismatch!("coverage obligation contents do not match plan")
+      end
+      valid_hits = (row["status"] == "exercised" && row["hits"].positive?) ||
+                   (row["status"] == "not_observed" && row["hits"].zero?)
+      invalid!("coverage obligation status and hits disagree") unless valid_hits
+    end
+
+    def validate_projections!(report)
+      rows = report.fetch("obligations")
+      { "missing" => "not_observed", "exercised" => "exercised" }.each do |field, status|
+        projection = report[field]
+        invalid!("coverage report #{field} projection must be an array") unless projection.is_a?(Array)
+        expected = rows.select { |row| row.fetch("status") == status }
+        unless projection.length == expected.length
+          invalid!("coverage report #{field} projection has an invalid row count")
+        end
+        projection.each { |item| validate_projection_row!(item, field) }
+        invalid!("coverage report #{field} projection disagrees with obligations") unless
+          projection_signature(projection).eql?(projection_signature(expected))
+      end
+    end
+
+    def validate_projection_row!(row, field)
+      invalid!("coverage report #{field} projection contains a malformed row") unless projection_row?(row)
+    end
+
+    def projection_row?(row)
+      return false unless row.is_a?(Hash) && row.keys.all?(String)
+
+      %w[id target status].all? { |key| row[key].is_a?(String) } &&
+        row["inputs"].is_a?(Hash) && row["inputs"].keys.all?(String) &&
+        row["inputs"].values.all? { |typed| valid_typed_value?(typed) } && row["hits"].is_a?(Integer)
+    end
+
+    def valid_typed_value?(typed)
+      return false unless typed.is_a?(Hash) && typed.keys.all?(String) && typed["kind"].is_a?(String)
+
+      case typed["kind"]
+      when "nil" then typed.keys.sort == %w[kind value] && typed["value"].nil?
+      when "boolean" then typed.keys.sort == %w[kind value] && [true, false].include?(typed["value"])
+      when "integer", "symbol", "string"
+        typed.keys.sort == %w[kind value] && typed["value"].is_a?(String)
+      when "partition"
+        typed.keys.sort == %w[kind lower name upper] && typed["name"].is_a?(String) &&
+          canonical_integer_string?(typed["lower"]) && canonical_integer_string?(typed["upper"]) &&
+          Integer(typed["lower"], 10) <= Integer(typed["upper"], 10)
+      else false
+      end
+    rescue ArgumentError
+      false
+    end
+
+    def canonical_integer_string?(value)
+      value.is_a?(String) && value.match?(/\A-?(?:0|[1-9]\d*)\z/) && Integer(value, 10).to_s == value
+    end
+
+    def validate_counts!(report)
+      values = %w[exercised_count obligation_count missing_count unknown_count not_observed_count]
+      invalid!("coverage report counts must be integers") unless values.all? { |key| report[key].is_a?(Integer) }
+      exercised = report.fetch("obligations").count { |row| row.fetch("status") == "exercised" }
+      missing = report.fetch("obligations").count { |row| row.fetch("status") == "not_observed" }
+      expected = { "exercised_count" => exercised, "obligation_count" => @obligations.length,
+                   "missing_count" => missing, "unknown_count" => 0, "not_observed_count" => missing }
+      invalid!("coverage report counters disagree with obligation rows") unless values.to_h do |key|
+        [key, report[key]]
+      end == expected
+    end
+
+    def validate_completion_percent!(report)
+      value = report["completion_percent"]
+      return if value.nil? && report["exercised_count"].zero?
+
+      invalid!("coverage report cannot give a percentage for an empty denominator") if report["obligation_count"].zero?
+      unless value.is_a?(Numeric) && !value.is_a?(Complex)
+        invalid!("coverage report completion_percent must be numeric or null")
+      end
+
+      expected = ((report.fetch("exercised_count") * 100.0) / report.fetch("obligation_count")).round(2)
+      invalid!("coverage report completion_percent disagrees with counters") unless value == expected
+    end
+
+    def scope_projection(scope)
+      return nil unless scope.is_a?(Array)
+
+      entries = scope.map { |item| scope_entry_projection(item) }
+      entries.sort
+    rescue ArgumentError, TypeError
+      invalid!("coverage report input scope is malformed")
+    end
+
+    def scope_entry_projection(item)
+      invalid!("coverage report input scope is malformed") unless item.is_a?(Hash)
+
+      target = item["target"] || item[:target]
+      names = item["analyzed_inputs"] || item[:analyzed_inputs]
+      excluded = item["excluded_inputs"] || item[:excluded_inputs]
+      group = item["combination_group"] || item[:combination_group]
+      unless target.is_a?(String) && names.is_a?(Array) && names.all?(String) && excluded.is_a?(Array)
+        invalid!("coverage report input scope is malformed")
+      end
+      exclusion_names = excluded.map { |entry| exclusion_name(entry) }
+      group_inputs = group && group_inputs_for_scope(group)
+      [target, names.sort, exclusion_names.sort, group_inputs&.sort]
+    end
+
+    def exclusion_name(entry)
+      name = entry.is_a?(Hash) ? entry["name"] || entry[:name] : nil
+      invalid!("coverage report excluded input scope is malformed") unless name.is_a?(String)
+
+      name
+    end
+
+    def group_inputs_for_scope(group)
+      inputs = group.is_a?(Hash) ? group["inputs"] || group[:inputs] : nil
+      invalid!("coverage report combination group is malformed") unless inputs.is_a?(Array) && inputs.all?(String)
+
+      inputs
+    end
+
+    def projection_signature(rows)
+      signatures = rows.map do |row|
+        [row["id"], row["target"], row["inputs"], row["status"], row["hits"]]
+      end
+      signatures.sort_by { |id,| id.to_s }
+    end
+
+    def typed_inputs(inputs)
+      inputs.to_h do |name, value|
+        typed = Report.value(value)
+        [name.to_s, typed.to_h { |key, item| [key.to_s, item] }]
+      end
+    end
+  end
+end

data/lib/specproof/domains.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module SpecProof
+  # Normalizes and compares supported input domains.
+  module Domains
+    module_function
+
+    STRING_INSTANCE_OF = Object.instance_method(:instance_of?)
+    STRING_ENCODING = String.instance_method(:encoding)
+    STRING_VALID_ENCODING = String.instance_method(:valid_encoding?)
+
+    def supported_string?(value)
+      return false unless STRING_INSTANCE_OF.bind_call(value, String)
+
+      encoding = STRING_ENCODING.bind_call(value)
+      [Encoding::UTF_8, Encoding::US_ASCII].include?(encoding) && STRING_VALID_ENCODING.bind_call(value)
+    rescue TypeError
+      false
+    end
+
+    def canonical_string(value)
+      raise ArgumentError, "unsupported string value" unless supported_string?(value)
+
+      copy = String.new(value)
+      (copy.encoding == Encoding::US_ASCII ? copy.encode(Encoding::UTF_8) : copy).freeze
+    end
+
+    def from_range(range, source: nil)
+      unless range.is_a?(Range) && range.begin.is_a?(Integer) && range.end.is_a?(Integer)
+        raise ConfigurationError.new("range endpoints must be bounded integers", code: "invalid_range", source: source)
+      end
+
+      upper = range.exclude_end? ? range.end - 1 : range.end
+      IntegerDomain.new(lower: range.begin, upper: upper)
+    end
+
+    def from_values(values, source: nil)
+      unless values.is_a?(Array)
+        raise ConfigurationError.new("values must be an array", code: "invalid_values", source: source)
+      end
+
+      normalized = values.map do |value|
+        case value
+        when NilClass, TrueClass, FalseClass, Integer then value
+        when Symbol then value.to_s.freeze.to_sym
+        when String
+          unless supported_string?(value)
+            raise ConfigurationError.new("finite string values must be valid UTF-8 or US-ASCII strings",
+                                         code: "unsupported_value", source: source)
+          end
+
+          canonical_string(value)
+        else
+          raise ConfigurationError.new("finite values must be integers, symbols, strings, booleans, or nil",
+                                       code: "unsupported_value", source: source)
+        end
+      end
+      normalized.uniq!
+      FiniteDomain.new(values: normalized.sort_by { |value| sort_key(value) })
+    end
+
+    def sort_key(value)
+      case value
+      when NilClass then [0]
+      when FalseClass then [1, 0]
+      when TrueClass then [1, 1]
+      when Integer then [2, value]
+      when Symbol then [3, value.to_s]
+      when String then [4, value]
+      end
+    end
+
+    def include?(domain, value)
+      case domain
+      when IntegerDomain then value.is_a?(Integer) && value.between?(domain.lower, domain.upper)
+      when FiniteDomain
+        return false unless primitive?(value)
+
+        value = canonical_string(value) if supported_string?(value)
+        domain.values.any? { |member| member.instance_of?(value.class) && member.eql?(value) }
+      else false
+      end
+    end
+
+    def primitive?(value)
+      case value
+      when NilClass, TrueClass, FalseClass, Integer, Symbol then true
+      when String then supported_string?(value)
+      else false
+      end
+    end
+
+    def empty?(domain)
+      domain.is_a?(IntegerDomain) ? domain.lower > domain.upper : domain.values.empty?
+    end
+
+    def same_kind?(left, right)
+      (left.is_a?(IntegerDomain) && right.is_a?(IntegerDomain)) ||
+        (left.is_a?(FiniteDomain) && right.is_a?(FiniteDomain))
+    end
+
+    def to_a(domain)
+      domain.is_a?(IntegerDomain) ? [domain.lower, domain.upper] : domain.values
+    end
+  end
+
+  # Represents an inclusive integer interval, including an empty interval.
+  class IntegerDomain
+    def self.from_range(range)
+      Domains.from_range(range)
+    end
+
+    def include?(value)
+      value.is_a?(Integer) && value.between?(lower, upper)
+    end
+  end
+
+  # Represents a finite set of supported scalar values.
+  class FiniteDomain
+    def include?(value)
+      Domains.include?(self, value)
+    end
+  end
+end