active_sanction 1.0.0

data/lib/active_sanction/http_client.rb

@@ -0,0 +1,324 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "fileutils"
+require "net/http"
+require "uri"
+require "active_sanction/error"
+require "active_sanction/configuration"
+require "active_sanction/http_client/errors"
+require "active_sanction/http_client/response"
+
+module ActiveSanction
+  # A small GET client over `net/http`, built for one job: pulling published
+  # sanctions files off government servers.
+  #
+  #   client = ActiveSanction::HttpClient.new
+  #   client.get("https://sanctionslistservice.ofac.treas.gov/api/download/SDN.CSV").body
+  #   client.download("https://.../SDN_ADVANCED.XML", to: "/tmp/sdn_advanced.xml")
+  #
+  # No HTTP gem: the stdlib covers every need here, and the gem's zero-runtime-
+  # dependency promise is worth more to an application embedding it than the
+  # ergonomics of a nicer adapter layer would be.
+  #
+  # What the endpoints force on us, all verified live:
+  #
+  # * **OFAC returns 403 to a request with no User-Agent**, so the header is
+  #   mandatory rather than defaulted-and-forgotten, and a blank one raises
+  #   before a socket is opened.
+  # * **OFAC's download URLs 302 to blob storage**, so following redirects is
+  #   part of a working GET, not an option a caller might switch on.
+  # * **SDN_ADVANCED.XML is 126 MB**, so #download streams to disk. Holding a
+  #   list that size in a String to write it out again is how a sync job gets
+  #   itself OOM-killed in a container.
+  #
+  # Bodies come back as the server sent them, with no transcoding: OFAC's CSV
+  # and the UN's XML disagree about encoding, and guessing here would corrupt
+  # one of them. Parsers (#14, #15) declare what they expect.
+  #
+  # @api private
+  class HttpClient
+    extend T::Sig
+
+    # 303 is included even though it is defined to change the method, because
+    # this client only ever issues GET and so already complies.
+    #
+    # @api private
+    REDIRECT_STATUSES = T.let([301, 302, 303, 307, 308].freeze, T::Array[Integer])
+
+    # Failures worth trying again. A 4xx is never in here: a 403 for a missing
+    # User-Agent or a 404 for a retired URL says the request is wrong, and
+    # repeating it wastes the publisher's capacity to make the same point.
+    #
+    # OpenSSL errors are deliberately absent: a certificate that does not
+    # verify will not verify a second later either, and quietly retrying a TLS
+    # failure against a government endpoint is not a behaviour worth having.
+    # See FATAL_ERRORS, which is where they go instead.
+    #
+    # @api private
+    TRANSIENT_ERRORS = T.let(
+      [
+        EOFError, IOError, SocketError, Net::HTTPBadResponse, Net::ProtocolError,
+        Errno::ECONNABORTED, Errno::ECONNREFUSED, Errno::ECONNRESET,
+        Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::EPIPE, Errno::ETIMEDOUT
+      ].freeze,
+      T::Array[T.class_of(StandardError)]
+    )
+
+    # Failures translated on the first attempt rather than retried. A caller
+    # rescuing FetchError should not have to know that this client speaks
+    # `net/http`, and it certainly should not have to know that `net/http`
+    # speaks OpenSSL -- but a bad certificate is still not worth a second
+    # request, so it becomes a ConnectionError that says `retryable?` is false.
+    #
+    # Guarded because `net/http` loads OpenSSL optionally, and a Ruby built
+    # without it can still fetch a list over plain HTTP.
+    #
+    # @api private
+    FATAL_ERRORS = T.let(
+      (defined?(::OpenSSL::SSL::SSLError) ? [::OpenSSL::SSL::SSLError] : []).freeze,
+      T::Array[T.class_of(StandardError)]
+    )
+
+    # Checked when the client is built, so a blank one raises before a socket
+    # is opened rather than earning a 403 from OFAC.
+    sig { returns(String) }
+    attr_reader :user_agent
+
+    sig { returns(Numeric) }
+    attr_reader :open_timeout
+
+    sig { returns(Numeric) }
+    attr_reader :read_timeout
+
+    sig { returns(Integer) }
+    attr_reader :max_redirects
+
+    sig { returns(Integer) }
+    attr_reader :max_retries
+
+    sig { returns(Numeric) }
+    attr_reader :retry_backoff
+
+    # Settings default to the global configuration, read at construction, so a
+    # client built inside a source adapter honours whatever the host
+    # application set at boot without threading a config object through every
+    # adapter.
+    sig do
+      params(user_agent: T.untyped, open_timeout: Numeric, read_timeout: Numeric, max_redirects: Integer,
+             max_retries: Integer, retry_backoff: Numeric).void
+    end
+    def initialize(user_agent: ActiveSanction.config.user_agent,
+                   open_timeout: ActiveSanction.config.open_timeout,
+                   read_timeout: ActiveSanction.config.read_timeout,
+                   max_redirects: ActiveSanction.config.max_redirects,
+                   max_retries: ActiveSanction.config.max_retries,
+                   retry_backoff: ActiveSanction.config.retry_backoff)
+      @user_agent = T.let(Configuration.user_agent!(user_agent), String)
+      @open_timeout = T.let(open_timeout, Numeric)
+      @read_timeout = T.let(read_timeout, Numeric)
+      @max_redirects = T.let(max_redirects, Integer)
+      @max_retries = T.let(max_retries, Integer)
+      @retry_backoff = T.let(retry_backoff, Numeric)
+    end
+
+    # Fetches a URL and buffers the body in memory. Right for the index pages
+    # and small XML lists; use #download for anything list-sized.
+    sig { params(url: T.untyped, headers: T::Hash[T.untyped, T.untyped]).returns(Response) }
+    def get(url, headers: {})
+      fetch(url, headers: headers)
+    end
+
+    # Streams a URL to disk, returning a Response whose body is nil -- the
+    # bytes are in the file, and materializing them twice defeats the point.
+    #
+    # `to:` is a path, or any IO-ish object that responds to #write, which is
+    # what the payload cache (#11) passes so it can own its own atomicity.
+    # Given a path, the download lands on a sibling `.part` file and is renamed
+    # only once the server has answered 2xx, so an interrupted or 404'd fetch
+    # never leaves something at the destination that looks like a list.
+    sig { params(url: T.untyped, to: T.untyped, headers: T::Hash[T.untyped, T.untyped]).returns(Response) }
+    def download(url, to:, headers: {})
+      return fetch(url, headers: headers, sink: to) if to.respond_to?(:write)
+
+      stream_to_path(url, to.to_s, headers)
+    end
+
+    private
+
+    sig { params(url: T.untyped, path: String, headers: T::Hash[T.untyped, T.untyped]).returns(Response) }
+    def stream_to_path(url, path, headers)
+      partial = "#{path}.part"
+      response = T.let(File.open(partial, "wb") { |file| fetch(url, headers: headers, sink: file) }, Response)
+      File.rename(partial, path) if response.success?
+      response
+    ensure
+      # `T.must` because Sorbet reads an `ensure` as reachable before the first
+      # assignment in the body; `partial` is that assignment.
+      FileUtils.rm_f(T.must(partial))
+    end
+
+    # One hop at a time: each is retried on its own, so a 500 from the blob
+    # store the second hop landed on does not replay the first.
+    sig { params(url: T.untyped, headers: T::Hash[T.untyped, T.untyped], sink: T.untyped).returns(Response) }
+    def fetch(url, headers:, sink: nil)
+      uri = uri!(url)
+      request_headers = headers!(headers)
+      seen = [uri.to_s]
+      redirects = []
+
+      loop do
+        response = with_retries(uri) { perform(uri, request_headers, sink, redirects) }
+        return response unless response.redirect? && response["location"]
+
+        redirects << uri
+        raise TooManyRedirects, chain_message(redirects) if redirects.size > max_redirects
+
+        uri = next_hop(uri, response["location"], seen)
+      end
+    end
+
+    sig do
+      params(uri: URI::Generic, headers: T::Hash[String, String], sink: T.untyped,
+             redirects: T::Array[URI::Generic]).returns(Response)
+    end
+    def perform(uri, headers, sink, redirects)
+      response = T.let(nil, T.nilable(Response))
+      build_http(uri).start do |session|
+        session.request(Net::HTTP::Get.new(uri, headers)) do |raw|
+          response = receive(raw, uri, sink, redirects)
+        end
+      end
+      T.must(response)
+    end
+
+    # Only a successful body is streamed. An error page is small and the caller
+    # will want to read it, and writing one into the sink would hand the
+    # payload cache a 404 notice to checksum as though it were a list.
+    #
+    # A 304 is the one status with nothing to read either way: it is defined to
+    # carry no body, and handing back the empty string `read_body` produces
+    # would give conditional GET (#10) something a caller could try to parse.
+    sig do
+      params(raw: T.untyped, uri: URI::Generic, sink: T.untyped,
+             redirects: T::Array[URI::Generic]).returns(Response)
+    end
+    def receive(raw, uri, sink, redirects)
+      status = raw.code.to_i
+      body = T.let(nil, T.nilable(String))
+      if status == 304
+        nil
+      elsif sink && status.between?(200, 299)
+        rewind(sink)
+        raw.read_body { |chunk| sink.write(chunk) }
+      else
+        body = raw.read_body
+      end
+      Response.new(status: status, headers: raw.to_hash, uri: uri, body: body, redirects: redirects)
+    end
+
+    # A read that dies mid-body has already written part of the file, so a
+    # retry has to start the sink over rather than append a second prefix to
+    # the first. An append-only sink cannot be reset; it is the caller's to
+    # handle, and #download's own path never produces one.
+    sig { params(sink: T.untyped).void }
+    def rewind(sink)
+      return unless sink.respond_to?(:truncate) && sink.respond_to?(:rewind)
+
+      sink.rewind
+      sink.truncate(0)
+    end
+
+    # Exponential backoff, no jitter: this is one process fetching a handful of
+    # files on a schedule, not a fleet that needs de-synchronizing, and a
+    # deterministic delay is one less thing for a stuck sync to explain.
+    sig { params(uri: URI::Generic, block: T.proc.returns(Response)).returns(Response) }
+    def with_retries(uri, &block)
+      attempt = 0
+      loop do
+        attempt += 1
+        begin
+          response = block.call
+          return response unless retry_status?(response, attempt)
+        rescue *FATAL_ERRORS => e
+          raise ConnectionError.new(failure_message(uri, e, attempt), retryable: false)
+        rescue Timeout::Error => e
+          raise TimeoutError, failure_message(uri, e, attempt) unless attempt <= max_retries
+        rescue *TRANSIENT_ERRORS => e
+          raise ConnectionError, failure_message(uri, e, attempt) unless attempt <= max_retries
+        end
+        sleep(backoff_for(attempt))
+      end
+    end
+
+    sig { params(response: Response, attempt: Integer).returns(T::Boolean) }
+    def retry_status?(response, attempt)
+      response.server_error? && attempt <= max_retries
+    end
+
+    sig { params(attempt: Integer).returns(Numeric) }
+    def backoff_for(attempt)
+      retry_backoff * (2**(attempt - 1))
+    end
+
+    sig { params(uri: URI::Generic).returns(Net::HTTP) }
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = open_timeout
+      http.read_timeout = read_timeout
+      http
+    end
+
+    # The configured agent unless the caller overrode it, compared case-
+    # insensitively because HTTP header names are. Validating the merged value
+    # rather than only the configured one is what makes the guarantee real: the
+    # request that goes out is the one checked, and it is checked here, before
+    # a socket is opened.
+    sig { params(extra: T.untyped).returns(T::Hash[String, String]) }
+    def headers!(extra)
+      headers = extra.to_h.to_h { |name, value| [name.to_s, value.to_s] }
+      key = headers.keys.find { |name| name.casecmp?("user-agent") }
+      agent = key ? headers[key] : user_agent
+      Configuration.user_agent!(agent)
+      headers.delete(key) if key
+      headers.merge("User-Agent" => agent)
+    end
+
+    sig { params(url: T.untyped).returns(URI::Generic) }
+    def uri!(url)
+      uri = url.is_a?(URI::Generic) ? url : URI.parse(url.to_s)
+      raise InvalidArgument, "#{url.inspect} is not an http(s) URL" unless uri.is_a?(URI::HTTP) && uri.host
+
+      uri
+    rescue URI::InvalidURIError => e
+      raise InvalidArgument, "#{url.inspect} is not a URL: #{e.message}"
+    end
+
+    # `Location` is allowed to be relative, and publishers use that, so it is
+    # resolved against the URL that produced it rather than parsed alone.
+    sig { params(from: URI::Generic, location: T.untyped, seen: T::Array[String]).returns(URI::Generic) }
+    def next_hop(from, location, seen)
+      target = URI.join(from, location)
+      raise InvalidRedirect, "#{from} redirected to #{location.inspect}" unless target.is_a?(URI::HTTP) && target.host
+      raise RedirectLoop, "#{from} redirected back to #{target}" if seen.include?(target.to_s)
+
+      seen << target.to_s
+      target
+    rescue URI::Error => e
+      raise InvalidRedirect, "#{from} redirected to an unusable location #{location.inspect}: #{e.message}"
+    end
+
+    sig { params(redirects: T::Array[URI::Generic]).returns(String) }
+    def chain_message(redirects)
+      "#{redirects.first} exceeded #{max_redirects} redirects: #{redirects.join(" -> ")}"
+    end
+
+    sig { params(uri: URI::Generic, error: Exception, attempts: Integer).returns(String) }
+    def failure_message(uri, error, attempts)
+      "GET #{uri} failed after #{attempts} attempt#{"s" unless attempts == 1}: #{error.class}: #{error.message}"
+    end
+  end
+end

