active_sanction 1.0.0

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

@@ -0,0 +1,279 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/entity"
+require "active_sanction/name"
+require "active_sanction/address"
+require "active_sanction/identifier"
+require "active_sanction/partial_date"
+require "active_sanction/sources/remarks"
+
+module ActiveSanction
+  module Sources
+    class UnConsolidated < Base
+      # One `<INDIVIDUAL>` or `<ENTITY>` turned into an Entity.
+      #
+      # Separate from the adapter because they are two jobs: the adapter says
+      # what the list is and where it lives, and this says what the UN's
+      # elements mean. The mapping is where all the judgment sits, so it is
+      # worth being able to read it on its own.
+      #
+      # The two record shapes are mapped by one class rather than two. Every
+      # element that differs between them differs only by prefix --
+      # `INDIVIDUAL_ALIAS` against `ENTITY_ALIAS`, `INDIVIDUAL_ADDRESS` against
+      # `ENTITY_ADDRESS` -- so the prefix is taken from the record's own name.
+      # An element only individuals have then resolves to a path entities do
+      # not carry, which reads as absent, which is what it is.
+      #
+      # @api private
+      class Record
+        extend T::Sig
+
+        TYPES = T.let({ UnConsolidated::INDIVIDUAL => :individual,
+                        UnConsolidated::ENTITY => :organization }.freeze, T::Hash[String, Symbol])
+
+        # The UN splits one name across up to four numbered elements, and any
+        # subset may be present: 736 individuals have a FIRST_NAME, 170 have a
+        # FOURTH_NAME, and an entity's whole name is in FIRST_NAME alone.
+        NAME_PARTS = T.let(%w[FIRST_NAME SECOND_NAME THIRD_NAME FOURTH_NAME].freeze, T::Array[String])
+
+        # `QUALITY` under `<INDIVIDUAL_ALIAS>` grades the alias. Published as
+        # Good (1,534), Low (629), or blank (169).
+        ALIAS_QUALITIES = T.let({ "good" => :good, "low" => :low }.freeze, T::Hash[String, Symbol])
+
+        # `QUALITY` under `<ENTITY_ALIAS>` is not a grade at all -- it is the
+        # alias kind, published as a.k.a. (585), f.k.a. (19), or blank (125).
+        # One element name, two vocabularies, in one document. Both tables are
+        # consulted for every alias and each misses the other's values, so
+        # neither shape needs a branch and neither loses what it publishes.
+        ALIAS_KINDS = T.let(
+          { "a.k.a." => :aka, "f.k.a." => :fka, "n.k.a." => :nka }.freeze, T::Hash[String, Symbol]
+        )
+
+        # `TYPE_OF_DOCUMENT` is free text, and the UN writes it in three
+        # languages. Anything unrecognised is :other, which is a real answer:
+        # a document we cannot classify still matches on its number.
+        DOCUMENT_KINDS = T.let({
+          "passport" => :passport,
+          "numéro de passeport" => :passport,
+          "número de pasaporte" => :passport,
+          "national identification number" => :national_id
+        }.freeze, T::Hash[String, Symbol])
+
+        # `TYPE_OF_DATE`, of which only these two change how the date is read.
+        # EXACT and a blank value are the same instruction: read what is there.
+        BETWEEN = T.let("BETWEEN", String)
+        APPROXIMATELY = T.let("APPROXIMATELY", String)
+
+        # Elements the canonical model has no home for, appended to remarks
+        # rather than dropped. A gender and a place of birth are real screening
+        # signal, and losing them to keep a schema tidy is the wrong trade.
+        EXTRA_FIELDS = T.let({
+          "VERSIONNUM" => "Version", "REFERENCE_NUMBER" => "Reference", "GENDER" => "Gender",
+          "TITLE/VALUE" => "Title", "DESIGNATION/VALUE" => "Designation"
+        }.freeze, T::Hash[String, String])
+
+        PLACE_OF_BIRTH_PARTS = T.let(%w[STREET CITY STATE_PROVINCE COUNTRY NOTE].freeze, T::Array[String])
+
+        WHITESPACE = T.let(/\s+/, Regexp)
+
+        sig { returns(Parsers::XmlRecords::Record) }
+        attr_reader :node
+
+        sig { params(node: Parsers::XmlRecords::Record).void }
+        def initialize(node)
+          @node = T.let(node, Parsers::XmlRecords::Record)
+          @names = T.let(nil, T.nilable(T::Array[Name]))
+        end
+
+        # The entity, or nil for a record with no name -- which cannot be
+        # screened against and is never what the Committee meant to publish.
+        sig { returns(T.nilable(Entity)) }
+        def entity
+          return nil if names.empty?
+
+          Entity.new(source: :un_consolidated, source_ref: source_ref, type: type, names: names,
+                     addresses: addresses, identifiers: identifiers, dates_of_birth: dates_of_birth,
+                     nationalities: nationalities, programs: programs, listed_on: listed_on,
+                     remarks: remarks)
+        end
+
+        sig { returns(Symbol) }
+        def type = TYPES.fetch(node.name, :organization)
+
+        sig { returns(T.nilable(String)) }
+        def source_ref = node["DATAID"]
+
+        sig { returns(T::Array[String]) }
+        def nationalities = node.values("NATIONALITY/VALUE")
+
+        sig { returns(T.nilable(PartialDate)) }
+        def listed_on = PartialDate.parse(node["LISTED_ON"])
+
+        # The joined published name first, then the original script, then every
+        # alias in the order the Committee filed it.
+        sig { returns(T::Array[Name]) }
+        def names
+          @names ||= [published_name, original_script].compact + alias_names
+        end
+
+        sig { returns(T::Array[PartialDate]) }
+        def dates_of_birth
+          each("DATE_OF_BIRTH").filter_map { |born| date_of_birth(born) }
+        end
+
+        sig { returns(T::Array[Identifier]) }
+        def identifiers
+          each("DOCUMENT").filter_map { |document| identifier(document) }
+        end
+
+        sig { returns(T::Array[Address]) }
+        def addresses
+          each("ADDRESS").filter_map { |place| address(place) }
+        end
+
+        sig { returns(T::Array[String]) }
+        def programs = node.values("UN_LIST_TYPE")
+
+        # The UN's own comment verbatim, then the elements that have nowhere
+        # else to go, behind the marker that makes them trivial to strip again.
+        sig { returns(T.nilable(String)) }
+        def remarks
+          Remarks.build(node["COMMENTS1"], extras)
+        end
+
+        private
+
+        # The child elements of a record, which the UN names after the record
+        # they hang off. See the class comment for why that is worth exploiting.
+        sig { params(suffix: String).returns(T::Array[Parsers::XmlRecords::Record]) }
+        def each(suffix) = node.nodes("#{node.name}_#{suffix}")
+
+        sig { returns(T.nilable(Name)) }
+        def published_name
+          value = collapse(NAME_PARTS.filter_map { |part| node[part] }.join(" "))
+          value && Name.new(value: value, kind: :primary)
+        end
+
+        # The name as the publisher's own script writes it -- Arabic for 338 of
+        # the individuals. Filed as an alias with no `script` declared: which
+        # script a string is in is a question about its characters, and
+        # answering it from the element's name would be a guess. The normalizer
+        # (#26) reads the characters and is the right place for it.
+        sig { returns(T.nilable(Name)) }
+        def original_script
+          value = collapse(node["NAME_ORIGINAL_SCRIPT"])
+          value && Name.new(value: value, kind: :aka)
+        end
+
+        # 294 of the 3,061 alias elements are placeholders: `<QUALITY/>` and
+        # `<ALIAS_NAME/>` and nothing else. They must produce no name at all --
+        # a blank-valued Name would be a record that matches everything.
+        sig { returns(T::Array[Name]) }
+        def alias_names
+          each("ALIAS").filter_map do |alt|
+            value = collapse(alt["ALIAS_NAME"])
+            next nil if value.nil?
+
+            published = alt["QUALITY"].to_s.downcase
+            Name.new(value: value, kind: ALIAS_KINDS.fetch(published, :aka),
+                     quality: ALIAS_QUALITIES[published])
+          end
+        end
+
+        # 55 of the 949 date elements carry a TYPE_OF_DATE and no date, which
+        # reads as nil rather than as a date of unknown value.
+        sig { params(born: Parsers::XmlRecords::Record).returns(T.nilable(PartialDate)) }
+        def date_of_birth(born)
+          type_of_date = born["TYPE_OF_DATE"].to_s.upcase
+          return between(born) if type_of_date == BETWEEN
+
+          approximate(PartialDate.parse(born["DATE"] || born["YEAR"]), type_of_date)
+        end
+
+        sig { params(born: Parsers::XmlRecords::Record).returns(T.nilable(PartialDate)) }
+        def between(born)
+          from = born["FROM_YEAR"]
+          to = born["TO_YEAR"]
+          return nil if from.nil? || to.nil?
+
+          PartialDate.range(from, to)
+        end
+
+        # "Circa 1962" and "1963" are the same claim about a person, and
+        # PartialDate already knows to compare an approximate date loosely --
+        # but only if the adapter tells it the publisher said approximately.
+        sig { params(date: T.nilable(PartialDate), type_of_date: String).returns(T.nilable(PartialDate)) }
+        def approximate(date, type_of_date)
+          return date if date.nil? || type_of_date != APPROXIMATELY
+
+          PartialDate.from_h(date.to_h.merge(approximate: true))
+        end
+
+        # 447 of the UN's 954 document elements name a document type and give
+        # no number. There is nothing there to match on, so they are dropped
+        # rather than kept as identifiers with no identity.
+        sig { params(document: Parsers::XmlRecords::Record).returns(T.nilable(Identifier)) }
+        def identifier(document)
+          return nil if document.null?("NUMBER")
+
+          Identifier.new(kind: document_kind(document), value: document["NUMBER"],
+                         country: document["ISSUING_COUNTRY"] || document["COUNTRY_OF_ISSUE"],
+                         issued_on: PartialDate.parse(document["DATE_OF_ISSUE"]),
+                         expires_on: PartialDate.parse(document["DATE_OF_EXPIRY"]),
+                         note: document_note(document))
+        rescue ArgumentError
+          nil
+        end
+
+        sig { params(document: Parsers::XmlRecords::Record).returns(Symbol) }
+        def document_kind(document)
+          DOCUMENT_KINDS.fetch(collapse(document["TYPE_OF_DOCUMENT"]).to_s.downcase, :other)
+        end
+
+        sig { params(document: Parsers::XmlRecords::Record).returns(T.nilable(String)) }
+        def document_note(document)
+          parts = [collapse(document["TYPE_OF_DOCUMENT2"]), document["CITY_OF_ISSUE"], document["NOTE"]].compact
+          parts.empty? ? nil : parts.join("; ")
+        end
+
+        # An address element that located nothing is dropped rather than kept
+        # empty: it cannot be screened on and would only inflate the count.
+        sig { params(place: Parsers::XmlRecords::Record).returns(T.nilable(Address)) }
+        def address(place)
+          Address.new(street: place["STREET"], city: place["CITY"], state_province: place["STATE_PROVINCE"],
+                      postal_code: place["ZIP_CODE"], country: place["COUNTRY"], note: place["NOTE"])
+        rescue ArgumentError
+          nil
+        end
+
+        # Label/value pairs for Remarks.build, which drops the ones the record
+        # left blank. A value may be several -- the UN files three designations
+        # under one element -- and arrives as the Array it published.
+        sig { returns(T::Array[T.untyped]) }
+        def extras
+          EXTRA_FIELDS.map { |path, label| [label, node.values(path)] } + places_of_birth
+        end
+
+        sig { returns(T::Array[T.untyped]) }
+        def places_of_birth
+          each("PLACE_OF_BIRTH").map do |place|
+            ["Place of birth", PLACE_OF_BIRTH_PARTS.filter_map { |part| place[part] }.join(", ")]
+          end
+        end
+
+        # The UN's own line wrapping arrives inside values: two names in the
+        # published file carry a newline and fifty spaces mid-string, and 39
+        # name parts are padded on one side. Joined verbatim those produce
+        # "JOHN  IMANI", which is a name nothing will ever match.
+        sig { params(value: T.untyped).returns(T.nilable(String)) }
+        def collapse(value)
+          string = value.to_s.split(WHITESPACE).join(" ")
+          string.empty? ? nil : -string
+        end
+      end
+    end
+  end
+end

