active_sanction 1.0.0

data/lib/active_sanction/phonetics.rb

@@ -0,0 +1,40 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module ActiveSanction
+  # What a name sounds like, as a key two spellings of it can share. Stage 3c
+  # of the matching pipeline.
+  #
+  #   ActiveSanction::Phonetics::DoubleMetaphone.call("qaddafi")   # => ["KTF"]
+  #   ActiveSanction::Phonetics::DoubleMetaphone.call("gaddafi")   # => ["KTF"]
+  #
+  # ### Why this is not in Similarity
+  #
+  # Because a key is not a score. Everything in Similarity answers "how close
+  # are these two names" with a number between 0 and 1, and the whole of that
+  # module's contract -- symmetric, never rounded, `threshold:` as an
+  # optimization, a `ceiling` that may never come in under a real score --
+  # is about keeping four such numbers comparable enough to blend.
+  #
+  # This stage answers a different question and gives a different kind of
+  # answer: it turns one name into the handful of strings that stand for how
+  # it sounds. Two names either share one of those strings or they do not.
+  # That is what makes it useful in the two places it is used --
+  #
+  # - the inverted index (#31) keys on it, so that a query for `GADDAFI`
+  #   reaches a record spelled `QADHAFI` at all, which no amount of comparing
+  #   would help with if the record is never fetched; and
+  # - the scorer (#32) reads it as one share of the blend it scores a pair on.
+  #
+  # -- and it is also why it cannot be blended with the other four. A shared
+  # key is evidence, at the strength #32 decides. It is never a match on its
+  # own: `HSN` is the key for `HUSSEIN`, and equally for `HASSAN`.
+  #
+  # @api private
+  module Phonetics
+  end
+end
+
+require "active_sanction/phonetics/double_metaphone"

data/lib/active_sanction/query.rb

