active_sanction 1.0.0

data/lib/active_sanction/entity.rb

@@ -0,0 +1,293 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module ActiveSanction
+  # The single source-agnostic record every adapter produces. Nothing
+  # downstream -- storage, index, matcher -- should ever need to know which
+  # government published a record.
+  #
+  #   ActiveSanction::Entity.new(
+  #     id:            "ofac_sdn:2674",
+  #     source:        :ofac_sdn,
+  #     source_ref:    "2674",
+  #     type:          :individual,
+  #     names:         [Name, ...],
+  #     addresses:     [Address, ...],
+  #     identifiers:   [Identifier, ...],
+  #     dates_of_birth: [PartialDate, ...],
+  #     nationalities: ["EG"],
+  #     programs:      ["SDGT"],
+  #     listed_on:     PartialDate,
+  #     remarks:       "..."
+  #   )
+  #
+  # Instances are frozen on construction and compare by value.
+  class Entity
+    extend T::Sig
+
+    # `vessel` and `aircraft` are first-class because they are ~10% of the OFAC
+    # SDN list (1,540 vessels, 342 aircraft) and carry name-like strings. Without
+    # a distinct type a search for a person can rank a ship.
+    TYPES = T.let(%i[individual organization vessel aircraft].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.
+    #
+    # @api private
+    MEMBERS = T.let(%i[
+      id source source_ref type names addresses identifiers dates_of_birth
+      nationalities programs listed_on remarks
+    ].freeze, T::Array[Symbol])
+
+    # Plural, and it is not a hedge. The UN publishes more than one date of
+    # birth for 140 of its 736 individuals and as many as ten for one of them,
+    # because that is the honest state of the intelligence: several
+    # governments reported several dates and the Committee listed all of them.
+    # Collapsing that to one would mean choosing, on no evidence, which
+    # report to believe -- and a screening decision that clears someone whose
+    # DOB matched the discarded one is exactly the failure this library exists
+    # to prevent. The scorer (#32) reads them the way PartialDate#overlaps?
+    # already reads a single imprecise date: any of them matching is a match.
+    #
+    # @api private
+    DATE_MEMBERS = T.let(%i[dates_of_birth].freeze, T::Array[Symbol])
+
+    # Which class rebuilds each nested member from a hash. The names are
+    # strings, resolved lazily through `const_get`, so this file depends on
+    # none of those four classes at load time -- and Sorbet cannot see through
+    # that, deliberately. What the checker holds instead is the other end:
+    # #initialize declares all four member types, so a hash that rebuilds into
+    # the wrong thing is caught where the entity is built rather than here.
+    #
+    # @api private
+    COLLECTION_TYPES = T.let({
+      names: "ActiveSanction::Name",
+      addresses: "ActiveSanction::Address",
+      identifiers: "ActiveSanction::Identifier",
+      dates_of_birth: "ActiveSanction::PartialDate"
+    }.freeze, T::Hash[Symbol, String])
+
+    # @api private
+    SCALAR_TYPES = T.let({ listed_on: "ActiveSanction::PartialDate" }.freeze, T::Hash[Symbol, String])
+
+    # Namespaced, and never nil: #initialize derives one from the source and
+    # the publisher's own reference when the caller gives none.
+    sig { returns(String) }
+    attr_reader :id
+
+    sig { returns(Symbol) }
+    attr_reader :source
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :source_ref
+
+    sig { returns(Symbol) }
+    attr_reader :type
+
+    sig { returns(T::Array[Name]) }
+    attr_reader :names
+
+    sig { returns(T::Array[Address]) }
+    attr_reader :addresses
+
+    sig { returns(T::Array[Identifier]) }
+    attr_reader :identifiers
+
+    sig { returns(T::Array[PartialDate]) }
+    attr_reader :dates_of_birth
+
+    sig { returns(T::Array[String]) }
+    attr_reader :nationalities
+
+    sig { returns(T::Array[String]) }
+    attr_reader :programs
+
+    sig { returns(T.nilable(PartialDate)) }
+    attr_reader :listed_on
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :remarks
+
+    # Rebuilds an entity from #to_h output. Accepts string keys too, so a record
+    # that has been through JSON round-trips 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 Entity attribute(s): #{unknown.join(", ")}" if unknown.any?
+
+      # `new(**hash)` past required keyword parameters is one of the few
+      # things Sorbet cannot check statically. The hash is validated on the two
+      # lines above and by #initialize below, so what is lost here is only the
+      # checker's ability to see it happen.
+      T.unsafe(self).new(**coerce_members(attributes))
+    end
+
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+    def self.coerce_members(attributes)
+      COLLECTION_TYPES.each do |member, class_name|
+        attributes[member] &&= attributes[member].map { |value| build(class_name, value) }
+      end
+      SCALAR_TYPES.each { |member, class_name| attributes[member] &&= build(class_name, attributes[member]) }
+      attributes
+    end
+    private_class_method :coerce_members
+
+    # Values that are already value objects pass through untouched, so from_h is
+    # safe to call on a half-deserialized hash.
+    sig { params(class_name: String, value: T.untyped).returns(T.untyped) }
+    def self.build(class_name, value)
+      return value unless value.is_a?(Hash)
+
+      Object.const_get(class_name).from_h(value)
+    end
+    private_class_method :build
+
+    # Each collection is nilable because nil is how "the publisher listed
+    # none" arrives from a store or a half-built hash; #list! turns it into the
+    # empty array the reader hands back.
+    #
+    # The four collection members and `listed_on` are declared, and the rest is
+    # `T.untyped` on purpose. The difference is who wrote the value: the nested
+    # members are canonical objects an adapter builds, and declaring them is
+    # what makes `srb tc` refuse an adapter that hands over the string a
+    # publisher wrote where a PartialDate belongs. The runtime check that comes
+    # with the signature is shallow -- it sees the Array and not what is in it
+    # -- so the adapter conformance group goes on asserting the element types
+    # per fixture, which is what covers an adapter written outside this repo.
+    #
+    # Everything else is the publisher's own text arriving as whatever the
+    # parser made of it, and the coercions below say what happens to it in
+    # messages written for whoever has to fix the record. A type error would
+    # say less.
+    sig do
+      params(
+        source: T.untyped,
+        type: T.untyped,
+        id: T.untyped,
+        source_ref: T.untyped,
+        names: T.nilable(T::Array[Name]),
+        addresses: T.nilable(T::Array[Address]),
+        identifiers: T.nilable(T::Array[Identifier]),
+        dates_of_birth: T.nilable(T::Array[PartialDate]),
+        nationalities: T.untyped,
+        programs: T.untyped,
+        listed_on: T.nilable(PartialDate),
+        remarks: T.untyped
+      ).void
+    end
+    def initialize(source:, type:, id: nil, source_ref: nil, names: [], addresses: [], identifiers: [],
+                   dates_of_birth: [], nationalities: [], programs: [], listed_on: nil, remarks: nil)
+      @source = T.let(symbol!(:source, source), Symbol)
+      @type = T.let(type!(type), Symbol)
+      @source_ref = T.let(string_or_nil(source_ref), T.nilable(String))
+      @id = T.let(string_or_nil(id) || derived_id, String)
+      @names = T.let(list!(:names, names), T::Array[Name])
+      @addresses = T.let(list!(:addresses, addresses), T::Array[Address])
+      @identifiers = T.let(list!(:identifiers, identifiers), T::Array[Identifier])
+      @dates_of_birth = T.let(list!(:dates_of_birth, dates_of_birth), T::Array[PartialDate])
+      @nationalities = T.let(strings!(:nationalities, nationalities), T::Array[String])
+      @programs = T.let(strings!(:programs, programs), T::Array[String])
+      @listed_on = T.let(listed_on, T.nilable(PartialDate))
+      # original free text, always retained verbatim
+      @remarks = T.let(string_or_nil(remarks), T.nilable(String))
+      freeze
+    end
+
+    # True when the publisher gave no date at all, which is most of OFAC --
+    # its dates are prose in Remarks and stay there until #19 reads them.
+    sig { returns(T::Boolean) }
+    def dates_of_birth? = dates_of_birth.any?
+
+    # The name an adapter marked `:primary`, falling back to the first name for
+    # sources such as Canada that publish no alias kinds at all.
+    sig { returns(T.nilable(Name)) }
+    def primary_name
+      names.find(&:primary?) || names.first
+    end
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def to_h
+      {
+        id: id,
+        source: source,
+        source_ref: source_ref,
+        type: type,
+        names: names.map(&:to_h),
+        addresses: addresses.map(&:to_h),
+        identifiers: identifiers.map(&:to_h),
+        dates_of_birth: dates_of_birth.map(&:to_h),
+        nationalities: nationalities,
+        programs: programs,
+        listed_on: listed_on&.to_h,
+        remarks: remarks
+      }
+    end
+
+    # Compared through #to_h so nested members only have to serialize, not
+    # implement value equality themselves. Class is part of the comparison to
+    # keep #== and #hash agreeing, which is what Hash and Set rely on.
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def ==(other)
+      return false unless other.instance_of?(self.class)
+
+      to_h == other.to_h
+    end
+    alias eql? ==
+
+    sig { returns(Integer) }
+    def hash
+      [self.class, to_h].hash
+    end
+
+    sig { returns(String) }
+    def inspect
+      "#<#{self.class} id=#{id.inspect} type=#{type.inspect} names=#{names.size}>"
+    end
+
+    private
+
+    sig { returns(String) }
+    def derived_id
+      raise InvalidArgument, "id is required when source_ref is nil" if source_ref.nil?
+
+      # Namespaced so ids stay unique and stable across sources.
+      -"#{source}:#{source_ref}"
+    end
+
+    sig { params(value: T.untyped).returns(Symbol) }
+    def type!(value)
+      type = symbol!(:type, value)
+      return type if TYPES.include?(type)
+
+      raise InvalidArgument, "unknown type #{type.inspect}, expected one of #{TYPES.join(", ")}"
+    end
+
+    sig { params(member: Symbol, value: T.untyped).returns(Symbol) }
+    def symbol!(member, value)
+      raise InvalidArgument, "#{member} is required" if value.nil? || value.to_s.empty?
+
+      value.to_sym
+    end
+
+    sig { params(value: T.untyped).returns(T.nilable(String)) }
+    def string_or_nil(value)
+      value.nil? ? nil : -value.to_s
+    end
+
+    sig { params(member: Symbol, value: T.untyped).returns(T.untyped) }
+    def list!(member, value)
+      return [].freeze if value.nil?
+      raise InvalidArgument, "#{member} must be an Array" unless value.is_a?(Array)
+
+      value.dup.freeze
+    end
+
+    sig { params(member: Symbol, value: T.untyped).returns(T::Array[String]) }
+    def strings!(member, value)
+      list!(member, value).map { |item| -item.to_s }.freeze
+    end
+  end
+end

data/lib/active_sanction/error.rb

@@ -0,0 +1,332 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module ActiveSanction
+  # The one rescue that covers this library.
+  #
+  #   begin
+  #     ActiveSanction.sync!
+  #   rescue ActiveSanction::Error => e
+  #     raise unless e.retryable?
+  #
+  #     RetryLater.enqueue(e.source_id)
+  #   end
+  #
+  # Every error raised out of a public method answers to this, and carries
+  # what a caller needs to decide between the only three responses there are
+  # to a screening failure: **retry this** (`retryable?`), **alert somebody**
+  # (anything else that is not the caller's fault), and **this is a bug in my
+  # call** (ConfigurationError, InvalidArgument, QueryError). None of those
+  # decisions should be made by matching on a message string, so none of them
+  # has to be.
+  #
+  # ### The hierarchy
+  #
+  #     Error                      the marker; rescue this
+  #       ConfigurationError       this installation is set up wrong; never retry
+  #       SourceError              something went wrong with one list
+  #         FetchError             the bytes could not be obtained
+  #         ParseError             the bytes could not be read
+  #         IntegrityError         the bytes are not what they claim to be
+  #       StorageError             the store could not answer
+  #       UnsupportedError         this object cannot do that
+  #       InvalidArgument          a public method was called wrongly
+  #         QueryError             ...specifically, with an unusable query
+  #       MissingKey               a field or column that does not exist
+  #
+  # ### Why this is a module and not a class
+  #
+  # Because two of its members have to be something else as well. A caller who
+  # passes `threshold: 300` has made the mistake Ruby has had a class for since
+  # 1995, and `rescue ArgumentError` is what the code around this library
+  # already says; asking every host application to learn a private synonym for
+  # it would be this library exporting its own taxonomy into code that has no
+  # reason to care. So InvalidArgument is an `::ArgumentError` and MissingKey is
+  # a `::KeyError` -- and Ruby has one superclass to give. A module is what lets
+  # them be both, and `rescue ActiveSanction::Error` covers them anyway, because
+  # `rescue` matches with `===`, which a module answers.
+  #
+  # The trade is that `ActiveSanction::Error` cannot be raised or instantiated
+  # itself. That is not a loss: an error that says only "something in the
+  # sanctions library went wrong" is not one a caller could act on, and every
+  # member below names a response.
+  #
+  # ### Stability
+  #
+  # This hierarchy is public API. Within a major version an error will not move
+  # to a different parent, and an attribute will not be removed. New subclasses
+  # may be added under an existing parent -- that is what keeps `rescue
+  # ActiveSanction::FetchError` working when a new transport failure is given a
+  # name of its own -- so a `case` over error classes should carry an `else`.
+  module Error
+    extend T::Sig
+    extend T::Helpers
+
+    # Only ever mixed into an exception class -- this is a marker for the
+    # library's own failures, not a bag of attributes anything can wear.
+    requires_ancestor { Exception }
+
+    # Which list the failure belongs to, as the key its adapter declared, or
+    # nil for a failure that is not about one list -- a bad configuration, an
+    # unusable query, a store that will not open at all.
+    #
+    # Always set on a SourceError by the time it leaves the source, even when
+    # the layer that raised it could not know: an HTTP client knows a URL, not
+    # which sanctions list is at the other end of it. See #in_source.
+    sig { returns(T.nilable(Symbol)) }
+    attr_reader :source_id
+
+    # The HTTP status behind the failure, where there was one. Nil for
+    # everything that failed before a server answered -- a timeout, a refused
+    # connection -- and for everything that is not a fetch.
+    sig { returns(T.nilable(Integer)) }
+    attr_reader :status
+
+    # `retryable:` overrides whatever the subclass would have decided, for the
+    # cases only the raising code knows about. Everything else is a subclass's
+    # own answer; see #retryable?.
+    sig do
+      params(message: T.untyped, source_id: T.untyped, status: T.untyped, retryable: T.nilable(T::Boolean)).void
+    end
+    def initialize(message = nil, source_id: nil, status: nil, retryable: nil)
+      @source_id = T.let(source_id&.to_sym, T.nilable(Symbol))
+      @status = T.let(status&.to_i, T.nilable(Integer))
+      @retryable = T.let(retryable, T.nilable(T::Boolean))
+      super(message)
+    end
+
+    # Whether running the same call again could plausibly succeed.
+    #
+    # A first-class predicate rather than something a consumer reconstructs
+    # from the message, because backoff is the one decision a host application
+    # has to make in the request path and it should not be making it out of
+    # English. False is the default and the safe answer: a failure nobody has
+    # classified is one to look at rather than one to hammer.
+    sig { returns(T::Boolean) }
+    def retryable? = retryable_or(false)
+
+    # The failure as data, for a log line or a job record that has to survive
+    # the process.
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def to_h
+      { error: self.class.name, message: message, source_id: source_id, status: status, retryable: retryable? }
+        .compact
+    end
+
+    # Stamps the list this failure belongs to onto an error raised by a layer
+    # that did not know it, and returns self so a rescue can re-raise in one
+    # line. Never overwrites a source already recorded -- the innermost layer
+    # that knew is the one that was right.
+    sig { params(key: T.untyped).returns(T.self_type) }
+    def in_source(key)
+      @source_id = T.let(key&.to_sym, T.nilable(Symbol)) if @source_id.nil?
+      self
+    end
+
+    private
+
+    # What a subclass answers with when the raising code did not override it.
+    # The override exists because the classification is occasionally something
+    # only the call site knows -- a 404 from a publisher that rotates its URLs
+    # weekly is worth another look, and one from a URL we hardcoded is not.
+    sig { params(default: T::Boolean).returns(T::Boolean) }
+    def retryable_or(default) = @retryable.nil? ? default : @retryable
+  end
+
+  # This installation is set up wrong: a blank User-Agent, a negative timeout,
+  # a source key nothing is registered under, an ActiveRecord store whose
+  # migration was never run.
+  #
+  # Never retryable, by definition -- nothing about waiting changes an
+  # initializer -- and raised as early as the bad value can be seen, which for
+  # a setting is where it is set rather than during a sync three hours later.
+  # Separate from InvalidArgument: this means "this installation is
+  # misconfigured", that means "this call is wrong", and only one of them is
+  # fixed by editing an initializer.
+  class ConfigurationError < StandardError
+    extend T::Sig
+    include Error
+
+    sig { returns(T::Boolean) }
+    def retryable? = false
+  end
+
+  # Something went wrong with one list. Carries #source_id, so a caller
+  # rescuing a whole sync knows which publisher to name.
+  #
+  # Raised directly only where the failure fits none of the three below --
+  # a source adapter that declares no URL, a payload the publisher confirmed
+  # but would not serve.
+  class SourceError < StandardError
+    include Error
+  end
+
+  # The bytes could not be obtained: a timeout, a refused connection, a
+  # redirect chain that does not terminate, a status the caller declared fatal.
+  #
+  # Carries #status where a server produced one, and answers #retryable? from
+  # it. This is the error a host application backs off on, and the reason the
+  # predicate exists: 503 and 429 are the publisher having a bad afternoon,
+  # 403 and 404 are a request that will be just as wrong in ten minutes.
+  class FetchError < SourceError
+    extend T::Sig
+
+    # 408 and 429 are the server asking to be asked again; 5xx is it failing to
+    # answer at all. A 4xx outside those two 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.
+    #
+    # @api private
+    RETRYABLE_STATUSES = T.let(([408, 425, 429] + (500..599).to_a).freeze, T::Array[Integer])
+
+    sig { returns(T::Boolean) }
+    def retryable? = retryable_or(RETRYABLE_STATUSES.include?(status))
+  end
+
+  # The bytes arrived and could not be read as the format they were declared
+  # to be: an HTML error page served under a `.xml` URL, a truncated download,
+  # an encoding that cannot be decoded, a ZIP member that will not inflate.
+  #
+  # Distinct from a Parsers::Warning, which is one *row* that could not be read
+  # while the rest of the file could. A list is not a file we control, and
+  # refusing 19,321 records because one of them is malformed fails exactly when
+  # the list is most needed -- so a bad row is a warning, and only a payload
+  # that cannot be read at all raises this.
+  #
+  # ### Where
+  #
+  # A 25 MB XML payload that "is not XML" is not a diagnosable complaint, so
+  # this carries a locator whenever the parser can produce one:
+  #
+  #   rescue ActiveSanction::ParseError => e
+  #     e.line     # => 418_223
+  #     e.record   # => 12_004      (1-based, in the order the file yielded them)
+  #     e.offset   # => 8_388_608   (byte offset into the payload)
+  #     e.locator  # => "line 418223"
+  #
+  # All three are nil where the parser cannot say -- libxml2 reports no
+  # position for some failures, and a ZIP directory that ends inside an entry
+  # header has an offset but no line. An error that cannot point at a line
+  # still says what went wrong rather than pointing at the wrong one.
+  class ParseError < SourceError
+    extend T::Sig
+
+    # 1-based line within the payload, or nil.
+    sig { returns(T.nilable(Integer)) }
+    attr_reader :line
+
+    # 1-based index of the record being read, in the order the parser yielded
+    # them, or nil. The locator that means something for a format with no
+    # lines -- a spreadsheet, a stream of XML elements on one line.
+    sig { returns(T.nilable(Integer)) }
+    attr_reader :record
+
+    # Byte offset into the payload, or nil.
+    sig { returns(T.nilable(Integer)) }
+    attr_reader :offset
+
+    sig do
+      params(message: T.untyped, line: T.nilable(Integer), record: T.nilable(Integer), offset: T.nilable(Integer),
+             options: T.untyped).void
+    end
+    def initialize(message = nil, line: nil, record: nil, offset: nil, **options)
+      @line = T.let(line, T.nilable(Integer))
+      @record = T.let(record, T.nilable(Integer))
+      @offset = T.let(offset, T.nilable(Integer))
+      super(message, **options)
+    end
+
+    # Where in the payload, in the terms the parser could supply, or nil when
+    # it could supply none. Appended to #to_s -- and so to #message, which is
+    # defined in terms of it -- so a log line that records nothing but the
+    # message still says where.
+    sig { returns(T.nilable(String)) }
+    def locator
+      parts = []
+      parts << "line #{line}" if line
+      parts << "record #{record}" if record
+      parts << "byte #{offset}" if offset
+      parts.empty? ? nil : parts.join(", ")
+    end
+
+    sig { returns(String) }
+    def to_s
+      where = locator
+      where ? "#{super} (at #{where})" : super
+    end
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def to_h = super.merge({ line: line, record: record, offset: offset }.compact)
+  end
+
+  # The bytes are not what they claim to be: content that no longer hashes to
+  # the checksum stored beside it, a snapshot filed under one source that says
+  # it is another.
+  #
+  # Never repaired, and never answered with whatever could still be read. A
+  # store that hands back the 8,000 records it managed to parse out of 19,015
+  # produces a report that looks exactly like a clean one, which is the most
+  # expensive thing this library can get wrong. An operator can always discard
+  # the copy and re-sync; nobody can recover a screening decision made against
+  # a list that was quietly half there.
+  class IntegrityError < SourceError; end
+
+  # The store could not answer: a list that has never been synced, a snapshot
+  # written under a schema this version does not read, a validator file that
+  # is not readable as validators.
+  #
+  # About the *store* rather than about the publisher, which is the difference
+  # that matters when deciding what to do: a FetchError is somebody else's
+  # outage, and this is local state to repair or re-sync.
+  class StorageError < StandardError
+    include Error
+  end
+
+  # This object cannot do that: a backend without the capability asked for, an
+  # abstract method a subclass never implemented.
+  #
+  # A StandardError rather than the `NotImplementedError` that reads more
+  # naturally for the second case, deliberately. `NotImplementedError` is a
+  # ScriptError, so it is not caught by `rescue StandardError` -- and one
+  # adapter forgetting `#parse` would take down a sync run that is supposed to
+  # isolate each source's failure from the others, which is the run's single
+  # most important property.
+  class UnsupportedError < StandardError
+    include Error
+  end
+
+  # A public method was called with something it cannot use: a threshold of
+  # 300, a Snapshot whose `record_count` disagrees with its entities, a name
+  # value object built with no value.
+  #
+  # This is the "bug in my call" branch, and it is an `::ArgumentError` as well
+  # as an ActiveSanction::Error so that it reads as one to code that has never
+  # heard of this library. Messages are written for whoever has to fix the
+  # call, or the record: `"limit must be at least 1, got 0"` rather than a type
+  # name.
+  class InvalidArgument < ::ArgumentError
+    include Error
+  end
+
+  # A screening query that cannot be run: an empty `sources:` list, a threshold
+  # outside 0..100, a limit of zero, a field spelled two ways at once.
+  #
+  # Its own class because a query is user input in a way the rest of this is
+  # not -- it is frequently built from a form or an API request -- and a
+  # service turning a bad query into a 422 and a bad configuration into a 500
+  # should not have to tell them apart by reading messages.
+  class QueryError < InvalidArgument; end
+
+  # A field or column that does not exist, asked for by name: `row[:nmae]`, or
+  # a path into an XML record that no element supplies.
+  #
+  # A `::KeyError`, because it is what `Hash#fetch` raises and these methods
+  # are `fetch` in everything but name. Almost always a typo in an adapter
+  # rather than a question about the data, so the message lists what *is*
+  # there.
+  class MissingKey < ::KeyError
+    include Error
+  end
+end