active_sanction 1.0.1 → 1.1.1

data/lib/active_sanction/matcher.rb

@@ -6,6 +6,7 @@ require "sorbet-runtime"
 require "time"
 require "active_sanction/error"
 require "active_sanction/index"
+require "active_sanction/instrumentation"
 require "active_sanction/match_result"
 require "active_sanction/query"
 require "active_sanction/scorer"
@@ -131,6 +132,14 @@ module ActiveSanction
     sig { returns(Symbol) }
     attr_reader :backend
 
+    # Where the `:screen` event goes, or nil for nothing listening. Read once
+    # at construction and frozen with everything else here, which is the rule
+    # the class comment states for the whole query path: a subscriber swapped
+    # halfway through a batch cannot make half of it instrumented. See
+    # Instrumentation.
+    sig { returns(T.untyped) }
+    attr_reader :instrumenter
+
     class << self
       extend T::Sig
 
@@ -152,14 +161,29 @@ module ActiveSanction
       # covers all three, and both report the name clear.
       sig do
         params(store: T.untyped, sources: T.untyped, weights: T.untyped, candidate_limit: T.untyped,
-               backend: T.untyped).returns(Matcher)
+               backend: T.untyped, instrumenter: T.untyped).returns(Matcher)
       end
       def build(store = nil, sources: nil, weights: nil, candidate_limit: nil,
-                backend: MatchResult::DEFAULT_BACKEND)
+                backend: MatchResult::DEFAULT_BACKEND, instrumenter: nil)
         store ||= ActiveSanction.config.storage
+        listening = instrumenter.nil? ? ActiveSanction.config.instrumenter : instrumenter
+        built = Instrumentation.instrument(listening, :"index.build", { store: store.class.name }) do |event|
+          index_over(store, sources, event)
+        end
+        new(index: built.fetch(:index), snapshots: built.fetch(:checksums), verified: built.fetch(:attested),
+            weights: weights, candidate_limit: candidate_limit, backend: backend, instrumenter: listening)
+      end
+
+      private
+
+      # Every list this matcher will hold, read one at a time and released
+      # before the next is opened, and what it cost.
+      sig { params(store: T.untyped, sources: T.untyped, event: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+      def index_over(store, sources, event)
         builder = Index::Builder.new
         checksums = T.let({}, T::Hash[Symbol, String])
         attested = T.let([], T::Array[Symbol])
+        entities = 0
         requested(store, sources).each do |key|
           snapshot = store.fetch_snapshot(key)
           checksums[key] = snapshot.checksum
@@ -168,12 +192,27 @@ module ActiveSanction
           # different list.
           attested << key if snapshot.trusted?
           snapshot.entities.each { |entity| builder.add(entity) }
+          entities += snapshot.record_count
         end
-        new(index: builder.build, snapshots: checksums, verified: attested, weights: weights,
-            candidate_limit: candidate_limit, backend: backend)
+        index = builder.build
+        measure(event, index, checksums, entities)
+        { index: index, checksums: checksums, attested: attested }
       end
 
-      private
+      # What a host watches at boot and after every sync: how long an index
+      # took to build, how much of it there is, and roughly what it weighs.
+      # `bytes` is an estimate and says so -- see Index#profile, which is
+      # where the assumptions behind the number are written down, and where
+      # the entity count deliberately does not come from.
+      sig do
+        params(event: T.untyped, index: Index, checksums: T::Hash[Symbol, String], entities: Integer).void
+      end
+      def measure(event, index, checksums, entities)
+        event[:sources] = checksums.keys
+        event[:snapshots] = checksums
+        event[:entities] = entities
+        index.profile.each { |name, value| event[name] = value }
+      end
 
       # The lists to index, in a deterministic order, or the exception that
       # says why there are none.
@@ -204,10 +243,10 @@ module ActiveSanction
     # one name against several list versions, or a spec.
     sig do
       params(index: Index, snapshots: T.untyped, weights: T.untyped, candidate_limit: T.untyped,
-             backend: T.untyped, verified: T.untyped).void
+             backend: T.untyped, verified: T.untyped, instrumenter: T.untyped).void
     end
     def initialize(index:, snapshots:, weights: nil, candidate_limit: nil, backend: MatchResult::DEFAULT_BACKEND,
-                   verified: nil)
+                   verified: nil, instrumenter: nil)
       @index = index
       @snapshots = T.let(snapshots!(snapshots), T::Hash[Symbol, String])
       @verified = T.let(verified!(verified), T::Array[Symbol])