@@ -0,0 +1,290 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/scorer"
+require "active_sanction/sources/definition"
+
+module ActiveSanction
+  # One screening request: what is known about the subject, and how the
+  # search is to be run.
+  #
+  #   query = ActiveSanction::Query.build(
+  #     name:          "Bosco Ntaganda",
+  #     type:          :individual,
+  #     date_of_birth: "1973",
+  #     countries:     %w[CD],
+  #     sources:       %i[ofac_sdn un_consolidated],
+  #     threshold:     75,
+  #     limit:         10
+  #   )
+  #
+  #   query.subject     # => Scorer::Subject, folded once and held
+  #   query.threshold   # => 75.0
+  #
+  # ### Two kinds of field, and the line between them matters
+  #
+  # **Evidence** -- the name, the type, the dates of birth, the nationalities,
+  # the identifiers -- is what the scorer compares against a record, and it
+  # belongs to Scorer::Subject, which this builds and holds. **Search
+  # options** -- `sources`, `threshold`, `limit` -- decide which records are
+  # looked at and how many come back, and they never touch a comparison.
+  #
+  # Keeping them apart is what lets a stored decision be re-derived: the
+  # evidence says what was screened and the options say what the run was
+  # willing to return, and an audit needs both separately. It is also why
+  # Subject carries no threshold -- see the note at the end of that class.
+  #
+  # ### Singular and plural spellings are both accepted
+  #
+  # `date_of_birth:` and `dates_of_birth:`, `country:`, `countries:` and
+  # `nationalities:`, `identifier:` and `identifiers:` all mean the same
+  # thing. A caller with one date writes the singular and a caller with three
+  # writes the plural, and neither should have to remember which this library
+  # prefers. `#to_h` emits the plural, canonical spelling.
+  #
+  # That resolution happens in `.build` and `.from_h`, which is what every
+  # screening call goes through -- `Matcher#screen` builds one of these out of
+  # whatever it was handed. `.new` takes the canonical names and nothing else,
+  # in the manner of Scorer::Weights: one constructor states the shape and one
+  # accepts what a caller wrote.
+  #
+  # ### Defaults come from configuration, once, here
+  #
+  # A query with no `threshold:` takes `config.screening_threshold` and one
+  # with no `limit:` takes `config.screening_limit`, both read at construction
+  # and then fixed. Nothing downstream reads a global: a Matcher screens the
+  # numbers on the query it was given, so a configuration changed mid-batch
+  # cannot produce a run that is half one threshold and half another.
+  #
+  # Instances are frozen on construction and compare by value.
+  class Query
+    extend T::Sig
+
+    # The canonical spelling of every field, and the shape `#to_h` emits.
+    #
+    # @api private
+    MEMBERS = T.let(
+      %i[name type dates_of_birth nationalities identifiers sources threshold limit].freeze,
+      T::Array[Symbol]
+    )
+
+    # The spellings a caller may write instead, and what each one means. See
+    # the note above.
+    #
+    # @api private
+    ALIASES = T.let(
+      {
+        date_of_birth: :dates_of_birth, dob: :dates_of_birth, dobs: :dates_of_birth,
+        country: :nationalities, countries: :nationalities, nationality: :nationalities,
+        identifier: :identifiers, source: :sources
+      }.freeze,
+      T::Hash[Symbol, Symbol]
+    )
+
+    # The members that are lists. A value that is not one becomes a list of
+    # one, which is what makes `identifier: { kind: :passport, value: "AB-1" }`
+    # a single identifier: `Array(hash)` reads a Hash as a list of its pairs,
+    # and a caller naming one document would get two nonsense identifiers back.
+    #
+    # @api private
+    COLLECTIONS = T.let(%i[dates_of_birth nationalities identifiers sources].freeze, T::Array[Symbol])
+
+    # The evidence, folded once. Every comparison in a screening run happens
+    # against this one object rather than against a name re-folded per
+    # candidate.
+    sig { returns(Scorer::Subject) }
+    attr_reader :subject
+
+    # Which lists to screen against, or nil for every list the matcher holds.
+    # Naming one it does not hold is an error rather than a shorter answer --
+    # see Matcher.
+    sig { returns(T.nilable(T::Array[Symbol])) }
+    attr_reader :sources
+
+    # 0..100. The lowest score worth reporting, and the number that decides
+    # what a screening call costs -- see Scorer.
+    sig { returns(Float) }
+    attr_reader :threshold
+
+    # How many results to return, highest score first.
+    sig { returns(Integer) }
+    attr_reader :limit
+
+    class << self
+      extend T::Sig
+
+      # Whatever a caller had, as a Query:
+      #
+      #   Query.build("Bosco Ntaganda")
+      #   Query.build(name: "Bosco Ntaganda", threshold: 80)
+      #   Query.build(query, limit: 5)         # the same query, with one option changed
+      #
+      # A bare String or Name is a query about that name and nothing else,
+      # which is what a batch of names is a list of.
+      sig { params(value: T.untyped, overrides: T.untyped).returns(Query) }
+      def build(value = nil, **overrides)
+        case value
+        when Query then overrides.empty? ? value : T.unsafe(value).merge(**overrides)
+        when Hash then from_h(normalize(value).merge(normalize(overrides)))
+        when nil then from_h(overrides)
+        else from_h(normalize(overrides).merge(name: value))
+        end
+      end
+
+      # Rebuilds a query from #to_h output, accepting string keys so one
+      # stored in an audit record survives the round-trip through JSON.
+      sig { params(hash: T.untyped).returns(Query) }
+      def from_h(hash)
+        attributes = normalize(hash)
+        unknown = attributes.keys - MEMBERS
+        raise QueryError, "unknown Query attribute(s): #{unknown.join(", ")}" if unknown.any?
+
+        # `new(**hash)` past a required keyword parameter is one of the few
+        # things Sorbet cannot check statically. #initialize validates what
+        # arrives, which is where a bad round-trip is caught.
+        T.unsafe(self).new(**attributes)
+      end
+
+      private
+
+      # Symbol keys, with every accepted spelling resolved to its canonical
+      # one. A caller that wrote both spellings of the same field is a typo
+      # rather than a merge, so it is refused.
+      sig { params(hash: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+      def normalize(hash)
+        spellings = T.let({}, T::Hash[Symbol, Symbol])
+        hash.to_h.each_with_object({}) do |(key, value), attributes|
+          written = key.to_s.to_sym
+          member = ALIASES.fetch(written, written)
+          clash = spellings[member]
+          raise QueryError, "#{clash} and #{written} are the same field -- pass one" if conflict?(clash, written)
+
+          spellings[member] = written
+          attributes[member] = wrap(member, value)
+        end
+      end
+
+      sig { params(clash: T.nilable(Symbol), written: Symbol).returns(T::Boolean) }
+      def conflict?(clash, written) = !clash.nil? && clash != written
+
+      sig { params(member: Symbol, value: T.untyped).returns(T.untyped) }
+      def wrap(member, value)
+        return value unless COLLECTIONS.include?(member)
+        return value if value.nil? || value.is_a?(Array)
+
+        [value]
+      end
+    end
+
+    # Only `name` is required; see Scorer::Subject on why that is the shape of
+    # the problem rather than a convenience.
+    sig do
+      params(name: T.untyped, type: T.untyped, dates_of_birth: T.untyped, nationalities: T.untyped,
+             identifiers: T.untyped, sources: T.untyped, threshold: T.untyped, limit: T.untyped).void
+    end
+    def initialize(name:, type: nil, dates_of_birth: [], nationalities: [], identifiers: [],
+                   sources: nil, threshold: nil, limit: nil)
+      @subject = T.let(
+        Scorer::Subject.new(name: name, type: type, dates_of_birth: dates_of_birth,
+                            nationalities: nationalities, identifiers: identifiers),
+        Scorer::Subject
+      )
+      @sources = T.let(sources!(sources), T.nilable(T::Array[Symbol]))
+      @threshold = T.let(threshold!(threshold), Float)
+      @limit = T.let(limit!(limit), Integer)
+      freeze
+    end
+
+    # This query with some fields replaced, which is how a batch applies one
+    # threshold to a list of names.
+    sig { params(overrides: T.untyped).returns(Query) }
+    def merge(**overrides) = self.class.build(to_h, **overrides)
+
+    # The name as the caller wrote it, which is what a report quotes back.
+    sig { returns(String) }
+    def name = subject.name
+
+    sig { returns(T.nilable(Symbol)) }
+    def type = subject.type
+
+    sig { returns(T::Array[PartialDate]) }
+    def dates_of_birth = subject.dates_of_birth
+
+    sig { returns(T::Array[String]) }
+    def nationalities = subject.nationalities
+
+    sig { returns(T::Array[Identifier]) }
+    def identifiers = subject.identifiers
+
+    # The folded name every comparison runs against, and what a Matcher hands
+    # the index rather than the string it came from.
+    sig { returns(Normalizer::Form) }
+    def form = subject.form
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def to_h
+      subject.to_h.merge(sources: sources, threshold: threshold, limit: limit)
+    end
+
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def ==(other)
+      return false unless other.instance_of?(self.class)
+
+      to_h == other.to_h
+    end
+    alias eql? ==
+
+    sig { returns(Integer) }
+    def hash = [self.class, to_h].hash
+
+    sig { returns(String) }
+    def inspect = "#<#{self.class} #{name.inspect} threshold=#{threshold} limit=#{limit}>"
+
+    private
+
+    # nil means every list the matcher holds. An empty array does not: a
+    # caller that computed its source list and got nothing back is asking to
+    # screen against no lists at all, which returns a clean report for
+    # everybody, so it is refused rather than quietly read as "all".
+    sig { params(value: T.untyped).returns(T.nilable(T::Array[Symbol])) }
+    def sources!(value)
+      return nil if value.nil?
+
+      keys = Array(value).map { |key| Sources::Definition.key!(key) }.uniq
+      raise QueryError, "sources cannot be empty -- omit it to screen against every list" if keys.empty?
+
+      keys.freeze
+    end
+
+    # Validated by the scorer's own check, so a threshold on the 0..1 scale is
+    # refused here with the message that explains it rather than three layers
+    # down.
+    sig { params(value: T.untyped).returns(Float) }
+    def threshold!(value)
+      return Scorer.threshold!(ActiveSanction.config.screening_threshold) if value.nil?
+
+      number = begin
+        Float(value)
+      rescue TypeError, ArgumentError
+        raise QueryError, "threshold must be a number between 0 and 100, got #{value.inspect}"
+      end
+      Scorer.threshold!(number)
+    end
+
+    sig { params(value: T.untyped).returns(Integer) }
+    def limit!(value)
+      return ActiveSanction.config.screening_limit if value.nil?
+
+      integer = begin
+        Integer(value)
+      rescue TypeError, ArgumentError
+        raise QueryError, "limit must be a whole number of results, got #{value.inspect}"
+      end
+      raise QueryError, "limit must be at least 1, got #{integer}" unless integer.positive?
+
+      integer
+    end
+  end
+end

data/lib/active_sanction/rescreen/alert.rb

@@ -0,0 +1,314 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/error"
+require "active_sanction/match_result"
+require "active_sanction/subject"
+
+module ActiveSanction
+  class Rescreen
+    # One subject, one record, and what moved between two list versions.
+    #
+    #   alert.subject_id      # => "cust_1"
+    #   alert.change          # => :newly_listed
+    #   alert.result          # => MatchResult, scored against the record as it is now
+    #   alert.previous_result # => nil -- there was no such record before
+    #   alert.score           # => 94.1
+    #   alert.previous_score  # => nil
+    #
+    #   puts alert
+    #   # => cust_1  newly listed  un_consolidated:6908021  BOSCO TAGANDA  94.1
+    #
+    # ### The two sides, and why either may be missing
+    #
+    # An alert is a *change*, so it is two screening results rather than one:
+    # `previous_result` is what this subject scored against the record as the
+    # old list had it, and `result` is what it scores against the record as
+    # the new list has it. A newly listed record has no previous side. A
+    # delisted one has no current side. Everything else has both, and the pair
+    # is what lets an alert say a subject moved from 71 to 94 rather than
+    # merely that it now matches -- which is the difference between an analyst
+    # reading a record and an analyst reading a change to one.
+    #
+    # Both are full MatchResults, each stamped with the checksum of the list
+    # version it was scored against, so an alert is defensible the same way a
+    # screening decision is: the explanation is on it, and it adds up.
+    # `#evidence` is the side the alert was raised on, for a caller that wants
+    # the record and does not care which list version described it.
+    #
+    # The side that did *not* clear is scored again without a cutoff, so its
+    # result may sit below the threshold its own query names -- which is
+    # exactly what a subject moving into or out of range looks like, and is
+    # the whole reason the score is carried rather than only the fact of a
+    # match.
+    #
+    # ### What `change` says, and what it does not
+    #
+    # It is about **this subject's match**, not about the record's paperwork:
+    #
+    # - `:newly_listed` -- the subject did not reach the threshold against
+    #   this record before and does now. Usually because the record is new;
+    #   also because an existing record gained the alias, the identifier or
+    #   the date of birth that brought the subject over the line, which is the
+    #   same event for a compliance team and is why it is not filed
+    #   separately.
+    # - `:delisted` -- it did reach the threshold before and does not now.
+    #   Usually because the record was withdrawn; also because an amendment
+    #   moved it out of range. This is the half of a rescreen that a run
+    #   against new records only would miss, and it is the half that lets a
+    #   customer back through the door.
+    # - `:details_changed` -- it matched before, it matches now, and the
+    #   record moved underneath it. The score may be identical: a program
+    #   added or an address corrected changes what a hit *means* without
+    #   changing what it scores, and deciding that such a change is too small
+    #   to report would be deciding which sanctions hits a host is willing to
+    #   miss.
+    #
+    # Which of those two routes into `:newly_listed` and `:delisted` a given
+    # alert took is not guesswork -- `#fields` is empty when the record itself
+    # arrived or left, and names the fields that moved when it was amended.
+    #
+    # ### Both snapshot ids, on every alert
+    #
+    # A MatchResult cites the one list version it was scored against, and an
+    # alert is about two. So it carries both: `previous_snapshot_id` and
+    # `snapshot_id` are the checksums the diff was computed over, which is
+    # what makes an alert reproducible under audit -- keep the pair and the
+    # whole run can be derived again, from lists that can be identified rather
+    # than from a copy of an answer nobody can check.
+    #
+    # Instances are frozen on construction and compare by value.
+    class Alert
+      extend T::Sig
+
+      # What happened to this subject's match. See the class comment.
+      CHANGES = T.let(%i[newly_listed delisted details_changed].freeze, T::Array[Symbol])
+
+      # @api private
+      MEMBERS = T.let(
+        %i[subject change fields result previous_result snapshot_id previous_snapshot_id].freeze,
+        T::Array[Symbol]
+      )
+
+      # The book entry this alert is about, as the caller supplied it.
+      sig { returns(Subject) }
+      attr_reader :subject
+
+      sig { returns(Symbol) }
+      attr_reader :change
+
+      # The fields of the record that moved, in Entity's member order, or an
+      # empty array when the record was added or withdrawn whole. See
+      # Diff::Change.
+      sig { returns(T::Array[Symbol]) }
+      attr_reader :fields
+
+      # Scored against the record as the new list has it, or nil when the new
+      # list does not have it.
+      sig { returns(T.nilable(MatchResult)) }
+      attr_reader :result
+
+      # Scored against the record as the old list had it, or nil when the old
+      # list did not have it.
+      sig { returns(T.nilable(MatchResult)) }
+      attr_reader :previous_result
+
+      # The checksum of the list version this run screened against.
+      sig { returns(String) }
+      attr_reader :snapshot_id
+
+      # The checksum of the list version it was compared with.
+      sig { returns(String) }
+      attr_reader :previous_snapshot_id
+
+      # Rebuilds an alert from #to_h output, accepting string keys so one
+      # survives the round-trip through JSON and back out of whatever a host
+      # stored it in.
+      sig { params(hash: T.untyped).returns(T.attached_class) }
+      def self.from_h(hash)
+        attributes = hash.to_h.transform_keys(&:to_sym)
+        unknown = attributes.keys - MEMBERS
+        raise InvalidArgument, "unknown Alert attribute(s): #{unknown.join(", ")}" if unknown.any?
+
+        T.unsafe(self).new(**attributes,
+                           subject: build(Subject, attributes[:subject]),
+                           result: build(MatchResult, attributes[:result]),
+                           previous_result: build(MatchResult, attributes[:previous_result]))
+      end
+
+      # A value that is already the object passes through, so from_h is safe
+      # to call on a half-deserialized hash.
+      sig { params(klass: T.untyped, value: T.untyped).returns(T.untyped) }
+      def self.build(klass, value) = value.is_a?(Hash) ? klass.from_h(value) : value
+      private_class_method :build
+
+      sig do
+        params(subject: T.untyped, change: T.untyped, snapshot_id: T.untyped, previous_snapshot_id: T.untyped,
+               result: T.untyped, previous_result: T.untyped, fields: T.untyped).void
+      end
+      def initialize(subject:, change:, snapshot_id:, previous_snapshot_id:, result: nil, previous_result: nil,
+                     fields: [])
+        @subject = T.let(instance!(:subject, Subject, subject), Subject)
+        @change = T.let(change!(change), Symbol)
+        @result = T.let(result!(:result, result), T.nilable(MatchResult))
+        @previous_result = T.let(result!(:previous_result, previous_result), T.nilable(MatchResult))
+        sides!
+        @fields = T.let(Array(fields).map(&:to_sym).freeze, T::Array[Symbol])
+        @snapshot_id = T.let(string!(:snapshot_id, snapshot_id), String)
+        @previous_snapshot_id = T.let(string!(:previous_snapshot_id, previous_snapshot_id), String)
+        freeze
+      end
+
+      # The caller's own id for the subject, which is what an alert is joined
+      # back to a book of business by.
+      sig { returns(String) }
+      def subject_id = subject.id
+
+      # The side the alert was raised on: the current one, or the previous one
+      # for a delisting, which is the version that actually matched. It is
+      # what `#entity` and `#matched_name` read, so an alert describes the
+      # record the way it looked when it crossed the threshold.
+      #
+      # Never nil: an alert with neither side is not a change, and is refused
+      # at construction.
+      sig { returns(MatchResult) }
+      def evidence = T.must(delisted? ? previous_result || result : result || previous_result)
+
+      # The record this alert is about, as the surviving side has it.
+      sig { returns(Entity) }
+      def entity = evidence.entity
+
+      sig { returns(String) }
+      def entity_id = entity.id
+
+      # The spelling that produced the score, as its publisher wrote it. See
+      # MatchResult#matched_name.
+      sig { returns(Name) }
+      def matched_name = evidence.matched_name
+
+      sig { returns(Symbol) }
+      def source = entity.source
+
+      # What the subject scores against the record now, or nil if the record
+      # is no longer on the list.
+      sig { returns(T.nilable(Float)) }
+      def score = result&.score
+
+      # What it scored against the record before, or nil if the record was
+      # not on the previous list.
+      sig { returns(T.nilable(Float)) }
+      def previous_score = previous_result&.score
+
+      # The threshold this subject was screened at, which is half of what
+      # makes the change mean anything: the same pair of scores is a new
+      # listing at 75 and nothing at all at 95.
+      sig { returns(Float) }
+      def threshold = evidence.threshold
+
+      # When the run that produced this alert happened. One instant for a
+      # whole run -- see Rescreen.
+      sig { returns(Time) }
+      def screened_at = evidence.screened_at
+
+      sig { returns(T::Boolean) }
+      def newly_listed? = change == :newly_listed
+
+      sig { returns(T::Boolean) }
+      def delisted? = change == :delisted
+
+      sig { returns(T::Boolean) }
+      def details_changed? = change == :details_changed
+
+      # The documented shape. Every value is a String, a Float, an Integer, an
+      # Array or a Hash of the same, so `JSON.generate(alert.to_h)` needs
+      # nothing from this library and `Alert.from_h(JSON.parse(json))` rebuilds
+      # exactly this object.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def to_h
+        {
+          subject: subject.to_h,
+          change: change,
+          fields: fields,
+          result: result&.to_h,
+          previous_result: previous_result&.to_h,
+          snapshot_id: snapshot_id,
+          previous_snapshot_id: previous_snapshot_id
+        }
+      end
+
+      # One line, for the summary a human reads:
+      #
+      #   cust_1  newly listed  un_consolidated:6908021  BOSCO TAGANDA  94.1 (was 71.0)
+      sig { returns(String) }
+      def to_s
+        "#{subject_id}  #{change.to_s.tr("_", " ")}  #{entity_id}  #{evidence.matched_name.value}  #{movement}"
+      end
+
+      sig { params(other: T.untyped).returns(T::Boolean) }
+      def ==(other)
+        return false unless other.instance_of?(self.class)
+
+        to_h == other.to_h
+      end
+      alias eql? ==
+
+      sig { returns(Integer) }
+      def hash = [self.class, to_h].hash
+
+      sig { returns(String) }
+      def inspect = "#<#{self.class} #{self}>"
+
+      private
+
+      # What the score did, which is the sentence an analyst reads first. A
+      # side that does not exist prints as the listing event it was.
+      sig { returns(String) }
+      def movement
+        return "#{previous_score} -> delisted" if result.nil?
+        return score.to_s if previous_result.nil?
+        return "#{score} (unchanged)" if score == previous_score
+
+        "#{previous_score} -> #{score}"
+      end
+
+      sig { params(member: Symbol, klass: T.untyped, value: T.untyped).returns(T.untyped) }
+      def instance!(member, klass, value)
+        return value if value.is_a?(klass)
+
+        raise InvalidArgument, "#{member} must be an #{klass}, got #{value.class}"
+      end
+
+      sig { params(member: Symbol, value: T.untyped).returns(T.nilable(MatchResult)) }
+      def result!(member, value) = value.nil? ? nil : instance!(member, MatchResult, value)
+
+      # An alert with neither side is not a change: nothing was scored, and
+      # there is no record for it to be about.
+      sig { void }
+      def sides!
+        return unless result.nil? && previous_result.nil?
+
+        raise InvalidArgument,
+              "an alert needs a result on at least one side of the change -- one that scored against neither " \
+              "list version is not a change, and cannot say what it is about"
+      end
+
+      sig { params(value: T.untyped).returns(Symbol) }
+      def change!(value)
+        symbol = value.to_s.to_sym
+        return symbol if CHANGES.include?(symbol)
+
+        raise InvalidArgument, "unknown change #{value.inspect}, expected one of #{CHANGES.join(", ")}"
+      end
+
+      sig { params(member: Symbol, value: T.untyped).returns(String) }
+      def string!(member, value)
+        string = value.to_s.strip
+        raise InvalidArgument, "#{member} is required -- an alert cites both list versions it compared" if string.empty?
+
+        -string
+      end
+    end
+  end
+end