active_sanction 1.0.0

data/lib/active_sanction/rescreen.rb

@@ -0,0 +1,332 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "time"
+require "active_sanction/diff"
+require "active_sanction/error"
+require "active_sanction/index"
+require "active_sanction/match_result"
+require "active_sanction/scorer"
+require "active_sanction/subject"
+require "active_sanction/rescreen/alert"
+
+module ActiveSanction
+  # Who a list change affects. Screening answers about a name; this answers
+  # about a book of business.
+  #
+  #   book = [
+  #     ActiveSanction::Subject.new(id: "cust_1", name: "Bosco Ntaganda", date_of_birth: "1973"),
+  #     ActiveSanction::Subject.new(id: "cust_2", name: "Jane Miller")
+  #   ]
+  #
+  #   diff   = ActiveSanction.diff(:ofac_sdn, from: yesterdays_snapshot)
+  #   alerts = ActiveSanction.rescreen(book, diff: diff, threshold: 75)
+  #
+  #   alerts.first.subject_id      # => "cust_1"
+  #   alerts.first.change          # => :newly_listed
+  #   alerts.first.result          # => a full MatchResult, with its explanation
+  #   alerts.first.previous_score  # => nil, or what it scored before
+  #
+  # ### Why this is the primitive rather than a nightly full screen
+  #
+  # Screening a customer once is a checkbox. The obligation is ongoing:
+  # somebody cleared last month may be listed today, and a delisting matters
+  # just as much, because it is the entry that lets a customer back through
+  # the door. That is recurring work, and the naive way to do it -- every
+  # subject against every record, every night -- costs the whole book times
+  # the whole corpus and stops being nightly somewhere around a few thousand
+  # customers.
+  #
+  # A rescreen costs the whole book times *the handful of records that moved*.
+  # Diff (#35) computes what changed in the list; this computes who that
+  # change affects, and it is the step that turns a diff into an alert. On a
+  # typical day an OFAC diff is a few dozen records, so the index built here
+  # is a few dozen names rather than 46,000 -- see the numbers in the README.
+  #
+  # ### It is built once and then only read
+  #
+  # A Rescreen holds an index over the records the diff names, both versions
+  # of each amended one, the weights it scores with and the threshold it
+  # defaults to. All of it is fixed at construction and the object is frozen,
+  # so a large book is streamed past one of these, in batches, from as many
+  # threads as a host has:
+  #
+  #   rescreening = ActiveSanction::Rescreen.new(diff: diff, threshold: 75)
+  #   customers.find_each(batch_size: 1_000) do |batch|
+  #     rescreening.call(batch) { |alert| AlertRecord.create!(alert.to_h) }
+  #   end
+  #
+  # Nothing about a book is held: subjects are read one at a time and only
+  # alerts are kept, so memory is a function of how much moved rather than of
+  # how many customers there are. The block is what makes even that bounded --
+  # it is called with each alert as it is raised, and a host that writes them
+  # out as they arrive never accumulates the array at all.
+  #
+  # ### It does not touch the matcher
+  #
+  # A rescreen builds its own index, over the diff, and never reads the store
+  # or the client's matcher. That is the point: applying a diff to a book must
+  # not cost an index build over the whole corpus, and a host that has never
+  # screened anything in this process can rescreen without paying for one.
+  #
+  # ### An empty diff does no work at all
+  #
+  # A sync that changed nothing, or a first sync -- which is a baseline rather
+  # than a list of 19,015 additions, see Diff -- yields no alerts and scores
+  # nothing. Not one subject is folded. A host that syncs hourly and
+  # rescreens after each sync is paying for the hours that moved, which is
+  # what makes rescreening after every sync affordable.
+  #
+  # ### What it does not do
+  #
+  # It reports the changes; it does not remember them. There is no alert
+  # store, no deduplication against what was raised yesterday, and no
+  # disposition -- see the note on case management in the README. Two runs
+  # over the same diff produce the same alerts, which is the property that
+  # makes them re-derivable and the reason a host, not this library, owns the
+  # queue they go into.
+  #
+  # It also cannot find what was already there. A subject who matched a record
+  # that did not change is not in a diff at all, and no rescreen will report
+  # them: the first screening run against a book is a deliberate full screen
+  # (`Client#screen_all`), and this is what keeps it current afterwards.
+  class Rescreen
+    extend T::Sig
+
+    # The diff being applied, which is what the alerts are about.
+    sig { returns(Diff) }
+    attr_reader :diff
+
+    # The lowest score worth an alert, for a subject that does not name its
+    # own. Read once, at construction, so a configuration changed mid-run
+    # cannot produce a book screened half one way.
+    sig { returns(Float) }
+    attr_reader :threshold
+
+    # What each signal was worth for this run, and what every result it
+    # produces records.
+    sig { returns(Scorer::Weights) }
+    attr_reader :weights
+
+    # How many names the index hands the scorer per subject. It does not bind
+    # on a typical diff -- a few dozen records cannot exceed it -- and is here
+    # for the day a publisher reissues a whole list under new ids.
+    sig { returns(Integer) }
+    attr_reader :candidate_limit
+
+    sig { returns(Symbol) }
+    attr_reader :backend
+
+    # Sugar, and what ActiveSanction.rescreen calls:
+    #
+    #   ActiveSanction::Rescreen.call(book, diff: diff, threshold: 75)
+    #
+    # Builds a Rescreen and applies it once. A host streaming a book in
+    # batches builds one with .new and calls it per batch instead, so the
+    # index is built once rather than per batch.
+    sig do
+      params(subjects: T.untyped, diff: T.untyped, options: T.untyped,
+             block: T.nilable(T.proc.params(alert: Alert).void)).returns(T::Array[Alert])
+    end
+    def self.call(subjects, diff:, **options, &block)
+      T.unsafe(self).new(diff: diff, **options).call(subjects, &block)
+    end
+
+    sig do
+      params(diff: T.untyped, threshold: T.untyped, weights: T.untyped, candidate_limit: T.untyped,
+             backend: T.untyped).void
+    end
+    def initialize(diff:, threshold: nil, weights: nil, candidate_limit: nil,
+                   backend: MatchResult::DEFAULT_BACKEND)
+      @diff = T.let(diff!(diff), Diff)
+      @threshold = T.let(threshold!(threshold), Float)
+      @weights = T.let(Scorer::Weights.build(weights), Scorer::Weights)
+      @candidate_limit = T.let(candidate_limit!(candidate_limit), Integer)
+      @backend = T.let(backend.to_s.to_sym, Symbol)
+      @versions = T.let(versions, T::Hash[String, T::Array[T.untyped]])
+      @fields = T.let(amended, T::Hash[String, T::Array[Symbol]])
+      # Both versions of an amended record are indexed, because a subject may
+      # have matched only the alias that was taken away.
+      @index = T.let(Index.build(@versions.values.flatten.compact), Index)
+      freeze
+    end
+
+    # The alerts this diff raises against this book, highest score first
+    # within each subject and in the order the subjects arrived:
+    #
+    #   rescreening.call(book)
+    #   rescreening.call(book) { |alert| queue.push(alert) }
+    #
+    # `subjects` is anything that responds to `each`, so an Enumerator over a
+    # database cursor is streamed rather than materialized. Each entry is a
+    # Subject or the Hash one is built from.
+    #
+    # Every alert in a run carries one `screened_at`, because a rescreening
+    # of a book against a new list version is a single event in an audit
+    # trail rather than ten thousand of them a microsecond apart. A host that
+    # calls this once per batch is running one event per batch, which is the
+    # honest description of what it did.
+    sig do
+      params(subjects: T.untyped, block: T.nilable(T.proc.params(alert: Alert).void)).returns(T::Array[Alert])
+    end
+    def call(subjects, &block)
+      return [] if diff.empty?
+
+      screened_at = Time.now.utc
+      alerts = T.let([], T::Array[Alert])
+      each(subjects) do |value|
+        found(Subject.build(value), screened_at).each do |alert|
+          block&.call(alert)
+          alerts << alert
+        end
+      end
+      alerts
+    end
+
+    # The list this run is about, taken from the diff.
+    sig { returns(Symbol) }
+    def source = diff.source
+
+    # How many records moved, which is what a run costs per subject.
+    sig { returns(Integer) }
+    def size = diff.size
+
+    # Nothing moved, so nothing can be affected. See the class comment.
+    sig { returns(T::Boolean) }
+    def empty? = diff.empty?
+
+    sig { returns(String) }
+    def inspect = "#<#{self.class} #{source} #{size} changed records at #{threshold}>"
+
+    private
+
+    # The alerts one subject raises, highest score first and then by record
+    # id, so that two runs over the same diff and the same book produce the
+    # same output in the same order.
+    sig { params(subject: Subject, screened_at: Time).returns(T::Array[Alert]) }
+    def found(subject, screened_at)
+      cutoff = subject.threshold || threshold
+      readings = candidates(subject).filter_map { |id| compare(subject, id, cutoff) }
+      return [] if readings.empty?
+
+      query = subject.query(threshold: cutoff, sources: [source])
+      readings.map { |reading| alert(subject, reading, query, screened_at) }
+              .sort_by { |raised| [-(raised.score || T.must(raised.previous_score)), raised.entity_id] }
+    end
+
+    # The records worth scoring this subject against: the same retrieval stage
+    # a screening call uses, over a corpus the size of the diff. An entity
+    # reached through two of its names, or through both versions of itself, is
+    # one record to compare and not two.
+    sig { params(subject: Subject).returns(T::Array[String]) }
+    def candidates(subject)
+      @index.candidates(subject.form, limit: candidate_limit).map { |candidate| candidate.entity.id }.uniq
+    end
+
+    # What this subject scores against both versions of one record, or nil
+    # when it reaches the threshold against neither -- which is the answer for
+    # nearly every pair and is why the cutoff is passed to the scorer rather
+    # than applied afterwards. See Scorer on what a threshold buys.
+    sig { params(subject: Subject, id: String, cutoff: Float).returns(T.nilable(T::Array[T.untyped])) }
+    def compare(subject, id, cutoff)
+      previous, current = @versions.fetch(id)
+      before = score(subject, previous, cutoff)
+      after = score(subject, current, cutoff)
+      return nil if before.nil? && after.nil?
+
+      change = if before.nil? then :newly_listed
+               elsif after.nil? then :delisted
+               else :details_changed
+               end
+      # The side that did not clear is scored again without a cutoff, so an
+      # alert can say a subject moved from 71 to 94 rather than only that it
+      # now matches. Reached once per alert, which is why it is affordable.
+      [id, change, before || score(subject, previous, 0.0), after || score(subject, current, 0.0)]
+    end
+
+    sig { params(subject: Subject, entity: T.untyped, cutoff: Float).returns(T.nilable(Scorer::Result)) }
+    def score(subject, entity, cutoff)
+      return nil if entity.nil?
+
+      Scorer.call(subject.evidence, entity, weights: weights, threshold: cutoff)
+    end
+
+    sig do
+      params(subject: Subject, reading: T::Array[T.untyped], query: Query, screened_at: Time).returns(Alert)
+    end
+    def alert(subject, reading, query, screened_at)
+      id, change, before, after = reading
+      Alert.new(
+        subject: subject, change: change, fields: @fields.fetch(id, []),
+        result: stamp(after, diff.to.checksum, query, screened_at),
+        previous_result: stamp(before, T.must(diff.from).checksum, query, screened_at),
+        snapshot_id: diff.to.checksum, previous_snapshot_id: T.must(diff.from).checksum
+      )
+    end
+
+    # One scored record as the audit object it has to be, stamped with the
+    # checksum of the list version it was scored against -- which is the whole
+    # of why an alert holds two of these rather than one score and a delta.
+    sig do
+      params(result: T.nilable(Scorer::Result), snapshot_id: String, query: Query,
+             screened_at: Time).returns(T.nilable(MatchResult))
+    end
+    def stamp(result, snapshot_id, query, screened_at)
+      return nil if result.nil?
+
+      MatchResult.from_scorer(result, query: query, snapshot_id: snapshot_id, weights: weights,
+                                      screened_at: screened_at, backend: backend)
+    end
+
+    sig { params(subjects: T.untyped, block: T.proc.params(value: T.untyped).void).void }
+    def each(subjects, &block)
+      unless subjects.respond_to?(:each)
+        raise InvalidArgument,
+              "a book of subjects has to be enumerable, got #{subjects.class}. An Array, or anything that " \
+              "responds to #each -- an Enumerator over a database cursor is streamed rather than materialized"
+      end
+
+      subjects.each(&block)
+    end
+
+    # Every record the diff names, by id, as a pair: how the old list had it
+    # and how the new list has it. A record that was added has no first half
+    # and one that was withdrawn has no second, and an amended one has both --
+    # which is what lets a single comparison produce a score on either side of
+    # the change. The three sets are disjoint, because a diff joins its two
+    # snapshots by id.
+    sig { returns(T::Hash[String, T::Array[T.untyped]]) }
+    def versions
+      found = T.let({}, T::Hash[String, T::Array[T.untyped]])
+      diff.removed.each { |entity| found[entity.id] = [entity, nil].freeze }
+      diff.added.each { |entity| found[entity.id] = [nil, entity].freeze }
+      diff.modified.each { |change| found[change.id] = [change.previous, change.entity].freeze }
+      found.freeze
+    end
+
+    sig { params(value: T.untyped).returns(Float) }
+    def threshold!(value) = Scorer.threshold!(value || ActiveSanction.config.screening_threshold)
+
+    sig { params(value: T.untyped).returns(Integer) }
+    def candidate_limit!(value) = Integer(value || ActiveSanction.config.candidate_limit)
+
+    # Which fields moved, per amended record, so an alert can say whether a
+    # subject's status changed because the list did or because the record did.
+    sig { returns(T::Hash[String, T::Array[Symbol]]) }
+    def amended = diff.modified.to_h { |change| [change.id, change.fields] }.freeze
+
+    # A baseline diff is empty, so `from` is present on every diff that can
+    # raise an alert -- which is what lets an alert cite both checksums. The
+    # check is here rather than at the alert, where the missing one would read
+    # as a bug in this class.
+    sig { params(value: T.untyped).returns(Diff) }
+    def diff!(value)
+      raise InvalidArgument, "diff must be an ActiveSanction::Diff, got #{value.class}" unless value.is_a?(Diff)
+      return value if value.empty? || value.from
+
+      raise InvalidArgument, "a rescreen needs both list versions to cite, and this diff has no `from`"
+    end
+  end
+end