@@ -216,6 +255,7 @@ module ActiveSanction
       @weights = T.let(Scorer::Weights.build(weights), Scorer::Weights)
       @candidate_limit = T.let(candidate_limit!(candidate_limit), Integer)
       @backend = T.let(backend.to_s.to_sym, Symbol)
+      @instrumenter = T.let(instrumenter.nil? ? ActiveSanction.config.instrumenter : instrumenter, T.untyped)
       freeze
     end
 
@@ -303,13 +343,31 @@ module ActiveSanction
       # weights, one instant, one backend. Only the snapshot checksum varies,
       # and only because a run may cover several lists.
       stamp = { query: query, weights: weights, backend: backend, screened_at: screened_at }
-      scored(query)
-        .sort_by { |result| [-result.score, result.source.to_s, result.entity.id] }
-        .first(query.limit)
-        .map do |result|
-          MatchResult.from_scorer(result, snapshot_id: snapshots.fetch(result.source),
-                                          verified: verified.include?(result.source), **stamp)
-        end
+      Instrumentation.instrument(instrumenter, :screen) do |event|
+        results = scored(query, event)
+                  .sort_by { |result| [-result.score, result.source.to_s, result.entity.id] }
+                  .first(query.limit)
+                  .map do |result|
+                    MatchResult.from_scorer(result, snapshot_id: snapshots.fetch(result.source),
+                                                    verified: verified.include?(result.source), **stamp)
+                  end
+        describe(event, query, results)
+        results
+      end
+    end
+
+    # What one query cost and what it consulted. `snapshots` is the whole
+    # checksum map rather than a count, because the question an audit asks of
+    # a screening event is which list *versions* answered it -- the same
+    # question every MatchResult is stamped with, and the only one a result
+    # set of zero cannot answer for itself.
+    sig { params(event: T.untyped, query: Query, results: T::Array[MatchResult]).void }
+    def describe(event, query, results)
+      event[:results] = results.size
+      event[:threshold] = query.threshold
+      event[:limit] = query.limit
+      event[:sources] = query.sources || sources
+      event[:snapshots] = snapshots
     end
 
     # Every entity the index retrieved, scored once.
@@ -321,10 +379,11 @@ module ActiveSanction
     # retrieves the same record under several spellings, and rescoring one
     # that has already failed the threshold is the most expensive way to
     # arrive at the same no.
-    sig { params(query: Query).returns(T::Array[Scorer::Result]) }
-    def scored(query)
+    sig { params(query: Query, event: T.untyped).returns(T::Array[Scorer::Result]) }
+    def scored(query, event)
       seen = T.let({}, T::Hash[[Symbol, String], T.nilable(Scorer::Result)])
-      index.candidates(query.form, limit: candidate_limit, sources: query.sources).each do |candidate|
+      retrieved = index.candidates(query.form, limit: candidate_limit, sources: query.sources)
+      retrieved.each do |candidate|
         # Keyed by list as well as id, because the same person really is two
         # records when two governments list them, and both belong in a report.
         key = [candidate.source, candidate.entity.id]
@@ -332,6 +391,12 @@ module ActiveSanction
 
         seen[key] = Scorer.call(query.subject, candidate, weights: weights, threshold: query.threshold)
       end
+      # Names retrieved, and the entities they came down to. The two differ by
+      # however many aliases of one record the query looked like, and a
+      # candidate cap is a cap on the first rather than the second -- which is
+      # the number to watch when tuning it.
+      event[:candidates] = retrieved.size
+      event[:scored] = seen.size
       seen.values.compact
     end
 

data/lib/active_sanction/sources/base.rb

@@ -8,6 +8,7 @@ require "active_sanction/error"
 require "active_sanction/entity"
 require "active_sanction/snapshot"
 require "active_sanction/fetcher"
