active_sanction 1.0.0

data/lib/active_sanction/scorer.rb

@@ -0,0 +1,303 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module ActiveSanction
+  # Turns a candidate into an explainable score. Stage 4 of the matching
+  # pipeline, and the component that decides whether this library is
+  # trustworthy.
+  #
+  #   subject = ActiveSanction::Scorer::Subject.new(
+  #     name: "Abu Abbas", type: :individual, dates_of_birth: "1948", nationalities: %w[RU]
+  #   )
+  #
+  #   result = ActiveSanction::Scorer.call(subject, entity)
+  #   result.score        # => 87.4
+  #   result.name.value   # => "ABBAS, Abu"
+  #   result.explanation
+  #   # => [#<Reason +91.2 name: matched primary name 'ABBAS, Abu'>,
+  #   #     #<Reason  +6.0 dob: date of birth 1948 overlaps listed 1948-12-10>,
+  #   #     #<Reason -12.0 nationality: query RU vs listed EG>]
+  #
+  #   ActiveSanction::Scorer.call(subject, index.candidates("Abu Abbas").first)
+  #
+  # Everything upstream narrows: the normalizer (#26) makes two names
+  # comparable, the index (#31) says which are worth comparing, and Similarity
+  # (#28, #29) and Phonetics (#30) each answer one question about a pair. This
+  # stage is the only one that says *how much a match is worth*, and the only
+  # one whose output a person has to act on.
+  #
+  # ### An entity's score is the best of its names
+  #
+  # Matching any single alias is a hit. OFAC ships 20,147 aliases against
+  # 19,321 primary names and the UN publishes as many as a dozen spellings of
+  # one person, so a score that averaged over an entity's names would punish
+  # the records that describe themselves most thoroughly -- and a score that
+  # only read the primary name would miss most of what these lists are for.
+  #
+  # So every name is scored and the best one wins, and the winner is on the
+  # Result: a report has to be able to say which spelling produced the hit.
+  #
+  # The low-quality penalty is applied *before* the maximum rather than to the
+  # winner afterwards, which is the difference between two readings of the
+  # same rule. The UN grades some aliases `Low`, meaning the Committee itself
+  # is unsure the person is known by that name; a good name scoring 85 should
+  # beat a low-quality one scoring 90, and it only does if the penalty is part
+  # of what the maximum is taken over.
+  #
+  # A former name (`fka`) is not penalized. It is a name the person really
+  # used, and a screening tool that discounted it would be discounting exactly
+  # the alias someone changes their name to escape.
+  #
+  # ### An entity of the wrong type is not scored at all
+  #
+  # A subject that says `:individual` is never compared to a vessel, whatever
+  # the names look like. `NORTHERN STAR` is a ship and a person and the
+  # difference is not a matter of degree -- there is no score at which a
+  # compliance officer wants a ship in a list of people -- so this is a filter
+  # and not a penalty, and `call` returns nil.
+  #
+  # Vessels and aircraft are ~10% of the SDN list and carry name-like strings,
+  # which is why Entity has the types at all. A subject that gives no type is
+  # asking a different question and is scored against everything.
+  #
+  # ### Deterministic, to the last decimal
+  #
+  # The same subject and the same entity produce the same score and the same
+  # explanation on every run, in every process. That is not a nicety: a
+  # screening decision is re-derived during an audit months later, and a score
+  # that moved by a tenth because a Hash iterated differently is a decision
+  # nobody can defend.
+  #
+  # What that costs is small and worth naming, because each piece of it is a
+  # place the property could be lost. Names are scored in the order the
+  # publisher listed them and ties go to the first, so an entity carrying the
+  # same spelling twice does not depend on which copy was seen first. The
+  # adjustments run in a fixed order -- see Adjustments -- and each picks its
+  # pairing by iteration order rather than by anything sorted on a Float.
+  # Rounding happens once, in Reason, and the score is the sum of the rounded
+  # contributions rather than the rounded sum.
+  #
+  # ### `threshold:` is how a screening call fits in its budget
+  #
+  # This stage is nearly all of what a screening call costs -- a few hundred
+  # candidates, four string algorithms and a phonetic pass on each -- and
+  # scoring them exactly costs about 46 ms under YJIT where scoring them to a
+  # threshold of 75 costs about 16. The difference is not an approximation:
+  # everything a threshold turns off is a comparison whose result could not
+  # have changed the answer, and a result at or above the cutoff is exactly
+  # the result the same call without one returns. See NameScore for the
+  # arithmetic and `rake benchmark:scorer` for the sweep.
+  #
+  # So the caller in front of this should always pass one. A matcher that
+  # screens without a threshold spends three times its budget computing exact
+  # scores for candidates it is about to discard.
+  #
+  # It is applied to the whole score rather than to the name, which matters:
+  # a subject carrying the right passport number needs forty points less of a
+  # name than one carrying nothing, and a threshold applied to the name alone
+  # would drop exactly the hits the identifiers exist to find.
+  #
+  # ### Weights
+  #
+  # Every number this stage uses is in Weights, with a default and the reason
+  # for it. A host that disagrees passes its own, per call or in
+  # configuration:
+  #
+  #   ActiveSanction.configure { |c| c.scorer_weights = { dob_conflict: -20.0 } }
+  #
+  # Changing them changes what a past decision would score today, so a stored
+  # decision records the weights it was made under -- which is #33's job, and
+  # the reason this stage takes them as an argument rather than reading a
+  # global halfway down a call stack.
+  module Scorer
+    extend T::Sig
+    extend T::Helpers
+
+    # Called as `Scorer.threshold!`, which is where `raise` comes from.
+    requires_ancestor { Kernel }
+
+    # The scale everything here works in. Similarity is 0..1; the conversion
+    # happens once, in NameScore.
+    #
+    # @api private
+    SCALE = T.let(100.0, Float)
+
+    module_function
+
+    # The best score this entity can make against this subject, or nil when
+    # there is nothing to score: an entity of the wrong type, or one whose
+    # every name folds away to nothing.
+    #
+    # Takes an Entity or an Index::Candidate, since the caller in front of
+    # this holds candidates and the caller in a console holds entities.
+    #
+    # `weights:` defaults to the configured set. It is read once per call
+    # rather than per name, so a configuration changed mid-call cannot produce
+    # a score that is half one set of weights and half another.
+    #
+    # `threshold:` is on the same 0..100 scale as the score. A result at or
+    # above it is exactly the result the same call without one returns; below
+    # it, nil. See the note on cost below for what it buys and why the caller
+    # in front of this should always pass one.
+    sig do
+      params(subject: Subject, candidate: T.untyped, weights: T.untyped, threshold: Numeric)
+        .returns(T.nilable(Result)).checked(:tests)
+    end
+    def call(subject, candidate, weights: nil, threshold: 0.0)
+      entity = candidate.is_a?(Entity) ? candidate : candidate.entity
+      return nil unless comparable?(subject, entity)
+
+      settings = Weights.build(weights || ActiveSanction.config.scorer_weights)
+      cutoff = threshold!(threshold)
+      # The secondary identifiers first, though they are reported second: they
+      # cost no string comparison, and what they come to is what the name has
+      # to beat. A subject carrying the right passport number needs 40 points
+      # less of a name than one carrying nothing.
+      adjustments = Adjustments.call(subject, entity, settings)
+      best = best_name(subject, entity, settings, floor(cutoff, adjustments))
+      return nil if best.nil?
+
+      name, form, reasons = best
+      result = Result.new(entity: entity, name: name, form: form,
+                          explanation: bounded(reasons + adjustments))
+      result.score < cutoff ? nil : result
+    end
+
+    # The least a name can score and still leave the entity able to reach the
+    # cutoff, given what the identifiers already came to.
+    #
+    # A cutoff of nothing is nothing, and the guard is not cosmetic: a stack
+    # of penalties can put a total below zero, where the floor clamps it back
+    # up, so `cutoff - adjustments` would demand a name score of 47 to reach a
+    # threshold of 0 and quietly return no result at all.
+    sig { params(cutoff: Float, adjustments: T::Array[Reason]).returns(Float).checked(:tests) }
+    def floor(cutoff, adjustments)
+      return 0.0 unless cutoff.positive?
+
+      [cutoff - adjustments.sum(&:contribution), 0.0].max
+    end
+
+    # A threshold as a Float, or a QueryError.
+    #
+    # This is the boundary where the library changes units: everything below
+    # this stage is a similarity on a 0..1 scale and everything above it is a
+    # percentage. Similarity checks for the mistake in one direction -- an 85
+    # arriving where 0.85 was meant, which would reject every pair and read as
+    # "nothing matched" -- and this checks the other, an argument outside
+    # 0..100 at all.
+    #
+    # What it deliberately cannot catch is a `0.75` meant as three-quarters,
+    # because 0.75 is a legitimate threshold and there is no way to tell the
+    # two apart. That mistake is the survivable one: a threshold far too low
+    # returns everything the index found rather than nothing, which is noisy
+    # and visible. It is the opposite error that hides a hit.
+    sig { params(threshold: Numeric).returns(Float).checked(:tests) }
+    def threshold!(threshold)
+      cutoff = threshold.to_f
+      return cutoff if cutoff.between?(0.0, SCALE)
+
+      raise QueryError,
+            "threshold must be between 0 and 100, got #{threshold.inspect} -- " \
+            "a screening score is a percentage, not a similarity on a 0..1 scale"
+    end
+
+    # Whether this entity is the kind of thing the subject asked about. A
+    # subject with no type asks about everything.
+    sig { params(subject: Subject, entity: Entity).returns(T::Boolean).checked(:tests) }
+    def comparable?(subject, entity) = subject.type.nil? || subject.type == entity.type
+
+    # One of an entity's names, as far as this stage takes it: the published
+    # name, its folded form, and the reasons that name produced.
+    #
+    # @api private
+    Scored = T.type_alias { [Name, Normalizer::Form, T::Array[Reason]] }
+
+    # Whichever of the entity's names scores highest once its own quality
+    # penalty is applied, or nil when none of them survives the fold or
+    # reaches the threshold.
+    #
+    # Each name is scored against the best one found so far as well as against
+    # the caller's threshold, since only the best is going to be reported. On
+    # an entity with a dozen aliases that is most of the work skipped: the
+    # second name only has to be compared closely enough to establish that it
+    # does not beat the first.
+    #
+    # Equal is not better, so a tie stays with the name the publisher listed
+    # first -- see the note on determinism above.
+    sig do
+      params(subject: Subject, entity: Entity, weights: Weights, threshold: Float)
+        .returns(T.nilable(Scored)).checked(:tests)
+    end
+    def best_name(subject, entity, weights, threshold)
+      best = T.let(nil, T.nilable(Scored))
+      highest = T.let(-Float::INFINITY, Float)
+      entity.names.each do |name|
+        # A name that folds away to nothing cannot be compared -- see
+        # Normalizer::Form#empty?, and Index, which skips the same names.
+        form = Normalizer.call(name, type: entity.type)
+        next if form.empty?
+
+        penalty = name.low_quality? ? weights.low_quality_alias : 0.0
+        cutoff = [threshold, highest].max - penalty
+        score = NameScore.call(subject.form, form, weights, threshold: cutoff.clamp(0.0, SCALE))
+        # A zero under a real cutoff means "could not reach it", not "scored
+        # nothing" -- and the two have to be told apart before the comparison
+        # below, which would otherwise take a name that was never measured.
+        next if score.zero? && cutoff.positive?
+        next unless score + penalty > highest
+
+        highest = score + penalty
+        best = [name, form, reasons(name, score, penalty)]
+      end
+      best
+    end
+
+    # What one name is worth: the blended similarity, and the penalty for a
+    # name its own publisher graded unreliable.
+    sig do
+      params(name: Name, score: Float, penalty: Float).returns(T::Array[Reason]).checked(:tests)
+    end
+    def reasons(name, score, penalty)
+      reasons = [Reason.new(factor: :name, detail: matched(name), contribution: score)]
+      return reasons if penalty.zero?
+
+      reasons << Reason.new(factor: :alias_quality, contribution: penalty,
+                            detail: "#{name.value.inspect} is graded a low-quality alias by its publisher")
+    end
+
+    sig { params(name: Name).returns(String).checked(:tests) }
+    def matched(name)
+      kind = name.primary? ? "primary name" : "alias"
+      suffix = name.primary? ? "" : " (#{name.kind})"
+      "matched #{kind} #{name.value.inspect}#{suffix}"
+    end
+
+    # Keeps the score inside 0..100 without letting the explanation stop
+    # explaining it. A cap that silently swallowed 12 points would leave a
+    # reviewer adding a column of figures that does not reach the number
+    # printed above it, so the correction is itself a reason.
+    #
+    # It fires rarely -- a decisive identifier boost on an already-strong name
+    # is the usual way -- and when it does, the fact that a score reached its
+    # ceiling with points to spare is worth seeing.
+    sig { params(reasons: T::Array[Reason]).returns(T::Array[Reason]).checked(:tests) }
+    def bounded(reasons)
+      total = reasons.sum(&:contribution).round(Reason::PRECISION)
+      capped = total.clamp(0.0, SCALE)
+      return reasons if capped == total
+
+      reasons + [Reason.new(factor: :clamp, contribution: capped - total,
+                            detail: "#{total.round(Reason::PRECISION)} #{capped.zero? ? "raised" : "capped"} " \
+                                    "to #{capped}")]
+    end
+  end
+end
+
+require "active_sanction/scorer/weights"
+require "active_sanction/scorer/reason"
+require "active_sanction/scorer/subject"
+require "active_sanction/scorer/name_score"
+require "active_sanction/scorer/adjustments"
+require "active_sanction/scorer/result"