data/lib/active_sanction/sources/un_consolidated.rb

@@ -0,0 +1,140 @@
+# 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
+    # The United Nations Security Council consolidated list: every individual
+    # and entity subject to a UN sanctions regime, in one document.
+    #
+    #   snapshot = ActiveSanction::Sources[:un_consolidated].new.sync
+    #
+    # ### One file, two record shapes
+    #
+    #   https://scsanctions.un.org/resources/xml/en/consolidated.xml   2.2 MB
+    #
+    #     <INDIVIDUALS><INDIVIDUAL>   736 people
+    #     <ENTITIES><ENTITY>          275 organizations
+    #
+    # Both are read in a single streaming pass. The file is small enough today
+    # to have been loaded whole without anyone noticing, which is exactly why
+    # it was not: the toolkit this adapter is written against (#15) is the one
+    # that will read OFAC's 126 MB advanced XML, and an adapter that quietly
+    # depended on holding the document would have to be rewritten then.
+    #
+    # ### The trap in this list
+    #
+    # `QUALITY` appears under both alias elements and means something different
+    # under each. Under `<INDIVIDUAL_ALIAS>` it grades the alias -- Good or Low
+    # -- which is a matching signal the scorer (#32) penalizes on. Under
+    # `<ENTITY_ALIAS>` it is not a grade at all; it is `a.k.a.` or `f.k.a.`,
+    # which is an alias *kind*. Reading one as the other silently either throws
+    # away every entity's alias kind or grades 585 organization aliases on a
+    # scale that was never applied to them. Record maps them separately, and
+    # the counts above come from the published file rather than from a guess.
+    #
+    # ### What this adapter does not do
+    #
+    # `INDIVIDUAL_PLACE_OF_BIRTH`, `GENDER`, `TITLE` and `DESIGNATION` have no
+    # home in the canonical model. They are appended to remarks after a marker
+    # rather than dropped -- a place of birth is real screening signal, and
+    # losing it to keep a schema tidy is the wrong trade -- and are left for a
+    # later issue to structure if a matcher turns out to want them.
+    class UnConsolidated < Base
+      extend T::Sig
+
+      key :un_consolidated
+      jurisdiction :un
+      authority "United Nations Security Council"
+      format :xml
+
+      # The most restrictive of the seven on paper. The UN's copyright page
+      # reserves reproduction of material on its sites, and the Consolidated
+      # List carries no separate open licence -- it is published so that
+      # member states and their regulated entities can implement the
+      # measures, which is the use this library is for. Redistributing it,
+      # as a bundle or through an API, is the case to take to counsel.
+      licence_notice "Copyright reserved by the United Nations. Published " \
+                     "for implementation of Security Council measures; no " \
+                     "open reuse licence is stated. Verified 2026-09-11."
+      licence_url "https://www.un.org/en/about-us/copyright"
+
+      url :main, "https://scsanctions.un.org/resources/xml/en/consolidated.xml"
+
+      # @api private
+      INDIVIDUAL = T.let("INDIVIDUAL", String)
+      # @api private
+      ENTITY = T.let("ENTITY", String)
+
+      # @api private
+      LIST = T.let(Parsers::XmlRecords.new(records: [INDIVIDUAL, ENTITY]), Parsers::XmlRecords)
+
+      # The generation timestamp the UN stamps on the document element. More
+      # precise than the Last-Modified header Base falls back to, and it is the
+      # string that appears on the UN's own site, so it is the one an examiner
+      # asking "which version was this screened against" will recognise.
+      #
+      # @api private
+      GENERATED_AT = T.let("dateGenerated", String)
+
+      # Records that could not be used. Read after #parse; sync orchestration
+      # (#34) reports them.
+      sig { returns(T::Array[Parsers::Warning]) }
+      attr_reader :warnings
+
+      sig { params(args: T.untyped, options: T.untyped).void }
+      def initialize(*args, **options)
+        super
+        @warnings = T.let([], T::Array[Parsers::Warning])
+        @unmapped = T.let([], T::Array[Parsers::Warning])
+        @generated_at = T.let(nil, T.nilable(String))
+      end
+
+      sig { override.params(raw: T.untyped).returns(T::Array[Entity]) }
+      def parse(raw)
+        reader = LIST.read(raw)
+        entities = build(reader)
+        @generated_at = reader.root[GENERATED_AT]
+        @warnings = reader.warnings + @unmapped
+        entities
+      end
+
+      sig { override.returns(T.nilable(String)) }
+      def source_version = @generated_at || super
+
+      private
+
+      sig { params(reader: Parsers::XmlRecords::Reader).returns(T::Array[Entity]) }
+      def build(reader)
+        @unmapped = []
+        reader.filter_map do |node|
+          record = Record.new(node)
+          entity = record.entity
+          entity.nil? ? note_nameless(node) : entity
+        end
+      end
+
+      # A record with no name cannot be screened against and is never what the
+      # Committee meant to publish. None of the 1,011 published today is
+      # nameless; the warning exists so that the day one is, it is visible
+      # rather than absent.
+      sig { params(node: Parsers::XmlRecords::Record).returns(NilClass) }
+      def note_nameless(node)
+        @unmapped << Parsers::Warning.new(
+          line: node.line,
+          message: "<#{node.name}> #{node["DATAID"].inspect} has no name and was skipped"
+        )
+        nil
+      end
+    end
+  end
+end
+
+require "active_sanction/sources/un_consolidated/record"
+
+ActiveSanction::Sources.register(ActiveSanction::Sources::UnConsolidated)