+require "active_sanction/instrumentation"
 require "active_sanction/parsers"
 require "active_sanction/payload_cache"
 require "active_sanction/sources"
@@ -82,17 +83,25 @@ module ActiveSanction
       sig { returns(T.untyped) }
       attr_reader :logger
 
+      # Where this adapter's `:parse` event goes, or nil for nothing
+      # listening. See Instrumentation.
+      sig { returns(T.untyped) }
+      attr_reader :instrumenter
+
       # `cache: nil` turns off payload caching, which costs one thing worth
       # knowing: a multi-file source can no longer answer a sync where some of
       # its files changed and others came back 304, so the unchanged ones are
       # downloaded again in full.
       sig do
-        params(fetcher: Fetcher, cache: T.nilable(PayloadCache), logger: T.untyped).void
+        params(fetcher: Fetcher, cache: T.nilable(PayloadCache), logger: T.untyped,
+               instrumenter: T.untyped).void
       end
-      def initialize(fetcher: Fetcher.new, cache: PayloadCache.new, logger: ActiveSanction.config.logger)
+      def initialize(fetcher: Fetcher.new, cache: PayloadCache.new, logger: ActiveSanction.config.logger,
+                     instrumenter: ActiveSanction.config.instrumenter)
         @fetcher = T.let(fetcher, Fetcher)
         @cache = T.let(cache, T.nilable(PayloadCache))
         @logger = T.let(logger, T.untyped)
+        @instrumenter = T.let(instrumenter, T.untyped)
         @results = T.let({}, T::Hash[Symbol, Fetcher::Result])
       end
 
@@ -137,6 +146,20 @@ module ActiveSanction
               "#{self.class} must implement #parse(raw) and return an Array of ActiveSanction::Entity"
       end
 
+      # What the last #parse could not read: a Parsers::Warning per row that
+      # was skipped or could not be mapped, kept rather than raised. Every
+      # shipped adapter overrides this with the parser's own warnings plus
+      # whatever it noticed itself, which is what the adapter rules require of
+      # a new one.
+      #
+      # Empty here rather than abstract, because an adapter that genuinely
+      # cannot fail to read a row should not have to say so, and because the
+      # `:parse` event counts these for every source and a count that is
+      # sometimes a NoMethodError is not a metric. See Doctor, which reads the
+      # warnings themselves rather than the count.
+      sig { returns(T::Array[Parsers::Warning]) }
+      def warnings = []
+
       # Fetches, parses, and checksums -- or returns nil when the publisher
       # says nothing has changed, which is the outcome to expect on most runs
       # and the reason conditional GET exists.
@@ -157,8 +180,15 @@ module ActiveSanction
       # or, for a source that declares a single file, as the bytes themselves.
       sig { params(payloads: T.untyped, files: T.untyped).returns(Snapshot) }
       def snapshot(payloads = nil, **files)
-        Snapshot.new(source: key, entities: parse(parse_argument(payloads || files)),
-                     fetched_at: Time.now.utc, source_version: source_version)
+        raw = parse_argument(payloads || files)
+        entities = Instrumentation.instrument(instrumenter, :parse,
+                                              { source: declared_key, bytes: byte_count(raw) }) do |event|
+          parsed = parse(raw)
+          event[:records] = parsed.size
+          event[:warnings] = warnings.size
+          parsed
+        end
+        Snapshot.new(source: key, entities: entities, fetched_at: Time.now.utc, source_version: source_version)
       rescue ActiveSanction::Error => e
         raise e.in_source(declared_key)
       end
@@ -250,7 +280,19 @@ module ActiveSanction
 
       sig { params(name: Symbol, address: String, force: T::Boolean).returns(Fetcher::Result) }
       def fetch_file(name, address, force)