data/lib/active_sanction/similarity/jaro_winkler.rb

@@ -0,0 +1,210 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module ActiveSanction
+  module Similarity
+    # Jaro-Winkler similarity, 0..1.
+    #
+    #   ActiveSanction::Similarity::JaroWinkler.call("martha", "marhta")  # => 0.9611
+    #   ActiveSanction::Similarity::JaroWinkler.call("dixon", "dicksonx") # => 0.8133
+    #
+    # ### Why this one
+    #
+    # Jaro counts the characters two strings share within a window that widens
+    # with their length, and charges half an edit for each pair that matched
+    # out of order. That is a good model of how names are actually
+    # mistyped -- `MARHTA` for `MARTHA` is one transposition and two
+    # substitutions to Levenshtein, which scores it 0.667 against Jaro's 0.944.
+    #
+    # Winkler's addition is a bonus for a shared prefix, on the observation
+    # that people get the beginning of a name right and drift later. Names are
+    # the case that observation was drawn from and the case it holds best for:
+    # a transliterator's choice of vowel, a clerk's spelling of a suffix, and
+    # a truncated field all differ at the end.
+    #
+    # The prefix bonus is also the reason this is not the only scorer in the
+    # pipeline. It rewards `SMITH` against `SMITHSON`, and it has nothing at
+    # all to say about `ABBAS, Abu` against `Abu Abbas`, which shares no
+    # prefix and is the single most common query shape against these lists.
+    # TokenSort and TokenSet are what answer that.
+    module JaroWinkler
+      extend T::Sig
+
+      # Winkler's constants, and they are his: 0.1 with a four-character cap
+      # is what the 1990 paper used and what every published reference value
+      # is computed against. `p * l` cannot exceed 0.4, which is what keeps
+      # the bonus from pushing a score past 1.0.
+      PREFIX_SCALE = T.let(0.1, Float)
+      MAX_PREFIX = T.let(4, Integer)
+
+      # The bonus applies only to pairs that already look alike, which is
+      # Winkler's own rule and worth keeping for a reason this domain cares
+      # about: without it, every name beginning `MOHAMMED` is pulled toward
+      # every other one regardless of what follows, and a list where a quarter
+      # of the entries share a given name is exactly where that shows up as
+      # false positives.
+      BOOST_THRESHOLD = T.let(0.7, Float)
+
+      module_function
+
+      # The similarity of two already-folded strings -- see Similarity for
+      # what `threshold:` does and what it promises.
+      sig { params(left: String, right: String, threshold: Numeric).returns(Float).checked(:tests) }
+      def call(left, right, threshold: 0.0)
+        cutoff = Similarity.threshold!(threshold)
+        return 1.0 if left == right
+
+        left_codes = Similarity.codepoints(left)
+        right_codes = Similarity.codepoints(right)
+        return 0.0 if ceiling(left_codes.size, right_codes.size) < cutoff
+
+        score = winkler(left_codes, right_codes, jaro_score(left_codes, right_codes))
+        score < cutoff ? 0.0 : score
+      end
+
+      # The highest score two strings of these lengths can reach, whatever
+      # they contain. This is the early exit: a pair whose ceiling is under
+      # the caller's threshold is rejected without either string being looked
+      # at.
+      #
+      # At most `shorter` characters can match, so the two coverage terms are
+      # bounded by 1 and `shorter / longer` and the transposition term by 1;
+      # the prefix bonus on top can be no larger than a prefix of `shorter`
+      # allows. The bound is loose -- a 0.85 threshold only rejects a pair
+      # whose lengths differ by more than 4x, because the prefix bonus is
+      # generous about it -- and loose is the only safe direction. A ceiling
+      # that ever came in under a real score would drop true matches, so it is
+      # derived rather than tuned, and the specs hold it to that against every
+      # pair they can build.
+      sig { params(left_length: Integer, right_length: Integer).returns(Float).checked(:tests) }
+      def ceiling(left_length, right_length)
+        shorter = [left_length, right_length].min
+        longer = [left_length, right_length].max
+        return shorter == longer ? 1.0 : 0.0 if shorter.zero?
+
+        jaro = (2.0 + shorter.fdiv(longer)) / 3.0
+        jaro + ([shorter, MAX_PREFIX].min * PREFIX_SCALE * (1.0 - jaro))
+      end
+
+      # Jaro on its own, without the prefix bonus. Public because it is the
+      # published quantity -- a reference table gives both -- and because the
+      # scorer may yet want the unboosted number for a pair whose shared
+      # prefix is the part a caller has least confidence in.
+      sig { params(left: String, right: String).returns(Float).checked(:tests) }
+      def jaro(left, right)
+        return 1.0 if left == right
+
+        jaro_score(Similarity.codepoints(left), Similarity.codepoints(right))
+      end
+
+      # Codepoints in, for the reason Similarity.codepoints gives. `left` and
+      # `right` mean the same two names here as they do above; only the
+      # representation changes, and the signatures say which is which.
+      sig { params(left: T::Array[Integer], right: T::Array[Integer]).returns(Float).checked(:tests) }
+      def jaro_score(left, right)
+        return 0.0 if left.empty? || right.empty?
+
+        window = ([left.size, right.size].max / 2) - 1
+        window = 0 if window.negative?
+        left_matched, right_matched, matches = match(left, right, window)
+        return 0.0 if matches.zero?
+
+        halved = transpositions(left, right, left_matched, right_matched) / 2.0
+        (matches.fdiv(left.size) + matches.fdiv(right.size) + ((matches - halved) / matches)) / 3.0
+      end
+
+      # Which characters of each string found a partner in the other, and how
+      # many did.
+      #
+      # A character matches at most once, and only within `window` positions
+      # of where it sits in the other string -- that window is what makes this
+      # a similarity between two names rather than a bag-of-letters count, and
+      # what keeps `ORWELL` from scoring highly against `LLEWRO`.
+      sig do
+        params(left: T::Array[Integer], right: T::Array[Integer], window: Integer)
+          .returns([T::Array[T::Boolean], T::Array[T::Boolean], Integer])
+          .checked(:tests)
+      end
+      def match(left, right, window)
+        left_matched = Array.new(left.size, false)
+        right_matched = Array.new(right.size, false)
+        last = right.size - 1
+        matches = 0
+        left.each_with_index do |code, i|
+          low = i > window ? i - window : 0
+          j = partner(right, right_matched, code, low, [i + window, last].min)
+          next if j.nil?
+
+          left_matched[i] = true
+          right_matched[j] = true
+          matches += 1
+        end
+        [left_matched, right_matched, matches]
+      end
+
+      # The first position in `right[low..high]` holding `code` and not already
+      # spoken for, or nil. Leftmost, which is what makes the pairing
+      # deterministic: `call(x, y)` has to return the same number every time
+      # it is asked, because a screening decision is re-derived during an
+      # audit.
+      sig do
+        params(right: T::Array[Integer], matched: T::Array[T::Boolean], code: Integer, low: Integer, high: Integer)
+          .returns(T.nilable(Integer))
+          .checked(:tests)
+      end
+      def partner(right, matched, code, low, high)
+        j = low
+        while j <= high
+          return j if !matched[j] && right.fetch(j) == code
+
+          j += 1
+        end
+        nil
+      end
+
+      # Matched characters that came out in a different order on each side.
+      # Walking both sides in step, every position where the two disagree is
+      # half of a transposition, which is why the caller halves the count.
+      sig do
+        params(left: T::Array[Integer], right: T::Array[Integer],
+               left_matched: T::Array[T::Boolean], right_matched: T::Array[T::Boolean])
+          .returns(Integer)
+          .checked(:tests)
+      end
+      def transpositions(left, right, left_matched, right_matched)
+        count = 0
+        k = 0
+        left.each_with_index do |code, i|
+          next unless left_matched[i]
+
+          k += 1 until right_matched.fetch(k)
+          count += 1 unless code == right.fetch(k)
+          k += 1
+        end
+        count
+      end
+
+      # The prefix bonus.
+      sig do
+        params(left: T::Array[Integer], right: T::Array[Integer], jaro: Float).returns(Float).checked(:tests)
+      end
+      def winkler(left, right, jaro)
+        return jaro if jaro < BOOST_THRESHOLD
+
+        jaro + (prefix_length(left, right) * PREFIX_SCALE * (1.0 - jaro))
+      end
+
+      sig { params(left: T::Array[Integer], right: T::Array[Integer]).returns(Integer).checked(:tests) }
+      def prefix_length(left, right)
+        limit = [MAX_PREFIX, left.size, right.size].min
+        length = 0
+        length += 1 while length < limit && left.fetch(length) == right.fetch(length)
+        length
+      end
+
+      private_class_method :jaro_score, :match, :partner, :transpositions, :winkler, :prefix_length
+    end
+  end
+end