data/lib/active_sanction/identifier.rb

@@ -0,0 +1,212 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/partial_date"
+
+module ActiveSanction
+  # A document number a sanctions list published for an entity: passport,
+  # national ID, tax number, company registration. It is the highest-value
+  # signal the matcher has -- an exact passport match is near-decisive in the
+  # scorer (#32), where a name match never is.
+  #
+  #   ActiveSanction::Identifier.new(
+  #     kind:       :passport,
+  #     value:      "AB-123 456",
+  #     country:    "Egypt",
+  #     issued_on:  PartialDate.parse("2004-06-01"),
+  #     expires_on: PartialDate.parse("2009-05-31"),
+  #     note:       "expired"
+  #   )
+  #
+  # `value` is the one required field: an identifier with no number is not an
+  # identifier. Everything else is optional, because OFAC's remarks often give
+  # just `Passport 123456 (Egypt)` and nothing more.
+  #
+  # The published string is kept verbatim -- it is what gets shown back to a
+  # user justifying a hit -- while comparison runs on #normalized_value, since
+  # two governments transcribing one passport rarely agree on its punctuation.
+  # Instances are frozen on construction and compare by value.
+  class Identifier
+    extend T::Sig
+
+    # The UN publishes TYPE_OF_DOCUMENT as free text ("Passport", "National
+    # Identification Number"), so adapters map onto these rather than passing a
+    # source's own vocabulary through. :other is a real answer, not a failure:
+    # a document we cannot classify still matches on its number.
+    KINDS = T.let(%i[passport national_id tax_id registration_number other].freeze, T::Array[Symbol])
+
+    # Canonical member order. Snapshot (#8) checksums the serialized form, so
+    # #to_h must lay its keys out the same way every time. `normalized_value`
+    # is derived rather than stored: a stored copy can disagree with the value
+    # it describes, and then two records that mean the same thing checksum
+    # apart.
+    #
+    # @api private
+    MEMBERS = T.let(%i[kind value country issued_on expires_on note].freeze, T::Array[Symbol])
+
+    # Everything a number is not: spaces, hyphens, slashes, dots. OFAC writes
+    # `AB-123 456` where the UN writes `AB123456`, and neither is more correct.
+    #
+    # @api private
+    INSIGNIFICANT = T.let(/[^[:alnum:]]+/, Regexp)
+
+    sig { returns(Symbol) }
+    attr_reader :kind
+
+    # The published string, verbatim: it is what gets shown back to whoever has
+    # to justify a hit.
+    sig { returns(String) }
+    attr_reader :value
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :country
+
+    sig { returns(T.nilable(PartialDate)) }
+    attr_reader :issued_on
+
+    sig { returns(T.nilable(PartialDate)) }
+    attr_reader :expires_on
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :note
+
+    # What comparison actually runs on -- see #== below.
+    sig { returns(String) }
+    attr_reader :normalized_value
+
+    # Rebuilds an identifier from #to_h output. Accepts string keys, and dates
+    # as the hashes JSON leaves behind, so a record survives a round-trip
+    # through storage (#24) without a separate coercion step.
+    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 Identifier 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
+
+    # `kind` defaults to :other because a number we cannot classify is still
+    # worth matching on -- OFAC remarks carry plenty of them.
+    #
+    # Untyped on purpose, and the same choice Entity makes: all six are the
+    # publisher's own text arriving as whatever the parser made of it. The two
+    # dates additionally accept a PartialDate, a #to_h hash or anything
+    # PartialDate.parse reads -- see #date_or_nil.
+    sig do
+      params(value: T.untyped, kind: T.untyped, country: T.untyped, issued_on: T.untyped,
+             expires_on: T.untyped, note: T.untyped).void
+    end
+    def initialize(value:, kind: :other, country: nil, issued_on: nil, expires_on: nil, note: nil)
+      @value = T.let(value!(value), String)
+      @normalized_value = T.let(-@value.downcase.gsub(INSIGNIFICANT, ""), String)
+      @kind = T.let(kind!(kind), Symbol)
+      @country = T.let(string_or_nil(country), T.nilable(String))
+      @issued_on = T.let(date_or_nil(:issued_on, issued_on), T.nilable(PartialDate))
+      @expires_on = T.let(date_or_nil(:expires_on, expires_on), T.nilable(PartialDate))
+      @note = T.let(string_or_nil(note), T.nilable(String))
+      freeze
+    end
+
+    sig { returns(T::Boolean) }
+    def passport? = kind == :passport
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def to_h
+      {
+        kind: kind,
+        value: value,
+        country: country,
+        issued_on: issued_on&.to_h,
+        expires_on: expires_on&.to_h,
+        note: note
+      }
+    end
+
+    sig { returns(String) }
+    def to_s = value
+
+    # Equality is the comparison the acceptance criteria asks for: `AB-123 456`
+    # and `ab123456` are one passport written down twice, and de-duplicating
+    # the same document across OFAC and the UN depends on saying so. Dates and
+    # notes stay out of the key -- publishers report them inconsistently, and
+    # letting them split one document into two records would defeat the dedup
+    # this exists for. Entity (#4) still compares its members through #to_h, so
+    # nothing here hides a differing published string from a record diff.
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def ==(other)
+      return false unless other.instance_of?(self.class)
+
+      comparison_key == other.comparison_key
+    end
+    alias eql? ==
+
+    sig { returns(Integer) }
+    def hash
+      [self.class, comparison_key].hash
+    end
+
+    sig { returns(String) }
+    def inspect
+      "#<#{self.class} #{kind.inspect} #{value.inspect}#{" country=#{country.inspect}" if country}>"
+    end
+
+    protected
+
+    # Country is folded rather than dropped: two passports with the same number
+    # from different countries are different documents.
+    sig { returns([Symbol, String, T.nilable(String)]) }
+    def comparison_key
+      [kind, normalized_value, country&.downcase]
+    end
+
+    private
+
+    sig { params(value: T.untyped).returns(String) }
+    def value!(value)
+      string = value.to_s.strip
+      raise InvalidArgument, "value is required" if string.empty?
+      raise InvalidArgument, "value has no alphanumerics: #{string.inspect}" if string.gsub(INSIGNIFICANT, "").empty?
+
+      -string
+    end
+
+    # Case is folded before the lookup: sources capitalize their document types
+    # however they like, and no adapter should have to remember which.
+    sig { params(value: T.untyped).returns(Symbol) }
+    def kind!(value)
+      raise InvalidArgument, "kind is required" if value.nil? || value.to_s.empty?
+
+      symbol = value.to_s.downcase.to_sym
+      return symbol if KINDS.include?(symbol)
+
+      raise InvalidArgument, "unknown kind #{symbol.inspect}, expected one of #{KINDS.join(", ")}"
+    end
+
+    sig { params(value: T.untyped).returns(T.nilable(String)) }
+    def string_or_nil(value)
+      return nil if value.nil?
+
+      string = value.to_s.strip
+      string.empty? ? nil : -string
+    end
+
+    # Issue and expiry dates arrive as imprecisely as any other list date -- the
+    # UN publishes year-only expiries -- so they are PartialDates. Hashes and
+    # strings are coerced, which is what makes a JSON round-trip land where it
+    # started.
+    sig { params(member: Symbol, value: T.untyped).returns(T.nilable(PartialDate)) }
+    def date_or_nil(member, value)
+      case value
+      when nil, PartialDate then value
+      when Hash then PartialDate.from_h(value)
+      else PartialDate.parse(value) || raise(InvalidArgument, "#{member} is not a date: #{value.inspect}")
+      end
+    end
+  end
+end