-        fetcher.fetch(address, key: file_key(name), force: force).success!
+        fetcher.fetch(address, key: file_key(name), force: force, source: declared_key).success!
+      end
+
+      # How many bytes #parse was handed, across every file of a multi-file
+      # source. Taken before the parse rather than after, so the `:parse`
+      # event still says how large the document was when the parse is what
+      # raised.
+      sig { params(raw: T.untyped).returns(Integer) }
+      def byte_count(raw)
+        return raw.bytesize if raw.is_a?(String)
+        return raw.to_h.each_value.sum { |payload| payload.to_s.bytesize } if raw.respond_to?(:to_h)
+
+        raw.to_s.bytesize
       end
 
       sig { params(name: Symbol).returns(T.untyped) }
@@ -283,7 +325,7 @@ module ActiveSanction
       sig { params(name: Symbol).returns(Fetcher::Result) }
       def refetch(name)
         logger&.info("[active_sanction] #{key} #{name} unchanged but not cached; fetching in full")
-        result = fetcher.fetch(url(name), key: file_key(name), force: true).success!
+        result = fetcher.fetch(url(name), key: file_key(name), force: true, source: declared_key).success!
         return result if result.changed?
 
         raise MissingPayload,

data/lib/active_sanction/sync.rb

@@ -5,6 +5,7 @@ require "sorbet-runtime"
 
 require "uri"
 require "active_sanction/error"
+require "active_sanction/instrumentation"
 require "active_sanction/sources"
 require "active_sanction/storage"
 require "active_sanction/sync/result"
@@ -149,6 +150,17 @@ module ActiveSanction
     sig { returns(T.untyped) }
     attr_reader :logger
 
+    # Where the `:sync` and `:store` events go, or nil for nothing listening.
+    #
+    # The `:fetch` and `:parse` events of the sources this run covers do not
+    # come from here: an adapter is constructed by the run and reads the
+    # configuration, exactly as it does for its logger and its User-Agent. So
+    # a host that instruments through `ActiveSanction.configure` sees all six
+    # events, and one that hands a run its own instrumenter sees the two this
+    # class emits. See Instrumentation.
+    sig { returns(T.untyped) }
+    attr_reader :instrumenter
+
     sig { params(options: T.untyped, block: T.untyped).returns(Report) }
     def self.call(**options, &block) = T.unsafe(self).new(**options).call(&block)
 
@@ -157,9 +169,10 @@ module ActiveSanction
     # raises here, before the first list is downloaded, rather than after.
     sig do
       params(sources: T.untyped, store: T.untyped, force: T::Boolean, concurrency: T.untyped,
-             logger: T.untyped).void
+             logger: T.untyped, instrumenter: T.untyped).void
     end
-    def initialize(sources: nil, store: nil, force: false, concurrency: nil, logger: ActiveSanction.config.logger)
+    def initialize(sources: nil, store: nil, force: false, concurrency: nil, logger: ActiveSanction.config.logger,
+                   instrumenter: ActiveSanction.config.instrumenter)
       @sources = T.let(resolve(sources), T::Array[T.untyped])
       @keys = T.let(@sources.map { |source| Sources::Definition.key!(source.key) }, T::Array[Symbol])
       @store = T.let(store || ActiveSanction.storage, T.untyped)
@@ -168,6 +181,7 @@ module ActiveSanction
         Configuration.sync_concurrency!(concurrency || ActiveSanction.config.sync_concurrency), Integer
       )
       @logger = T.let(logger, T.untyped)
+      @instrumenter = T.let(instrumenter, T.untyped)
       @lock = T.let(Mutex.new, Mutex)
       # The settings this run was started under, so a worker thread reads them
       # rather than the default client's. A configuration is fiber-local and a
@@ -195,9 +209,17 @@ module ActiveSanction
       started_at = Time.now.utc
       began = monotonic
       log_start
-      work = keys.each_with_index.map { |key, at| [at, key, sources.fetch(at)] }
-      results = run(work, &block).sort_by(&:first).map(&:last)
-      report = Report.new(results: results, started_at: started_at, duration: elapsed(began))
+      # The run's own duration is the Report's, taken from the same clock
+      # reading, so an event and the report a caller is holding never disagree
+      # about how long a run took.
+      report = Instrumentation.instrument(instrumenter, :sync,
+                                          { sources: keys, forced: force, concurrency: concurrency }) do |event|
+        work = keys.each_with_index.map { |key, at| [at, key, sources.fetch(at)] }
+        results = run(work, &block).sort_by(&:first).map(&:last)
+        finished = Report.new(results: results, started_at: started_at, duration: elapsed(began))
+        summarize(event, finished)
+        finished
+      end
       log_finish(report)
       report
     end