data/lib/active_sanction/sources.rb

@@ -0,0 +1,196 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/configuration"
+require "active_sanction/error"
+
+module ActiveSanction
+  # Every sanctions list this library knows how to read, filed under the key
+  # its adapter declares.
+  #
+  #   ActiveSanction::Sources[:un_consolidated]   # => the adapter class
+  #   ActiveSanction::Sources.keys                # => [:ofac_sdn, :un_consolidated, ...]
+  #
+  # The registry is open, and that is the point of this milestone. A bank with
+  # an internal watchlist, or a gem adding a jurisdiction this one has not got
+  # to, registers an adapter of its own without forking:
+  #
+  #   ActiveSanction::Sources.register(MyCompany::InternalWatchlist)
+  #   ActiveSanction.configure { |c| c.sources = %i[ofac_sdn my_internal_watchlist] }
+  #
+  # Nothing here requires Sources::Base. Registration is duck-typed on `.key`
+  # and `.new`, so a source backed by a database table rather than a published
+  # file -- which has no URL to declare and no payload to fetch -- is a
+  # first-class citizen rather than something that has to pretend to be a file
+  # download. Base is the convenient way to write an adapter, not the price of
+  # admission.
+  #
+  # Built-in adapters register themselves at the bottom of their own file, one
+  # explicit `Sources.register(self)` line each, rather than being enrolled by
+  # `inherited`. Auto-registering every subclass would also enrol the abstract
+  # intermediates that adapters sharing a publisher will want (an OFAC base
+  # holding the authority and the format for SDN and Consolidated both) and
+  # every throwaway subclass a test defines.
+  module Sources
+    # Two lists cannot answer to one name. Raised at load time, which is where
+    # this collision is cheap to fix.
+    #
+    # A ConfigurationError, like the two below it: all three are an
+    # installation wired up wrong -- a key typed twice, a key typed wrong, an
+    # adapter that never declared what it is -- and none of them is fixed by
+    # waiting and trying again.
+    class DuplicateKey < ConfigurationError; end
+
+    # A key nothing is registered under: a typo in `config.sources`, a CLI
+    # argument, or an adapter whose file was never required.
+    class UnknownSource < ConfigurationError; end
+
+    # An adapter that does not declare what the contract requires, or is asked
+    # for a declaration it never made.
+    class DeclarationError < ConfigurationError; end
+
+    # The bytes of one of a source's files could not be obtained -- the
+    # publisher confirmed a copy we do not hold, and re-asking for it in full
+    # did not produce one either.
+    #
+    # Retryable: it is a publisher or an intermediary cache in a state it will
+    # not be in an hour from now, and the next run usually just works.
+    class MissingPayload < FetchError
+      extend T::Sig
+
+      sig { returns(T::Boolean) }
+      def retryable? = retryable_or(true)
+    end
+
+    # @api private
+    MUTEX = T.let(Mutex.new, Mutex)
+    private_constant :MUTEX
+
+    # Built at load rather than memoized on first use. A lazily created Hash
+    # is itself a write, and the first two adapters to register in two threads
+    # would each create one and each keep the half of the registry the other
+    # could not see. Everything that writes to it holds MUTEX; reads do not,
+    # because a registry is written at load and read for the life of the
+    # process.
+    #
+    # @api private
+    REGISTRY = T.let({}, T::Hash[Symbol, T.untyped])
+    private_constant :REGISTRY
+
+    class << self
+      extend T::Sig
+
+      # An adapter is anything answering `.key` and `.new`, which is why every
+      # signature here says `T.untyped` where a class goes and none of them
+      # says `T.class_of(Sources::Base)`. That is the milestone this registry
+      # exists for: a bank's internal watchlist, backed by a database table
+      # with no URL and no payload, is a first-class source rather than
+      # something pretending to be a file download. Narrowing these types would
+      # quietly close what the class comment above promises is open.
+
+      # Adds a source to the registry and returns it. Registering the same
+      # class twice is a no-op, so a file that manages to get loaded under two
+      # paths does not take the whole process down with it.
+      sig { params(source: T.untyped).returns(T.untyped) }
+      def register(source)
+        key = registrable!(source)
+        MUTEX.synchronize do
+          claimed = registry[key]
+          raise DuplicateKey, duplicate_message(key, source, claimed) if claimed && claimed != source
+
+          registry[key] = source
+        end
+        source
+      end
+
+      # The adapter registered under a key.
+      #
+      # Raises rather than returning nil, because every caller of this method
+      # is resolving a name a human typed -- into `config.sources`, into
+      # `activesanction sync ofac_sdb` -- and a nil surfaces three layers later
+      # as a NoMethodError that says nothing about the misspelling. The message
+      # lists what *is* registered, which is also the answer to "why is my
+      # adapter not being picked up" (its file was never required).
+      sig { params(key: T.untyped).returns(T.untyped) }
+      def [](key)
+        name = key.to_sym
+        registry.fetch(name) do
+          raise UnknownSource, "no source registered as #{name.inspect}. Registered: #{list}"
+        end
+      end
+
+      sig { params(key: T.untyped).returns(T::Boolean) }
+      def registered?(key) = registry.key?(key.to_sym)
+
+      # Every registered adapter, ordered by key so a CLI listing and a sync
+      # summary do not reshuffle themselves between runs.
+      sig { returns(T::Array[T.untyped]) }
+      def all = registry.keys.sort.map { |key| registry[key] }
+
+      sig { returns(T::Array[Symbol]) }
+      def keys = registry.keys.sort
+
+      sig { returns(Integer) }
+      def size = registry.size
+
+      sig { returns(T::Boolean) }
+      def empty? = registry.empty?
+
+      # The adapters a sync should run: what `config.sources` names, or every
+      # registered source when it names nothing. An unknown key raises here,
+      # at the start of the run, rather than after the other lists have been
+      # downloaded.
+      sig { params(configured: T.nilable(T::Array[Symbol])).returns(T::Array[T.untyped]) }
+      def enabled(configured = ActiveSanction.config.sources)
+        return all if configured.nil?
+
+        configured.map { |key| self[key] }
+      end
+
+      # Drops a key and returns what was registered there, or nil. The
+      # supported way to replace a built-in adapter with a patched one:
+      #
+      #   ActiveSanction::Sources.unregister(:ofac_sdn)
+      #   ActiveSanction::Sources.register(MyCompany::PatchedOfacSdn)
+      #
+      # There is deliberately no `clear!`. Built-in adapters register on
+      # require, and `require` runs once per process: a suite that emptied the
+      # registry between examples would leave every later example running
+      # against a library that has forgotten its own sources.
+      sig { params(key: T.untyped).returns(T.untyped) }
+      def unregister(key)
+        MUTEX.synchronize { registry.delete(key.to_sym) }
+      end
+
+      private
+
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def registry = REGISTRY
+
+      sig { returns(String) }
+      def list = registry.empty? ? "(nothing)" : keys.join(", ")
+
+      sig { params(source: T.untyped).returns(Symbol) }
+      def registrable!(source)
+        unless source.respond_to?(:key) && source.respond_to?(:new)
+          raise InvalidArgument, "a source must answer .key and .new, got #{source.inspect}"
+        end
+
+        Definition.key!(source.key)
+      end
+
+      sig { params(key: Symbol, source: T.untyped, claimed: T.untyped).returns(String) }
+      def duplicate_message(key, source, claimed)
+        "cannot register #{source} as #{key.inspect}: #{claimed} already claims that key. A key is the public " \
+          "name of a list -- in configuration, in stored snapshots, in every match result that cites it -- so two " \
+          "lists cannot share one. Give the new source a different key, or call " \
+          "ActiveSanction::Sources.unregister(#{key.inspect}) first if you mean to replace #{claimed}."
+      end
+    end
+  end
+end
+
+require "active_sanction/sources/definition"
+require "active_sanction/sources/base"