data/lib/active_sanction/index/builder.rb

@@ -0,0 +1,89 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module ActiveSanction
+  class Index
+    # The mutable half of an immutable index.
+    #
+    # Index.build is the entry point; this exists so that the thing a web
+    # process shares between threads has no `add` on it at all. An index that
+    # could be appended to would be an index that has to be locked, and the
+    # whole design is that it is not -- see Index on the swap.
+    #
+    #   builder = ActiveSanction::Index::Builder.new
+    #   store.each_entity { |entity| builder.add(entity) }
+    #   index = builder.build
+    #
+    # A builder is single-threaded and single-use. Calling `build` twice
+    # returns two indexes over the same entries, which is harmless and not
+    # something anything needs.
+    class Builder
+      extend T::Sig
+
+      sig { void.checked(:tests) }
+      def initialize
+        @entries = T.let([], T::Array[Entry])
+        @tokens = T.let({}, T::Hash[String, T::Array[Integer]])
+        @trigrams = T.let({}, T::Hash[String, T::Array[Integer]])
+        @phonetics = T.let({}, T::Hash[String, T::Array[Integer]])
+      end
+
+      # Every name the entity carries, folded under its type and posted to the
+      # three feature spaces.
+      #
+      # Two names are skipped, and both are skips rather than errors because a
+      # government file is not something a build gets to reject:
+      #
+      # **A name that folds to nothing.** Punctuation, an emoji, a row of
+      # dashes -- Form#empty? exists for these. Such a name cannot be scored,
+      # so indexing it would only produce candidates no comparison can rank.
+      #
+      # **A name that folds onto one this entity already has.** OFAC publishes
+      # `MUÑOZ HERMANOS S.A.` and `MUNOZ HERMANOS` on one record, and after
+      # the fold they are the same string. Keeping both would post the same
+      # entity twice under every one of its features, which costs memory on
+      # the way in and hands the scorer the same comparison twice on the way
+      # out. The publisher's own spelling is not lost: the first one to arrive
+      # keeps its Name, and that is what a hit is reported in.
+      sig { params(entity: Entity).returns(T.self_type).checked(:tests) }
+      def add(entity)
+        folded = T.let({}, T::Hash[String, TrueClass])
+        entity.names.each do |name|
+          form = Normalizer.call(name.value, type: entity.type)
+          next if form.empty? || folded.key?(form.value)
+
+          folded[form.value] = true
+          index(Entry.new(id: @entries.size, entity: entity, name: name, form: form))
+        end
+        self
+      end
+
+      # The finished index. Everything it holds is frozen on the way in.
+      sig { returns(Index).checked(:tests) }
+      def build
+        Index.new(entries: @entries, tokens: @tokens, trigrams: @trigrams, phonetics: @phonetics)
+      end
+
+      private
+
+      sig { params(entry: Entry).void }
+      def index(entry)
+        @entries << entry
+        post(@tokens, Features.tokens(entry.form), entry.id)
+        post(@trigrams, Features.trigrams(entry.form), entry.id)
+        post(@phonetics, Features.phonetics(entry.form), entry.id)
+      end
+
+      # Ids arrive in ascending order because they are assigned in the order
+      # entries are made, so a posting list is sorted without ever being
+      # sorted. Query relies on that only for determinism; nothing binary
+      # searches these.
+      sig { params(postings: T::Hash[String, T::Array[Integer]], features: T::Array[String], id: Integer).void }
+      def post(postings, features, id)
+        features.each { |feature| (postings[feature] ||= []) << id }
+      end
+    end
+  end
+end