@@ -285,13 +307,39 @@ module ActiveSanction
         snapshot = adapter.sync(force: force || previous.nil?)
         return complete(key, :unchanged, previous, started) if unchanged?(previous, snapshot)
 
-        store.write_snapshot(snapshot)
+        write(key, snapshot)
         complete(key, :updated, Storage::Meta.from_snapshot(snapshot), started)
       rescue StandardError => e
         complete(key, :failed, previous, started, stamp(key, e))
       end
     end
 
+    # Writes one list, and says what it cost. Separate from the rest of
+    # #sync_source so the `:store` event times the write and nothing else --
+    # a store that takes eleven seconds to persist 19,321 entities is a
+    # different operational problem from a publisher that takes eleven seconds
+    # to serve them, and a timing that covered both could not tell a host
+    # which one it had.
+    sig { params(key: Symbol, snapshot: T.untyped).void }
+    def write(key, snapshot)
+      fields = { source: key, snapshot_id: snapshot.checksum, entities: snapshot.record_count,
+                 store: store.class.name }
+      Instrumentation.instrument(instrumenter, :store, fields) { store.write_snapshot(snapshot) }
+    end
+
+    # What a run did, as counts rather than as the Report itself: a subscriber
+    # forwarding an event to a metrics backend wants numbers, and one that
+    # wants the whole report already has it as the return value of the call
+    # that emitted this.
+    sig { params(event: T.untyped, report: Report).void }
+    def summarize(event, report)
+      event[:outcomes] = report.results.to_h { |result| [result.source, result.status] }
+      event[:updated] = report.updated.size
+      event[:unchanged] = report.unchanged.size
+      event[:failed] = report.failed.size
+      event[:records] = report.record_count
+    end
+
     # A failure captured for a source names that source, even when it was
     # raised somewhere that could not know -- a store that will not open, an
     # adapter constructor. Only ever fills a blank; see Error#in_source.

data/lib/active_sanction/testing/sanction_source.rb

