active_sanction 1.0.0

data/lib/active_sanction/sources/ofac/remarks_parser.rb

@@ -0,0 +1,312 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/identifier"
+require "active_sanction/name"
+require "active_sanction/partial_date"
+
+module ActiveSanction
+  module Sources
+    class Ofac < Base
+      # Reads the fields OFAC publishes no columns for out of the free text it
+      # packs them into.
+      #
+      #   parsed = RemarksParser.new("DOB 10 Dec 1948; POB Egypt; Passport 123456 (Egypt)")
+      #   parsed.dates_of_birth  # => [#<PartialDate 1948-12-10>]
+      #   parsed.places_of_birth # => ["Egypt"]
+      #   parsed.identifiers     # => [#<Identifier :passport "123456" country="Egypt">]
+      #   parsed.unrecognized    # => []
+      #
+      # SDN.CSV has no date of birth, place of birth, nationality or passport
+      # column. All of it -- 88,827 semicolon-delimited segments across 19,015
+      # remarks -- is prose in one field, written for a human reading a page.
+      # Until it is read, every OFAC entity carries names and nothing else, and
+      # names alone are what makes a screening tool cry wolf: the secondary
+      # identifiers that clear a false positive (#32) are all in here.
+      #
+      # ### Nothing is ever removed from the remark
+      #
+      # Extraction is additive. `Entity#remarks` keeps the publisher's whole
+      # string byte for byte whether this class understood it or not, so a
+      # pattern that drifts costs structure and never content. That is the one
+      # rule this file must not break: these are heuristics against text a
+      # government writes for people, they will go stale, and silent data loss
+      # in a compliance tool is the worst failure there is. A segment we cannot
+      # read is still in front of the user, in the publisher's own words.
+      #
+      # ### How a segment is read
+      #
+      # Segments are split on `;` and matched against a label vocabulary. A
+      # segment either extracts a value, or matches a shape known to be prose
+      # (`Secondary sanctions risk: ...`, which is 12% of the file and carries
+      # nothing structured), or is unrecognized -- and #unrecognized is what
+      # Coverage counts, so drift shows up as a number rather than as a bug
+      # report years later.
+      #
+      # Nothing here raises. A malformed segment -- `Passport issued in
+      # Sarajevo`, which names no passport at all -- reads as unrecognized and
+      # stays in the remark, because one unparseable clause must never cost the
+      # entity around it.
+      class RemarksParser
+        extend T::Sig
+
+        SEPARATOR = T.let(";", String)
+
+        # `alt.` prefixes a repeat: "DOB 1955; alt. DOB 1956" is one person two
+        # governments reported differently. It marks repetition and nothing
+        # else, so it is stripped and what follows is matched normally -- which
+        # is how multiple values of one kind fall out without a second rule.
+        ALTERNATE = T.let(/\Aalt\.\s+/i, Regexp)
+
+        # The full stop that ends a remark belongs to the sentence, not to the
+        # value: "Gender Male." is not a gender spelled with a period.
+        TRAILING_STOP = T.let(/\s*\.\z/, Regexp)
+
+        # OFAC publishes wallet addresses as `Digital Currency Address - XBT
+        # 1abc...`, one label per currency. They are matched by shape rather
+        # than enumerated: the list of currencies grows every time a new one is
+        # designated, and none of them changes how the address is read.
+        DIGITAL_CURRENCY = T.let(
+          /\ADigital Currency Address\s*-\s*(?<currency>[[:alnum:]]+)\s+(?<value>\S+)\z/i, Regexp
+        )
+
+        # The parenthesised qualifiers a document segment ends in: `Passport
+        # 123456 (Egypt)`, and sometimes two -- `Folio Mercantil No. 22839
+        # (Jalisco) (Mexico)` is a state and then a country. The space is what
+        # makes it a qualifier rather than part of the number: Hong Kong writes
+        # its ID numbers as `D489833(9)`, and splitting that off would leave a
+        # document number the issuing government would not recognize.
+        TRAILING_QUALIFIER = T.let(/\s+\(([^)]*)\)\s*\z/, Regexp)
+
+        # `Passport ZG4109521 (Pakistan) issued 07 Jun 2008 expires 06 Jun 2013`
+        # -- either clause may be absent and both may be present, so the value
+        # ends wherever the first one starts.
+        DATE_KEYWORDS = T.let(/\b(?:issued|expires|expired)\b/i, Regexp)
+        DATE_CLAUSE = T.let(/(issued|expires|expired)\s+(?:on\s+)?(.*?)(?=\s+#{DATE_KEYWORDS}|\z)/i, Regexp)
+
+        # A document number is a code, not a sentence. `Passport 265 216` and
+        # `SWIFT/BIC SBERRUMM` are numbers; `License to operate` is prose that
+        # happened to open with a label, and without this rule it would become
+        # an identifier that matches nothing and misleads everyone.
+        CODE = T.let(%r{\A[[:alnum:]][[:alnum:]\s._()/-]*\z}, Regexp)
+        DIGIT = T.let(/\d/, Regexp)
+
+        # No government issues a document number this long -- China's 18-digit
+        # social credit code is the longest in the file. What exceeds it is a
+        # clause that ran on: "Passport OR801168 and Kuwaiti National ID No.
+        # 281020505755 issued under the name ..." is one segment OFAC wrote as
+        # a sentence, and an identifier built from all of it would match
+        # nothing and mislead whoever read it.
+        MAX_CODE_LENGTH = T.let(40, Integer)
+
+        QUOTES = T.let(/\A['"“”‘’]|['"“”‘’]\z/, Regexp)
+
+        # The remark as published, and how this parser read it: every segment,
+        # those it extracted something from, those it recognized as prose, and
+        # those it could not read -- which is what Coverage counts.
+        sig { returns(String) }
+        attr_reader :text
+
+        sig { returns(T::Array[String]) }
+        attr_reader :segments
+
+        sig { returns(T::Array[String]) }
+        attr_reader :extracted
+
+        sig { returns(T::Array[String]) }
+        attr_reader :prose
+
+        sig { returns(T::Array[String]) }
+        attr_reader :unrecognized
+
+        sig { returns(T::Array[PartialDate]) }
+        attr_reader :dates_of_birth
+
+        sig { returns(T::Array[String]) }
+        attr_reader :places_of_birth
+
+        sig { returns(T::Array[String]) }
+        attr_reader :nationalities
+
+        sig { returns(T::Array[String]) }
+        attr_reader :genders
+
+        sig { returns(T::Array[Name]) }
+        attr_reader :aliases
+
+        sig { returns(T::Array[Identifier]) }
+        attr_reader :identifiers
+
+        sig { params(text: T.untyped).void }
+        def initialize(text)
+          @text = T.let(text.to_s, String)
+          @segments = T.let([], T::Array[String])
+          @extracted = T.let([], T::Array[String])
+          @prose = T.let([], T::Array[String])
+          @unrecognized = T.let([], T::Array[String])
+          @dates_of_birth = T.let([], T::Array[PartialDate])
+          @places_of_birth = T.let([], T::Array[String])
+          @nationalities = T.let([], T::Array[String])
+          @genders = T.let([], T::Array[String])
+          @aliases = T.let([], T::Array[Name])
+          @identifiers = T.let([], T::Array[Identifier])
+          read
+          freeze
+        end
+
+        # True when the remark yielded anything structured at all.
+        sig { returns(T::Boolean) }
+        def any? = extracted.any?
+
+        private
+
+        sig { void }
+        def read
+          text.split(SEPARATOR).each do |raw|
+            segment = raw.strip
+            next if segment.empty?
+
+            @segments << segment
+            classify(segment)
+          end
+        end
+
+        sig { params(segment: String).void }
+        def classify(segment)
+          body = segment.sub(ALTERNATE, "")
+          if field(body) || document(body) || digital_currency(body)
+            @extracted << segment
+          elsif Vocabulary::PROSE_PATTERN.match?(body)
+            @prose << segment
+          else
+            @unrecognized << segment
+          end
+        end
+
+        sig { params(body: String).returns(T.untyped) }
+        def field(body)
+          match = Vocabulary::FIELD_PATTERN.match(body)
+          return nil unless match
+
+          value = trim(match[:value])
+          return nil if value.nil?
+
+          case Vocabulary::FIELD_KINDS.fetch(T.must(match[:label]).downcase)
+          when :date_of_birth then born(value)
+          when :place_of_birth then keep(@places_of_birth, value)
+          when :nationality then keep(@nationalities, value)
+          when :gender then keep(@genders, value)
+          else known_as(Vocabulary::FIELD_KINDS.fetch(T.must(match[:label]).downcase), value)
+          end
+        end
+
+        # An unreadable date is not a date. It reads as unrecognized rather
+        # than as a nil the entity would carry around, which puts it in the
+        # coverage histogram where a new OFAC spelling can be seen.
+        sig { params(value: String).returns(T.untyped) }
+        def born(value)
+          date = PartialDate.parse(value)
+          return nil if date.nil?
+
+          keep(@dates_of_birth, date)
+        end
+
+        # `a.k.a. 'EL SENOR'` -- quoted, and the quotes are OFAC's punctuation
+        # rather than part of the name. 4,325 of the 4,349 inline aliases
+        # appear nowhere in ALT.CSV, so these are names the list publishes here
+        # and only here.
+        sig { params(kind: Symbol, value: String).returns(T.untyped) }
+        def known_as(kind, value)
+          keep(@aliases, Name.new(value: value.sub(QUOTES, "").sub(QUOTES, ""), kind: kind))
+        rescue ArgumentError
+          nil
+        end
+
+        sig { params(body: String).returns(T.untyped) }
+        def document(body)
+          match = Vocabulary::DOCUMENT_PATTERN.match(body)
+          return nil unless match
+
+          rest = trim(match[:rest])
+          return nil if rest.nil?
+
+          label = T.must(match[:label])
+          identify(label, Vocabulary::DOCUMENT_KINDS.fetch(label.downcase), rest)
+        end
+
+        sig { params(label: String, kind: Symbol, rest: String).returns(T.untyped) }
+        def identify(label, kind, rest)
+          head, issued_on, expires_on = split(rest)
+          value, qualifiers = unwrap(head)
+          return nil unless code?(value)
+
+          keep(@identifiers, Identifier.new(kind: kind, value: value, country: qualifiers.last,
+                                            issued_on: issued_on, expires_on: expires_on,
+                                            note: note(label, qualifiers)))
+        rescue ArgumentError
+          nil
+        end
+
+        sig { params(rest: String).returns([String, T.nilable(PartialDate), T.nilable(PartialDate)]) }
+        def split(rest)
+          dates = T.let({}, T::Hash[String, T.nilable(PartialDate)])
+          rest.scan(DATE_CLAUSE) { |keyword, date| dates[keyword.downcase] ||= PartialDate.parse(date) }
+          [rest.split(/\s+#{DATE_KEYWORDS}/, 2).first.to_s, dates["issued"], dates["expires"] || dates["expired"]]
+        end
+
+        # Outermost qualifier last, which is the one Identifier has a country
+        # field for. Anything inside it -- a state, a province -- has no home
+        # on the record and goes to the note rather than being dropped.
+        sig { params(head: String).returns([String, T::Array[String]]) }
+        def unwrap(head)
+          qualifiers = T.let([], T::Array[String])
+          text = head.dup
+          qualifiers.unshift(T.must(Regexp.last_match(1))) while text.sub!(TRAILING_QUALIFIER, "")
+          [text.strip, qualifiers]
+        end
+
+        sig { params(label: String, qualifiers: T::Array[String]).returns(String) }
+        def note(label, qualifiers)
+          inner = qualifiers[0..-2].to_a
+          inner.empty? ? label : "#{label} (#{inner.join(", ")})"
+        end
+
+        sig { params(body: String).returns(T.untyped) }
+        def digital_currency(body)
+          match = DIGITAL_CURRENCY.match(trim(body).to_s)
+          return nil unless match
+
+          currency = T.must(match[:currency]).upcase
+          keep(@identifiers, Identifier.new(kind: :other, value: match[:value], note: "#{currency} address"))
+        rescue ArgumentError
+          nil
+        end
+
+        sig { params(value: String).returns(T::Boolean) }
+        def code?(value)
+          return false if value.empty? || value.length > MAX_CODE_LENGTH || !CODE.match?(value)
+
+          DIGIT.match?(value) || value == value.upcase
+        end
+
+        # Returns the list, which is truthy: a caller reads "something was
+        # kept" from it, and a miss answers nil.
+        sig { params(list: T::Array[T.untyped], value: T.untyped).returns(T::Array[T.untyped]) }
+        def keep(list, value)
+          list << value
+        end
+
+        sig { params(value: T.untyped).returns(T.nilable(String)) }
+        def trim(value)
+          string = value.to_s.sub(TRAILING_STOP, "").strip
+          string.empty? ? nil : string
+        end
+      end
+    end
+  end
+end
+
+require "active_sanction/sources/ofac/remarks_parser/vocabulary"
+require "active_sanction/sources/ofac/remarks_parser/coverage"

data/lib/active_sanction/sources/ofac.rb

@@ -0,0 +1,248 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/parsers"
+require "active_sanction/sources"
+require "active_sanction/sources/base"
+
+module ActiveSanction
+  module Sources
+    # What the two OFAC lists have in common, which is nearly everything.
+    #
+    # OFAC publishes the SDN list and the Consolidated (non-SDN) list in
+    # exactly the same shape: three headerless CSVs joined on `ent_num`, the
+    # primary file carrying twelve columns, ALT carrying five and ADD six, all
+    # of them in Windows-1252 with `-0- ` for null. Only the file names, the
+    # sizes and the legal consequence of being on one differ.
+    #
+    #   SDN.CSV        19,321 rows      CONS_PRIM.CSV      481 rows
+    #   ALT.CSV        20,147 rows      CONS_ALT.CSV     1,109 rows
+    #   ADD.CSV        25,078 rows      CONS_ADD.CSV       614 rows
+    #
+    # So the reading is written once, here, and an adapter says only which
+    # list it is and where its three files live. Abstract: it declares no key
+    # and does not register, because there is no such list as "OFAC".
+    #
+    # ### The fields OFAC publishes no columns for
+    #
+    # Neither file has a date of birth, place of birth, nationality or
+    # passport column. All of it is prose in `Remarks`:
+    #
+    #     "DOB 10 Dec 1948; POB Egypt; nationality Egypt; Passport 123456 (Egypt)"
+    #
+    # RemarksParser reads it, and #remarks_coverage reports how much of it it
+    # understood -- 97% of the SDN file's 88,827 segments, which is a figure to
+    # watch rather than a guarantee. The remark is kept verbatim either way, so
+    # a pattern that goes stale costs structure and never content.
+    #
+    # This class is written entirely against the public extension points:
+    # declarations from Definition, fetch and cache and checksum from Base,
+    # reading and joining from Parsers. It required no change to any of them,
+    # which is the property M4 exists to prove.
+    #
+    # @api private
+    class Ofac < Base
+      extend T::Sig
+
+      jurisdiction :us
+      authority "U.S. Department of the Treasury, Office of Foreign Assets Control"
+      format :csv
+
+      # A work of the United States government, which 17 U.S.C. Section 105
+      # puts outside copyright protection. Treasury restricts its seals and
+      # its name rather than the data, which is why the notice mentions them:
+      # republishing the list is unencumbered, implying Treasury endorsed you
+      # is not.
+      licence_notice "A work of the U.S. government and not subject to " \
+                     "domestic copyright (17 U.S.C. 105). Treasury's seals " \
+                     "and marks are restricted separately, and nothing here " \
+                     "may imply endorsement. Verified 2026-09-11."
+      licence_url "https://home.treasury.gov/subfooter/site-policies-and-notices"
+
+      # The one floor either OFAC list commits to, and only for the run that
+      # has no previous snapshot to compare against. RemarksParser reads about
+      # 97% of the SDN file's segments; 90% is a long way below anything the
+      # file has done and still far above what a re-spelled document label
+      # would leave. There is deliberately no floor on the record count: the
+      # SDN list has roughly tripled since 2010, so any bound wide enough to
+      # have survived that is too wide to catch a truncated download, and the
+      # previous snapshot catches one for nothing. See Definition#floor.
+      floor :remarks_coverage, 0.90
+
+      # OFAC serves Windows-1252, not UTF-8, and says nothing about it in a
+      # header. Read as UTF-8 the accented names in the list -- and there are
+      # thousands -- arrive as replacement characters.
+      ENCODING = T.let(Encoding::WINDOWS_1252, Encoding)
+
+      # OFAC writes "-0- " for null, with a trailing space, in every one of its
+      # files and roughly a quarter of a million times overall.
+      NULL = T.let("-0-", String)
+
+      # Column names, positional: all six files ship without a header row.
+      # Declaring them here also pins each file's width, so a column inserted
+      # upstream surfaces as a warning on every row rather than as 19,321
+      # entities quietly built from shifted fields.
+      PRIMARY_COLUMNS = T.let(%i[
+        ent_num sdn_name sdn_type program title call_sign vessel_type
+        tonnage gross_registered_tonnage vessel_flag vessel_owner remarks
+      ].freeze, T::Array[Symbol])
+
+      ALT_COLUMNS = T.let(%i[ent_num alt_num alt_type alt_name alt_remarks].freeze, T::Array[Symbol])
+
+      ADD_COLUMNS = T.let(
+        %i[ent_num add_num address city_state_province_postal_code country add_remarks].freeze,
+        T::Array[Symbol]
+      )
+
+      PRIMARY = T.let(
+        Parsers::DelimitedTable.new(columns: PRIMARY_COLUMNS, null: NULL, encoding: ENCODING),
+        Parsers::DelimitedTable
+      )
+      ALT = T.let(
+        Parsers::DelimitedTable.new(columns: ALT_COLUMNS, null: NULL, encoding: ENCODING),
+        Parsers::DelimitedTable
+      )
+      ADD = T.let(
+        Parsers::DelimitedTable.new(columns: ADD_COLUMNS, null: NULL, encoding: ENCODING),
+        Parsers::DelimitedTable
+      )
+
+      # OFAC's join key. Every row of all six files carries one, and it is the
+      # only column on the primary file whose *values* have a shape.
+      ENT_NUM = T.let(/\A\d+\z/, Regexp)
+
+      # Rows that could not be read, and child rows that matched no entity.
+      # Populated by #parse and read afterwards -- sync orchestration (#34)
+      # reports them, and a nonzero orphan count is the signal that the three
+      # files were downloaded at different moments and no longer agree.
+      sig { returns(T::Array[Parsers::Warning]) }
+      attr_reader :warnings
+
+      # Child rows that matched no entity, by file -- a nonzero count means the
+      # three files were downloaded at different moments.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      attr_reader :orphans
+
+      # How much of OFAC's free text the last #parse understood. Not a warning,
+      # because an unread segment is not an error -- it is still in the remark,
+      # in the publisher's own words -- but a figure to watch: it is the only
+      # thing that moves when OFAC changes how it writes a passport line.
+      sig { returns(RemarksParser::Coverage) }
+      attr_reader :remarks_coverage
+
+      sig { params(args: T.untyped, options: T.untyped).void }
+      def initialize(*args, **options)
+        super
+        @warnings = T.let([], T::Array[Parsers::Warning])
+        @orphans = T.let({}, T::Hash[Symbol, T.untyped])
+        @remarks_coverage = T.let(RemarksParser::Coverage.new, RemarksParser::Coverage)
+        @unmapped = T.let([], T::Array[Parsers::Warning])
+      end
+
+      sig { override.params(raw: T.untyped).returns(T::Array[Entity]) }
+      def parse(raw)
+        join = Parsers::Join.new(on: :ent_num, aliases: ALT.read(raw[:alt]), addresses: ADD.read(raw[:add]))
+        entities = build(join, PRIMARY.read(raw[primary_file]))
+        @warnings = join.warnings + @unmapped
+        @orphans = join.orphans
+        entities
+      end
+
+      # What the two assertable columns of the primary file hold.
+      #
+      # The width declared in PRIMARY_COLUMNS catches a column OFAC *inserts*:
+      # every row arrives the wrong width and every row says so. Nothing about
+      # the width catches one OFAC *reorders*, which parses cleanly and builds
+      # 19,321 entities out of shifted fields. These are what catches that.
+      #
+      # Two of twelve, because ten of the columns are free text a government
+      # writes for people and there is nothing to assert about them. See
+      # Parsers::ColumnShape.
+      #
+      # `sdn_type` is held to three quarters rather than the 99% `ent_num` is,
+      # and the difference is what each one would cost to get wrong. OFAC does
+      # publish types this adapter has never seen -- that is what
+      # Record#unknown_type? exists for, and a new one is an `info` finding and
+      # a mapping to write, not a broken file. Demanding 99% would turn the
+      # week OFAC coins a word into an `error` on a list that is entirely fine,
+      # and a diagnostic that cries wolf about a healthy list is one nobody
+      # reads the week it is right. What three quarters still catches is the
+      # only thing worth an error here: a column that has stopped being the
+      # type column at all, which reads as zero.
+      sig { returns(T::Array[Parsers::ColumnShape]) }
+      def column_assertions
+        [Parsers::ColumnShape.new(name: :ent_num, matches: ENT_NUM, description: "numeric"),
+         Parsers::ColumnShape.new(name: :sdn_type, allowing: record_class.published_types, at_least: 0.75,
+                                  description: "a published SDN_Type")]
+      end
+
+      # One extra pass over the primary file, for the doctor and nothing else.
+      # It is the same reader the parse used, asked a different question.
+      sig { override.params(raw: T.untyped).returns(T::Array[Parsers::ColumnShape::Tally]) }
+      def column_shapes(raw)
+        rows = PRIMARY.read(raw[primary_file]).to_a
+        column_assertions.map { |shape| shape.tally(rows.map { |row| row[shape.name] }) }
+      end
+
+      # The declaration name of the file carrying one row per entity -- `:sdn`
+      # for the SDN list, `:prim` for the consolidated one. The first file an
+      # adapter declares, by the convention that the primary comes before the
+      # children it is joined to.
+      sig { returns(Symbol) }
+      def primary_file = T.must(urls.keys.first)
+
+      private
+
+      # The class each joined row is handed to. Overridden by an adapter whose
+      # list publishes something the shared mapping does not know about.
+      sig { returns(T.untyped) }
+      def record_class = Record
+
+      # Coverage is folded over every row, the nameless ones that produce no
+      # entity included: the question it answers is how much of the file this
+      # parser can read, and a row we drop is still a row OFAC published.
+      sig { params(join: Parsers::Join, rows: T.untyped).returns(T::Array[Entity]) }
+      def build(join, rows)
+        @unmapped = []
+        @remarks_coverage = RemarksParser::Coverage.new
+        entities = []
+        join.each(rows) do |row, related|
+          record = record_class.new(row: row, source: key, aliases: related[:aliases],
+                                    addresses: related[:addresses])
+          note(record)
+          entity = record.entity
+          entity.nil? ? note_nameless(row) : entities << entity
+        end
+        entities
+      end
+
+      # Everything worth saying about one record before it becomes an entity.
+      # A subclass adds to it rather than replacing it, so a list that can
+      # complain about more still complains about the same things.
+      sig { params(record: T.untyped).void }
+      def note(record)
+        note_unknown_type(record) if record.unknown_type?
+        @remarks_coverage.record(record.parsed_remarks)
+      end
+
+      sig { params(record: T.untyped).void }
+      def note_unknown_type(record)
+        @unmapped << Parsers::Warning.new(
+          line: record.row.line,
+          message: "unknown SDN_Type #{record.row[:sdn_type].inspect}; treated as an organization"
+        )
+      end
+
+      sig { params(row: Parsers::DelimitedTable::Row).void }
+      def note_nameless(row)
+        @unmapped << Parsers::Warning.new(
+          line: row.line, message: "row #{row[:ent_num].inspect} has no SDN_Name and was skipped"
+        )
+      end
+    end
+  end
+end
+
+require "active_sanction/sources/ofac/record"

data/lib/active_sanction/sources/ofac_consolidated/record.rb

@@ -0,0 +1,37 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/sources/ofac"
+
+module ActiveSanction
+  module Sources
+    class OfacConsolidated < Ofac
+      # A consolidated row, read exactly as an SDN row is, plus the one thing
+      # the SDN list does not have to say: which of OFAC's six non-SDN lists
+      # this record is on.
+      #
+      # The attribution is derived from the programs rather than stored beside
+      # them, so that it stays derivable from a stored Entity long after this
+      # object is gone -- see OfacConsolidated.lists. What the record adds is
+      # the human-readable form, appended to remarks ahead of the other
+      # source fields because it is the first thing an examiner looking at a
+      # hit needs to know.
+      #
+      # @api private
+      class Record < Ofac::Record
+        extend T::Sig
+
+        sig { returns(T::Array[Symbol]) }
+        def lists = OfacConsolidated.lists(programs)
+
+        sig { returns(T::Array[String]) }
+        def list_names = lists.map { |list| OfacConsolidated::NAMES.fetch(list) }
+
+        sig { override.returns(T::Array[T.untyped]) }
+        def remark_fields = [["List", list_names]] + super
+      end
+    end
+  end
+end