data/lib/active_sanction/index/candidate.rb

@@ -0,0 +1,63 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module ActiveSanction
+  class Index
+    # A name the index thinks is worth comparing, and how strongly it thought
+    # so.
+    #
+    #   candidate.name.value  # => "ABBAS, Abu"
+    #   candidate.form.value  # => "abbas abu"
+    #   candidate.weight      # => 14.82
+    #
+    # ### `weight` is not a score
+    #
+    # It is the sum of what the query and this name have in common, each
+    # shared feature counted by how rare it is -- see Index for the arithmetic.
+    # It says how confident the retrieval was, in a unit with no upper bound
+    # and no meaning outside the corpus it was computed against: a long name
+    # with rare tokens outranks a short one with common tokens before either
+    # has been compared to anything.
+    #
+    # So it is not comparable with the 0..100 a MatchResult (#33) carries, it
+    # is not a threshold anybody should set, and it must never reach a
+    # compliance user. Its one job is ordering the cap -- when more names
+    # match than the caller asked for, this decides which are dropped -- and
+    # it is exposed rather than hidden because that decision is the one thing
+    # about this stage that can silently cost a true match, and a caller
+    # investigating why a name was missed needs to see where it fell.
+    class Candidate
+      extend T::Sig
+
+      sig { returns(Entry).checked(:tests) }
+      attr_reader :entry
+
+      sig { returns(Float).checked(:tests) }
+      attr_reader :weight
+
+      sig { params(entry: Entry, weight: Float).void.checked(:tests) }
+      def initialize(entry:, weight:)
+        @entry = entry
+        @weight = weight
+        freeze
+      end
+
+      sig { returns(Entity).checked(:tests) }
+      def entity = entry.entity
+
+      sig { returns(Name).checked(:tests) }
+      def name = entry.name
+
+      sig { returns(Normalizer::Form).checked(:tests) }
+      def form = entry.form
+
+      sig { returns(Symbol).checked(:tests) }
+      def source = entry.source
+
+      sig { returns(String) }
+      def inspect = "#<#{self.class} #{name.value.inspect} weight=#{weight.round(2)}>"
+    end
+  end
+end