@@ -0,0 +1,234 @@
+# typed: ignore
+# frozen_string_literal: true
+
+# The contract every source adapter must satisfy, written once.
+#
+# Loaded by `require "active_sanction/testing"` -- see ActiveSanction::Testing,
+# which is where the entry point and the fixture root are documented.
+#
+#   RSpec.describe ActiveSanction::Sources::CanadaSema do
+#     it_behaves_like "a sanction source", fixture: "canada_sema/sema.xml"
+#   end
+#
+# A list its publisher splits across several files names each one, under the
+# keys the adapter declared its URLs with:
+#
+#   it_behaves_like "a sanction source",
+#                   fixture: { sdn: "ofac_sdn/SDN.CSV", alt: "ofac_sdn/ALT.CSV", add: "ofac_sdn/ADD.CSV" }
+#
+# Paths are relative to `spec/fixtures` -- or to whatever
+# `ActiveSanction::Testing.fixture_root` names, and an absolute path is taken
+# as it stands. The bytes reach #parse exactly as they were committed --
+# undecoded, so an adapter reading the Windows-1252 OFAC serves is held to
+# doing its own decoding rather than to being handed a String somebody already
+# fixed up.
+#
+# ### What this is for
+#
+# Everything downstream of an adapter -- storage, the diff between two syncs,
+# the index, the matcher, the report an examiner reads -- is written against
+# Entity and never against a list. That only holds if every adapter really
+# does produce the same shape, and "the same shape" is otherwise a paragraph
+# in a design document that each new adapter re-interprets. Here it is
+# executable, so adding a jurisdiction is a checklist rather than an open
+# research question.
+#
+# ### What it does not do
+#
+# It does not check that the adapter read its list *correctly*. Nothing here
+# knows that OFAC writes `-0-` for null, that the UN means two different
+# things by QUALITY, or which of the fixture's records is a vessel. Only a
+# spec that knows what is in the fixture can check that, so every adapter
+# still writes its own; this group is the floor, not the ceiling.
+#
+# ### Options
+#
+#   fixture:  required. A path under the fixture root, or a Hash of one path
+#             per declared URL. Real published records, not invented ones --
+#             a conformance run against a fixture somebody wrote to pass it
+#             proves nothing about the list.
+#
+#   remarks:  pass `remarks: false` for a list that publishes no free text of
+#             its own at all, so the check that the publisher's own words
+#             survive into `remarks` is skipped. Every list at launch does
+#             publish some, which is why the default is to require it: a
+#             remark quietly dropped is how a place of birth or a passport
+#             number stops reaching #19.
+RSpec.shared_examples "a sanction source" do |options = {}|
+  publishes_remarks = options.fetch(:remarks, true)
+
+  # Read through a `let` rather than closed over directly, so that a group
+  # that forgot to name a fixture says so when an example asks for one rather
+  # than while the suite is still loading.
+  let(:fixture) do
+    options.fetch(:fixture) do
+      raise ArgumentError, %(pass the fixture to parse: it_behaves_like "a sanction source", fixture: "list.xml")
+    end
+  end
+
+  let(:source) { described_class.new }
+  let(:payload) { fixture_payload(fixture) { |bytes| bytes } }
+  let(:records) { source.parse(payload) }
+
+  # Fixture bytes in the shape this adapter's #parse takes: the bytes
+  # themselves for a source declaring one file, a Hash keyed by declaration
+  # name for one declaring several. The same rule Base applies before calling
+  # #parse, so an adapter is exercised here exactly as `sync` exercises it.
+  def fixture_payload(paths)
+    bytes = named_fixtures(paths).to_h { |name, path| [name, yield(File.binread(fixture_path(path)))] }
+    described_class.multi_url? ? bytes : bytes.values.first
+  end
+
+  # One fixture path per declared file. A source declaring one file may name it
+  # as a bare path, which is what reading a fixture off disk looks like.
+  def named_fixtures(paths)
+    files = paths.is_a?(Hash) ? paths : { described_class.urls.keys.first => paths }
+    missing = described_class.urls.keys - files.keys
+    raise ArgumentError, "no fixture given for the #{missing.join(", ")} file(s) this source declares" if missing.any?
+
+    files
+  end
+
+  # Resolved through Testing rather than relative to this file, which is what
+  # lets the group work for a project whose fixtures are its own. See
+  # ActiveSanction::Testing.fixture_root.
+  def fixture_path(path) = ActiveSanction::Testing.fixture_path(path)
+
+  # Every date any entity carries, wherever the model puts them.
+  def entity_dates(entities)
+    entities.flat_map do |entity|
+      [entity.listed_on, *entity.dates_of_birth,
+       *entity.identifiers.flat_map { |identifier| [identifier.issued_on, identifier.expires_on] }]
+    end.compact
+  end
+
+  # The serialized records half the bytes produce, or the marker that reading
+  # them raised -- which is the other acceptable answer, and never equal to a
+  # complete parse.
+  def parsed_truncated(paths)
+    truncated = fixture_payload(paths) { |bytes| bytes[0, bytes.bytesize / 2] }
+    described_class.new.parse(truncated).map(&:to_h)
+  rescue ActiveSanction::Error
+    :raised
+  end
+
+  describe "what it declares" do
+    it "declares a key, which is the name the list answers to everywhere" do
+      expect(described_class.key.to_s).to match(ActiveSanction::Sources::Definition::KEY_PATTERN)
+    end
+
+    it "declares the jurisdiction behind the list" do
+      expect(described_class.jurisdiction).to be_a(Symbol)
+    end
+
+    it "declares the authority a compliance report has to print beside a hit" do
+      expect(described_class.authority).to be_a(String)
+    end
+
+    it "declares at least one URL to fetch the list from" do
+      expect(described_class.urls).not_to be_empty
+    end
+
+    # An adapter whose file is required but which never registers is invisible:
+    # `config.sources` cannot name it and `sync` will not run it, and nothing
+    # says so out loud.
+    it "registers itself, so requiring its file is enough to reach it" do
+      expect(ActiveSanction::Sources[described_class.key]).to eq(described_class)
+    end
+  end
+
+  describe "what #parse returns" do
+    it "builds at least one record from the fixture" do
+      expect(records).not_to be_empty
+    end
+
+    it "returns Entities and nothing else" do
+      expect(records).to all(be_an(ActiveSanction::Entity))
+    end
+
+    it "stamps every entity with this adapter's own key" do
+      expect(records.map(&:source).uniq).to eq([described_class.key])
+    end
+
+    it "gives every entity an id" do
+      expect(records.map(&:id)).to all(match(/\S/))
+    end
+
+    # A record with no name cannot be screened against, so it is not a record.
+    it "gives every entity at least one name" do
+      expect(records.reject { |record| record.names.any? }).to be_empty
+    end
+
+    # Types are the matcher's coarsest filter: a search for a person that can
+    # rank a ship is the failure this closes. Entity refuses anything else on
+    # construction, so this fails only for something that is not an Entity.
+    it "types every entity as one of the four canonical types" do
+      expect(records.map(&:type).uniq - ActiveSanction::Entity::TYPES).to be_empty
+    end
+
+    # Two records under one id are one record to storage, and the second
+    # silently replaces the first.
+    it "gives no two entities the same id" do
+      expect(records.map(&:id).tally.select { |_id, count| count > 1 }).to be_empty
+    end
+  end
+
+  # #35 diffs two syncs by comparing records under their ids. An id that moves
+  # because a Hash iterated differently, or because a counter was involved,
+  # reports the whole list as removed and re-added -- and a diff that says
+  # everything changed says nothing at all.
+  describe "reading the same bytes twice" do
+    it "produces the same ids" do
+      expect(described_class.new.parse(payload).map(&:id)).to eq(records.map(&:id))
+    end
+
+    it "produces the same records, in the same order" do
+      expect(described_class.new.parse(payload).map(&:to_h)).to eq(records.map(&:to_h))
+    end
+  end
+
+  describe "the canonical model it produces" do
+    # A date left as the publisher's string cannot be compared with one from
+    # another list, and PartialDate exists because none of these lists agree on
+    # how precise a date of birth is. Entity does not coerce, so an adapter
+    # that forgets is caught here rather than in the scorer.
+    it "publishes every date as a PartialDate, never as the string it was written as" do
+      expect(entity_dates(records)).to all(be_a(ActiveSanction::PartialDate))
+    end
+
+    # What storage (#24) does to every record on the way to disk and back.
+    it "round-trips every entity through the serialized form" do
+      expect(records.map { |record| ActiveSanction::Entity.from_h(record.to_h) }).to eq(records)
+    end
+
+    if publishes_remarks
+      # The publisher's own prose is where the fields the canonical model has
+      # no home for still live -- OFAC's dates of birth and passport numbers
+      # are nowhere else -- so an adapter that drops it loses data no later
+      # issue can get back.
+      it "keeps the publisher's own text in remarks" do
+        expect(records.filter_map { |record| ActiveSanction::Sources::Remarks.published(record.remarks) })
+          .not_to be_empty
+      end
+    end
+  end
+
+  describe "a payload that is not the list" do
+    # No sanctions list has ever been empty, so an empty payload is a failed
+    # download, a moved URL or an outage -- never a day on which nobody is
+    # sanctioned. Returning [] lets a sync succeed at screening against
+    # nothing, which is the most expensive way this library can fail.
+    it "refuses an empty payload rather than reporting a list with nobody on it" do
+      expect { described_class.new.parse(fixture_payload(fixture) { "" }) }
+        .to raise_error(ActiveSanction::Error)
+    end
+
+    # A truncated download may still be worth salvaging -- the XML toolkit
+    # keeps the records it read before the break and warns -- so what is
+    # required is not that it raises, only that half a list never comes back
+    # looking exactly like the whole one.
+    it "does not report a truncated document as though it were the whole list" do
+      expect(parsed_truncated(fixture)).not_to eq(records.map(&:to_h))
+    end
+  end
+end