data/lib/active_sanction/scorer/adjustments.rb

@@ -0,0 +1,241 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/country"
+require "active_sanction/scorer/reason"
+
+module ActiveSanction
+  module Scorer
+    # What the record says about a subject other than their name, and what
+    # each agreement and each contradiction is worth.
+    #
+    #   ActiveSanction::Scorer::Adjustments.call(subject, entity)
+    #   # => [#<Reason +40.0 identifier: passport AB123456 matches>,
+    #   #     #<Reason  -8.0 nationality: query RU vs listed EG>]
+    #
+    # Stage 4b, and the part that separates a usable screening tool from a
+    # name-similarity toy. A name score alone puts thousands of people on a
+    # list of a few hundred, because a quarter of the individuals on these
+    # lists share a handful of given names and every one of them scores in the
+    # seventies against every other. The passport number, the date of birth
+    # and the nationality are what tell those apart, and they are the fields a
+    # compliance officer already has in a customer record.
+    #
+    # ### Absent is not conflict, and it is the rule everything here obeys
+    #
+    # Most records lack most identifiers. Canada publishes no aliases and
+    # frequently no date of birth; OFAC's dates are prose in a remarks field
+    # and are missing wherever the sentence did not parse; the UN grades what
+    # it has and says nothing about what it does not. So every adjustment
+    # below fires only when *both* sides carry the field, and a field missing
+    # on either side produces no Reason at all -- not a small penalty, not a
+    # zero-valued reason.
+    #
+    # Treating absence as disagreement would penalize exactly the sparser
+    # lists, which means systematically under-scoring the jurisdictions that
+    # publish least and hiding real hits behind a threshold. It is the
+    # quietest way to build a screening tool that does not screen, and it is
+    # why this is stated as a rule rather than left to each branch.
+    #
+    # The same rule governs a country nobody can resolve. A nationality of
+    # `Ruritania` is not a contradiction of `Egypt`; it is a string this
+    # library does not recognize, and the difference between those two is a
+    # penalty applied to a match that was correct. See Country.
+    #
+    # ### The three signals, and why they are worth what they are
+    #
+    # **A document number is the only near-decisive field on a sanctions
+    # record.** Two people share a name; they do not share a passport number.
+    # It is the one place where agreement outranks everything the name said,
+    # which is what a boost of 40 points on a 100-point scale means: a name in
+    # the fifties plus the right passport clears any threshold this library
+    # would ship.
+    #
+    # **A date of birth is strong evidence in both directions.** An exact full
+    # date agreeing is worth a real boost; a genuine conflict -- two dates
+    # that cannot describe the same person -- is worth more against, because
+    # sharing a birthday with a listed person is a coincidence a few thousand
+    # people have and not having theirs is not. `PartialDate#overlaps?` is
+    # what decides which of the three cases a pair is in, and it is exact
+    # whatever precision either side carries: a year-only record does not
+    # conflict with a full date inside it, it agrees with it, weakly.
+    #
+    # **Nationality moves the score least.** People hold two passports, lists
+    # record the country a person was born in as readily as the one they are a
+    # citizen of, and the field is published as prose. It is real evidence and
+    # it is the softest of the three.
+    #
+    # ### Order is fixed, because an explanation is read
+    #
+    # Identifier, then date of birth, then nationality: strongest evidence
+    # first, so a reviewer reading an explanation downwards meets the reason
+    # the score is what it is before meeting the ones that adjusted it. The
+    # order is also what makes a score reproducible to the last decimal --
+    # see Scorer on why the sum has to be taken the same way every time.
+    #
+    # @api private
+    module Adjustments
+      extend T::Sig
+
+      # Below this many alphanumerics, a "document number" is not a document
+      # number. Nothing a government issues is three characters long, and an
+      # exact match on a short string is the one way a 40-point boost could
+      # land on a coincidence -- a remarks parser that read `Passport 12` out
+      # of a half-formed sentence would otherwise make two unrelated records
+      # decisive for each other.
+      MINIMUM_IDENTIFIER_LENGTH = T.let(4, Integer)
+
+      module_function
+
+      # Every adjustment both sides carry the evidence for, strongest first.
+      # An empty array is the ordinary answer for a record that publishes a
+      # name and nothing else.
+      sig do
+        params(subject: Subject, entity: Entity, weights: Weights)
+          .returns(T::Array[Reason]).checked(:tests)
+      end
+      def call(subject, entity, weights = Weights.default)
+        [identifier(subject, entity, weights), dob(subject, entity, weights),
+         nationality(subject, entity, weights)].compact
+      end
+
+      # The first document number both sides carry, in the order the caller
+      # and the publisher listed them. First rather than best: there is no
+      # "better" exact match on a document number, and iterating in a fixed
+      # order is what makes the explanation identical on every run.
+      sig { params(subject: Subject, entity: Entity, weights: Weights).returns(T.nilable(Reason)).checked(:tests) }
+      def identifier(subject, entity, weights)
+        subject.identifiers.each do |mine|
+          next if mine.normalized_value.length < MINIMUM_IDENTIFIER_LENGTH
+
+          theirs = entity.identifiers.find { |listed| same_document?(mine, listed) }
+          next if theirs.nil?
+
+          return Reason.new(factor: :identifier, contribution: weights.identifier_match,
+                            detail: document_detail(mine, theirs))
+        end
+        nil
+      end
+
+      # Exact, overlapping, or contradictory -- in that order, over every
+      # pairing of the dates the two sides carry. Both plural: the UN
+      # publishes more than one date of birth for 140 of its individuals
+      # because several governments reported several dates, and any of them
+      # matching is a match. A conflict therefore means *no* pairing overlaps,
+      # which is the only reading that does not turn an honestly uncertain
+      # record into a penalty.
+      sig { params(subject: Subject, entity: Entity, weights: Weights).returns(T.nilable(Reason)).checked(:tests) }
+      def dob(subject, entity, weights)
+        mine = subject.dates_of_birth
+        theirs = entity.dates_of_birth
+        return nil if mine.empty? || theirs.empty?
+
+        agreement(mine.product(theirs), weights) ||
+          dob_reason(:dob_conflict, "#{mine.join(", ")} conflicts with listed #{theirs.join(", ")}", weights)
+      end
+
+      # The best of the pairings, or nil when none of them agree at all --
+      # which is what makes the caller above a conflict.
+      sig do
+        params(pairs: T::Array[T::Array[PartialDate]], weights: Weights)
+          .returns(T.nilable(Reason)).checked(:tests)
+      end
+      def agreement(pairs, weights)
+        exact = pairs.find { |left, right| same_day?(T.must(left), T.must(right)) }
+        return dob_reason(:dob_exact, "#{exact.first} matches", weights) if exact
+
+        overlap = pairs.find { |left, right| T.must(left).overlaps?(right) }
+        return nil if overlap.nil?
+
+        dob_reason(:dob_overlap, "#{overlap.first} overlaps listed #{overlap.last}", weights)
+      end
+
+      # Agreement, or a contradiction both sides are precise enough to make.
+      #
+      # A country is compared as the alpha-2 code it resolves to, falling back
+      # to its folded string so that two publishers writing the same
+      # unrecognized value still agree. A *conflict* needs more: every value
+      # on both sides has to have resolved, because "these two strings are not
+      # equal" is not evidence that two countries are different.
+      sig { params(subject: Subject, entity: Entity, weights: Weights).returns(T.nilable(Reason)).checked(:tests) }
+      def nationality(subject, entity, weights)
+        listed = entity.nationalities
+        return nil if subject.nationalities.empty? || listed.empty?
+
+        mine = keys(subject.nationalities)
+        theirs = keys(listed)
+        shared = mine & theirs
+        if shared.any?
+          return Reason.new(factor: :nationality, contribution: weights.nationality_match,
+                            detail: "#{shared.join(", ")} matches")
+        end
+        return nil unless subject.countries? && resolved?(listed)
+
+        Reason.new(factor: :nationality, contribution: weights.nationality_conflict,
+                   detail: "query #{mine.join(", ")} vs listed #{theirs.join(", ")}")
+      end
+
+      # Kind, number and country all have to be compatible, and two of the
+      # three treat "unstated" as compatible rather than as different.
+      #
+      # `:other` is the kind OFAC's remarks produce for a number its sentence
+      # did not classify, so requiring the kinds to be equal would throw away
+      # most of the document numbers this library extracts. Country is the
+      # opposite case and is why Identifier's own equality carries it: two
+      # passports with the same number from different countries are different
+      # documents, so a country stated on both sides and disagreeing is a
+      # mismatch -- while a country stated on neither, or on one, is not.
+      sig { params(mine: Identifier, theirs: Identifier).returns(T::Boolean).checked(:tests) }
+      def same_document?(mine, theirs)
+        return false unless mine.normalized_value == theirs.normalized_value
+        return false unless mine.kind == theirs.kind || mine.kind == :other || theirs.kind == :other
+
+        same_country?(mine.country, theirs.country)
+      end
+
+      sig { params(mine: T.nilable(String), theirs: T.nilable(String)).returns(T::Boolean).checked(:tests) }
+      def same_country?(mine, theirs)
+        return true if mine.nil? || theirs.nil?
+
+        key(mine) == key(theirs)
+      end
+
+      # A full date on both sides, neither hedged with a "circa", naming the
+      # same day. Anything less precise is an overlap: `1948` and `1948-12-10`
+      # agree, and saying they match exactly would claim a precision the
+      # publisher did not.
+      sig { params(mine: PartialDate, theirs: PartialDate).returns(T::Boolean).checked(:tests) }
+      def same_day?(mine, theirs)
+        mine.precision == :day && theirs.precision == :day &&
+          !mine.approximate? && !theirs.approximate? && mine.first_date == theirs.first_date
+      end
+
+      sig { params(weight: Symbol, detail: String, weights: Weights).returns(Reason).checked(:tests) }
+      def dob_reason(weight, detail, weights)
+        Reason.new(factor: :dob, detail: "date of birth #{detail}", contribution: weights.fetch(weight))
+      end
+
+      sig { params(mine: Identifier, theirs: Identifier).returns(String).checked(:tests) }
+      def document_detail(mine, theirs)
+        kind = mine.kind == :other ? theirs.kind : mine.kind
+        return "#{kind} #{mine.value} matches" if mine.value == theirs.value
+
+        "#{kind} #{mine.value} matches listed #{theirs.value}"
+      end
+
+      # The alpha-2 code, or the folded string when the table does not know
+      # the value. Never nil, so agreement can be found on a spelling neither
+      # side could resolve.
+      sig { params(value: String).returns(String).checked(:tests) }
+      def key(value) = Country.code(value) || Country.fold(value)
+
+      sig { params(values: T::Array[String]).returns(T::Array[String]).checked(:tests) }
+      def keys(values) = values.map { |value| key(value) }.uniq
+
+      sig { params(values: T::Array[String]).returns(T::Boolean).checked(:tests) }
+      def resolved?(values) = values.all? { |value| Country.code(value) }
+    end
+  end
+end