data/lib/active_sanction/similarity/levenshtein.rb

@@ -0,0 +1,179 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module ActiveSanction
+  module Similarity
+    # Levenshtein edit distance, and the similarity derived from it, 0..1.
+    #
+    #   ActiveSanction::Similarity::Levenshtein.distance("kitten", "sitting") # => 3
+    #   ActiveSanction::Similarity::Levenshtein.call("kitten", "sitting")     # => 0.5714
+    #
+    # ### Why this one, next to Jaro-Winkler
+    #
+    # It answers a different question. Jaro-Winkler asks how many characters
+    # two names share and how far out of order they are, and it is generous:
+    # it has no way to charge for a name that is simply longer than the other,
+    # and its prefix bonus is deliberately biased toward the front. Edit
+    # distance counts what it would actually take to turn one string into the
+    # other, which is the thing that stays honest when a name gains a whole
+    # word.
+    #
+    #   JaroWinkler.call("gazprom", "gazprombank")   # => 0.9273
+    #   Levenshtein.call("gazprom", "gazprombank")   # => 0.6364
+    #
+    # Two different companies, and the scorer (#32) blends the two numbers
+    # precisely so that neither algorithm's blind spot decides a hit on its
+    # own.
+    #
+    # ### Normalized by the longer string
+    #
+    # `1 - distance / longer.length`, so the result is comparable across name
+    # lengths and against Jaro-Winkler. Dividing by the longer of the two is
+    # what makes the measure symmetric and keeps it in 0..1: the distance can
+    # never exceed the longer length, and it equals it exactly when the two
+    # share nothing.
+    #
+    # ### What else runs on it
+    #
+    # Both token ratios. TokenSort is one call to this on a pair of names
+    # whose tokens have been put in alphabetical order, and TokenSet is three
+    # on a pair that has been split into what they share and what they do not,
+    # so half of stage 3 is this file with the strings rearranged first. See
+    # TokenSort for why the rearranging is not done on top of Jaro-Winkler.
+    module Levenshtein
+      extend T::Sig
+
+      module_function
+
+      # The similarity of two already-folded strings -- see Similarity for
+      # what `threshold:` does and what it promises.
+      sig { params(left: String, right: String, threshold: Numeric).returns(Float).checked(:tests) }
+      def call(left, right, threshold: 0.0)
+        cutoff = Similarity.threshold!(threshold)
+        return 1.0 if left == right
+
+        left_codes = Similarity.codepoints(left)
+        right_codes = Similarity.codepoints(right)
+        longer = [left_codes.size, right_codes.size].max
+        return 0.0 if ceiling(left_codes.size, right_codes.size) < cutoff
+
+        # An edit budget rather than a score: within the budget the score is
+        # at or above the threshold, and the rows stop the moment a row's
+        # smallest value passes it.
+        distance = rows(left_codes, right_codes, ((1.0 - cutoff) * longer).floor)
+        return 0.0 if distance.nil?
+
+        score = 1.0 - distance.fdiv(longer)
+        score < cutoff ? 0.0 : score
+      end
+
+      # The number of single-character insertions, deletions and substitutions
+      # that turn one string into the other. Exact, and public because it is
+      # the quantity people know: a caller who wants "within two typos"
+      # already knows what to compare against, and asking that of a 0..1 score
+      # means multiplying by a length.
+      sig { params(left: String, right: String).returns(Integer).checked(:tests) }
+      def distance(left, right)
+        return 0 if left == right
+
+        left_codes = Similarity.codepoints(left)
+        right_codes = Similarity.codepoints(right)
+
+        # No cell can exceed the longer length, so a budget of it never fires
+        # and the walk is exhaustive.
+        T.must(rows(left_codes, right_codes, [left_codes.size, right_codes.size].max))
+      end
+
+      # The highest score two strings of these lengths can reach, whatever
+      # they contain. This is the early exit: a pair whose ceiling is under
+      # the caller's threshold is rejected without either string being looked
+      # at, and without the matrix.
+      #
+      # Turning the shorter string into the longer one costs at least the
+      # difference in their lengths -- every missing character is an
+      # insertion, however well the rest lines up -- so the score can be no
+      # better than `shorter / longer`. Unlike Jaro-Winkler's ceiling this one
+      # is tight, and it bites: at a 0.85 threshold it rejects every pair
+      # whose lengths differ by more than 15%, which on these lists is most of
+      # the corpus for a given query.
+      sig { params(left_length: Integer, right_length: Integer).returns(Float).checked(:tests) }
+      def ceiling(left_length, right_length)
+        shorter = [left_length, right_length].min
+        longer = [left_length, right_length].max
+        return shorter == longer ? 1.0 : 0.0 if shorter.zero?
+
+        shorter.fdiv(longer)
+      end
+
+      # The matrix, one row at a time, or nil once no row can lead to a
+      # distance within `max`.
+      #
+      # Two rows rather than the full grid: a cell depends on the one above
+      # it, the one to its left, and the one diagonally above-left, so nothing
+      # older than the previous row is ever read again. The full matrix for a
+      # pair of 40-character names is 1,681 cells held for no reason, and the
+      # scorer runs this a few hundred times per query.
+      #
+      # The cutoff is what makes `threshold:` worth more than the length check
+      # in `ceiling`: row minima never decrease as the walk descends, so once
+      # a row's smallest value is past the budget, no later row and no final
+      # cell can come back under it.
+      sig do
+        params(left: T::Array[Integer], right: T::Array[Integer], max: Integer)
+          .returns(T.nilable(Integer))
+          .checked(:tests)
+      end
+      def rows(left, right, max)
+        previous = (0..right.size).to_a
+        current = Array.new(right.size + 1, 0)
+        left.each_with_index do |code, i|
+          current[0] = i + 1
+          return nil if fill(code, right, previous, current) > max
+
+          previous, current = current, previous
+        end
+        previous.fetch(right.size)
+      end
+
+      # One row, and the smallest value in it. Three of the four numbers a
+      # cell needs are already in hand -- the substitution and deletion costs
+      # come from the same two positions of the previous row, and the
+      # insertion cost is the cell just written -- so only one read of each
+      # row and one of the string happen per cell.
+      #
+      # `fetch` rather than `[]` for those: this is the innermost loop in the
+      # library, and Sorbet types `Array#[]` as nilable, so every read through
+      # it would carry a `T.must`, which is a Ruby-level method call per cell.
+      sig do
+        params(code: Integer, right: T::Array[Integer], previous: T::Array[Integer], current: T::Array[Integer])
+          .returns(Integer)
+          .checked(:tests)
+      end
+      def fill(code, right, previous, current)
+        # The cell to the left is the one just written and the cell
+        # diagonally above-left is the one that was above, so both are carried
+        # in locals rather than read back out of the rows.
+        left_cell = current.fetch(0)
+        smallest = left_cell
+        diagonal = previous.fetch(0)
+        width = right.size
+        j = 0
+        while j < width
+          above = previous.fetch(j + 1)
+          value = diagonal + (right.fetch(j) == code ? 0 : 1)          # substitution
+          value = above + 1 if above < value                           # deletion
+          value = left_cell + 1 if left_cell < value                   # insertion
+          diagonal = above
+          left_cell = current[j + 1] = value
+          smallest = value if value < smallest
+          j += 1
+        end
+        smallest
+      end
+
+      private_class_method :rows, :fill
+    end
+  end
+end