active_sanction 1.0.0

data/lib/active_sanction/snapshot/bundle.rb

@@ -0,0 +1,381 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "json"
+require "active_sanction/entity"
+require "active_sanction/error"
+require "active_sanction/snapshot"
+require "active_sanction/sources"
+require "active_sanction/version"
+
+module ActiveSanction
+  class Snapshot
+    # One list, in one file, that another machine can load and trust without
+    # ever reaching the publisher.
+    #
+    #   File.open("ofac_sdn.asb", "wb") do |io|
+    #     ActiveSanction::Snapshot::Bundle.write(snapshot, io: io, sign_with: private_key)
+    #   end
+    #
+    #   File.open("ofac_sdn.asb", "rb") do |io|
+    #     snapshot = ActiveSanction::Snapshot::Bundle.read(io, verify_with: public_key)
+    #     snapshot.trusted?   # => true
+    #   end
+    #
+    # `ActiveSanction.export` and `.import` are the sugar over this that most
+    # applications want; this is the format itself, and it is public API. The
+    # byte-level specification is docs/bundle_format.md, which is written so
+    # that a bundle can be produced and read by something that is not this gem
+    # and not Ruby.
+    #
+    # ### Why a file, when there is already a store
+    #
+    # Storage::FileSystem writes gzipped JSON too, and its layout is explicitly
+    # private and expected to change. This is the opposite thing: a published
+    # artifact with a stability contract, which three situations need and a
+    # directory cannot serve.
+    #
+    # - **Publishers go down.** OFAC breaks, changes format, and rate-limits. A
+    #   bundle produced once and copied is the difference between a bad
+    #   afternoon at Treasury and a failed deploy for everyone downstream.
+    # - **Air-gapped and privacy-sensitive installations.** A compliance team
+    #   that will not send subject names to a third-party API will happily
+    #   consume fresh data. Only a file serves them.
+    # - **Audit.** A checksum proves a list is internally intact. A signature
+    #   proves it is *the one that was published*, which is the claim an
+    #   examiner is actually asking about.
+    #
+    # ### The shape of a bundle
+    #
+    #     ACTIVESANCTION-BUNDLE/1\n     magic, and the format version
+    #     {"format_version":1,...}\n    one canonical line -- see Header
+    #     ecdsa-sha256 MEUCIQ...\n      or "-" -- see Signature
+    #     <deflated NDJSON>             to EOF -- see Payload
+    #
+    # The first three lines are text on purpose: `head -c 512` on a bundle tells
+    # an operator what list it holds, how many records, from when, and who says
+    # so, without a tool and without decompressing anything.
+    #
+    # ### Determinism
+    #
+    # Two writes of one snapshot produce one file. Records are ordered by the
+    # fingerprint Snapshot's own checksum is built from rather than by whatever
+    # order a publisher's file happened to arrive in, the header's keys have a
+    # fixed order, the compression level is named by the specification rather
+    # than taken from a build's default, and there is deliberately no
+    # written-at timestamp anywhere in the file.
+    #
+    # What that buys is comparability: two mirrors that bundled the same
+    # snapshot can be held against each other byte for byte. The invariant that
+    # survives everything, including a zlib that packs differently, is the
+    # header line -- it pins the content, through `payload_digest`, and the
+    # provenance. A signature line is the one part that may differ between two
+    # signings, because ECDSA is randomized.
+    #
+    # ### What it refuses to do
+    #
+    # Return anything it cannot prove, on the same rule the stores follow. A
+    # flipped byte, a truncated download and an edited record all raise Corrupt
+    # rather than screening against a list that is quietly missing somebody. A
+    # format version from a newer gem raises UnsupportedFormat *before* the
+    # payload is touched, because a newer shape will usually deserialize into
+    # plausible, wrong records. And a snapshot only comes back `trusted?` when a
+    # key was supplied and the signature verified under it.
+    module Bundle
+      extend T::Sig
+      extend T::Helpers
+
+      # Called as `Bundle.read` -- module functions on a module, which is an
+      # Object, which is where `raise` comes from.
+      requires_ancestor { Kernel }
+
+      # Bumped when the container changes shape. Readers refuse anything above
+      # what they know rather than guessing, which is the whole reason it is on
+      # the first line of the file.
+      #
+      # @api private
+      FORMAT_VERSION = T.let(1, Integer)
+
+      # Formats this code can read. A bundle below the version it writes still
+      # round-trips; one above it does not, and says so.
+      #
+      # @api private
+      READABLE_FORMAT_VERSIONS = T.let(1..FORMAT_VERSION, T::Range[Integer])
+
+      # Snapshot schemas this code can read, held to the same range
+      # Storage::FileSystem holds a stored list to.
+      #
+      # @api private
+      READABLE_SCHEMA_VERSIONS = T.let(1..Snapshot::SCHEMA_VERSION, T::Range[Integer])
+
+      # @api private
+      MAGIC = T.let("ACTIVESANCTION-BUNDLE", String)
+
+      # @api private
+      MAGIC_PATTERN = T.let(%r{\A#{MAGIC}/(\d+)\z}, Regexp)
+
+      # The conventional extension, and what the CLI-shaped helpers default to.
+      #
+      # @api private
+      EXTENSION = T.let(".asb", String)
+
+      # How the records are laid out, and how they are packed. Named in the
+      # header of every bundle so that a v1 reader can refuse a v1 file that
+      # uses something it has never heard of, rather than misreading it.
+      #
+      # @api private
+      ENCODING = T.let("ndjson", String)
+      # @api private
+      COMPRESSION = T.let("deflate", String)
+
+      # The longest any of the three text lines may be. A malformed file must
+      # not be read as one 400 MB line before anything notices it is malformed.
+      #
+      # @api private
+      MAX_LINE_BYTES = T.let(64 * 1024, Integer)
+
+      # This bundle is not what it says it is: it does not begin like a bundle,
+      # it stops in the middle, its records no longer hash to the digest in its
+      # header, or it holds a different number of them than it claims.
+      #
+      # Never repaired and never partially returned, for the reason IntegrityError
+      # exists: a list that is quietly half there produces a report that looks
+      # exactly like a clean one.
+      class Corrupt < IntegrityError; end
+
+      # This bundle is intact, and somebody other than the expected publisher
+      # signed it. Deliberately a different error from Corrupt: "these bytes
+      # were damaged" and "these bytes came from somewhere else" are different
+      # incidents, and only one of them is fixed by downloading the file again.
+      class UntrustedSignature < IntegrityError; end
+
+      # Verification was asked for and there is no signature to verify. A
+      # subclass, so `rescue UntrustedSignature` covers both, while an operator
+      # can still tell "our publisher did not sign this" from "somebody else
+      # did".
+      class Unsigned < UntrustedSignature; end
+
+      # A bundle written under a format version, a snapshot schema or a payload
+      # encoding this code does not know -- almost always because it was written
+      # by a newer active_sanction.
+      #
+      # Separate from Corrupt because the file is fine and the fix is different:
+      # upgrade the gem. Raised before the payload is read, for the reason
+      # Storage::UnsupportedSchema is raised before a stored list is parsed.
+      class UnsupportedFormat < StorageError; end
+
+      module_function
+
+      # Writes `snapshot` to `io` and returns the Header it wrote.
+      #
+      #   Bundle.write(snapshot, io: io)                        # unsigned, and fully usable
+      #   Bundle.write(snapshot, io: io, sign_with: key)        # OpenSSL::PKey, or a PEM
+      #   Bundle.write(snapshot, io: io, generator: "acme/2.0") # whose bundle this is
+      #
+      # `generator` is the one field a publisher other than this gem should set.
+      # It is who published the file; `gem_version`, which is not overridable,
+      # is what serialized the records.
+      sig do
+        params(snapshot: T.untyped, io: T.untyped, sign_with: T.untyped, generator: T.untyped).returns(Header)
+      end
+      def write(snapshot, io:, sign_with: nil, generator: nil)
+        stored = snapshot!(snapshot)
+        payload, digest, bytes = Payload.pack(records(stored))
+        header = Header.from_snapshot(stored, payload_digest: digest, payload_bytes: bytes, generator: generator)
+        line = header.to_line
+        io.binmode if io.respond_to?(:binmode)
+        io.write("#{MAGIC}/#{FORMAT_VERSION}\n", "#{line}\n", "#{Signature.sign(line, sign_with)}\n", payload)
+        header
+      end
+
+      # Reads a bundle, verifying it as it goes, and returns the Snapshot.
+      #
+      #   Bundle.read(io)                     # => Snapshot, trusted? false
+      #   Bundle.read(io, verify_with: key)   # => Snapshot, trusted? true, or an exception
+      #
+      # Without `verify_with:` the signature is not looked at: an unsigned
+      # bundle is a first-class bundle, and a signed one read without a key is
+      # exactly as useful as an unsigned one -- its records are still proven
+      # against the digest in its header and against the snapshot checksum.
+      # What it is not is attested, and `trusted?` says so.
+      #
+      # With a key, the signature is checked **before a byte of the payload is
+      # inflated**. Compressed data from a party that has not authenticated is
+      # the last thing anybody should expand.
+      sig { params(io: T.untyped, verify_with: T.untyped).returns(Snapshot) }
+      def read(io, verify_with: nil)
+        io.binmode if io.respond_to?(:binmode)
+        version = magic!(io)
+        line = line!(io, "header")
+        header = supported!(parse!(line), version)
+        trusted = verified!(line!(io, "signature"), line, verify_with)
+        build(header, entities(io, header), trusted)
+      end
+
+      # What a bundle says about itself, without reading its records:
+      #
+      #   header = File.open(path, "rb") { |io| Bundle.header(io) }
+      #   header.record_count       # => 19015
+      #   header.snapshot_checksum  # => "sha256:9f86d081884c7d65..."
+      #
+      # Storage::Meta's job for a file somebody sent you, and cheap for the same
+      # reason: deciding whether a 25 MB bundle holds a list you already have
+      # should cost a few hundred bytes.
+      sig { params(io: T.untyped).returns(Header) }
+      def header(io)
+        io.binmode if io.respond_to?(:binmode)
+        version = magic!(io)
+        supported!(parse!(line!(io, "header")), version)
+      end
+
+      # The records of a snapshot, in the order a bundle lays them out.
+      #
+      # Sorted by the fingerprint Snapshot's checksum is built from, so that two
+      # snapshots holding the same entities in the order two publishers happened
+      # to emit them produce identical files -- and so that the order of a
+      # payload and the meaning of a checksum can never drift apart. Serializing
+      # each entity twice, once to fingerprint it and once to write it, is what
+      # one definition of "the fingerprint of an entity" costs; an export is not
+      # a hot path.
+      sig { params(snapshot: Snapshot).returns(T::Array[String]) }
+      def records(snapshot)
+        snapshot.entities
+                .sort_by { |entity| Snapshot.fingerprint(entity) }
+                .map { |entity| JSON.generate(entity.to_h) }
+      end
+
+      # The format version off the first line, checked before anything else in
+      # the file is looked at.
+      sig { params(io: T.untyped).returns(Integer) }
+      def magic!(io)
+        match = MAGIC_PATTERN.match(line!(io, "magic"))
+        raise Corrupt, "this is not an active_sanction bundle: it does not begin with #{MAGIC}/<version>" if match.nil?
+
+        version = Integer(T.must(match[1]))
+        return version if READABLE_FORMAT_VERSIONS.cover?(version)
+
+        raise UnsupportedFormat, format_message(version)
+      end
+
+      sig { params(line: String).returns(Header) }
+      def parse!(line)
+        Header.parse(line)
+      rescue JSON::ParserError, ArgumentError, TypeError, Sources::DeclarationError => e
+        raise Corrupt, "this bundle's header cannot be read (#{e.message})"
+      end
+
+      # Everything about a header that decides whether this code may read the
+      # payload at all. All of it happens before the payload is touched.
+      sig { params(header: Header, version: Integer).returns(Header) }
+      def supported!(header, version)
+        if header.format_version != version
+          raise Corrupt, "this bundle is labelled #{MAGIC}/#{version} and its header says format_version " \
+                         "#{header.format_version}. The two have to agree -- only one of them is signed"
+        end
+        raise UnsupportedFormat, schema_message(header) unless READABLE_SCHEMA_VERSIONS.cover?(header.schema_version)
+        raise UnsupportedFormat, payload_message(header) unless readable_payload?(header)
+
+        header
+      end
+
+      sig { params(header: Header).returns(T::Boolean) }
+      def readable_payload?(header)
+        header.payload_encoding == ENCODING && header.payload_compression == COMPRESSION
+      end
+
+      # Whether this bundle was proven to come from the holder of `key`, or the
+      # exception that says why it was not. False -- rather than an exception --
+      # only when no key was given, which is the caller saying they do not care.
+      sig { params(signature: String, header_line: String, key: T.untyped).returns(T::Boolean) }
+      def verified!(signature, header_line, key)
+        return false if key.nil?
+
+        Signature.verify!(signature, header_line, key)
+      end
+
+      # The records, streamed, held against everything the header promised
+      # about them.
+      sig { params(io: T.untyped, header: Header).returns(T::Array[T.untyped]) }
+      def entities(io, header)
+        built = T.let([], T::Array[T.untyped])
+        digest, bytes = Payload.unpack(io, limit: header.payload_bytes) { |record| built << entity!(record) }
+        unless digest == header.payload_digest && bytes == header.payload_bytes
+          raise Corrupt, digest_message(header, digest, bytes)
+        end
+
+        built
+      end
+
+      sig { params(record: String).returns(T.untyped) }
+      def entity!(record)
+        Entity.from_h(JSON.parse(record))
+      rescue JSON::ParserError, ArgumentError, TypeError, KeyError => e
+        raise Corrupt, "a record in this bundle cannot be read (#{e.message})"
+      end
+
+      # The snapshot itself, which re-derives its own checksum over the records
+      # that actually arrived and refuses to be built if it does not match the
+      # one in the header. The same defence a store relies on, applied to a file
+      # that came from somebody else.
+      sig { params(header: Header, entities: T::Array[T.untyped], trusted: T::Boolean).returns(Snapshot) }
+      def build(header, entities, trusted)
+        Snapshot.new(source: header.source, entities: entities, fetched_at: header.fetched_at,
+                     checksum: header.snapshot_checksum, record_count: header.record_count,
+                     schema_version: header.schema_version, source_version: header.source_version,
+                     trusted: trusted)
+      rescue Snapshot::ChecksumMismatch, InvalidArgument => e
+        raise Corrupt, "this bundle does not hold the list its header describes (#{e.message})"
+      end
+
+      # One line of the container, refused rather than read without limit.
+      sig { params(io: T.untyped, what: String).returns(String) }
+      def line!(io, what)
+        line = io.gets("\n", MAX_LINE_BYTES)
+        raise Corrupt, "this bundle ends before its #{what} line" if line.nil? || line.empty?
+        raise Corrupt, "this bundle's #{what} line is longer than #{MAX_LINE_BYTES} bytes" unless line.end_with?("\n")
+
+        line.chomp.force_encoding(Encoding::UTF_8)
+      end
+
+      sig { params(value: T.untyped).returns(Snapshot) }
+      def snapshot!(value)
+        return value if value.is_a?(Snapshot)
+
+        raise InvalidArgument, "Bundle.write takes an ActiveSanction::Snapshot, got #{value.class}"
+      end
+
+      sig { params(version: Integer).returns(String) }
+      def format_message(version)
+        "this bundle is written in bundle format version #{version}; active_sanction #{VERSION} reads " \
+          "#{READABLE_FORMAT_VERSIONS.first}-#{READABLE_FORMAT_VERSIONS.last}. Upgrade the gem -- nothing here " \
+          "can read it partially, and a format this code guessed at would produce a list nobody could defend"
+      end
+
+      sig { params(header: Header).returns(String) }
+      def schema_message(header)
+        "this bundle holds records written under snapshot schema_version #{header.schema_version} by " \
+          "#{header.generator}; active_sanction #{VERSION} reads #{READABLE_SCHEMA_VERSIONS.first}-" \
+          "#{READABLE_SCHEMA_VERSIONS.last}. Upgrade the gem, or ask the publisher for a bundle this old"
+      end
+
+      sig { params(header: Header).returns(String) }
+      def payload_message(header)
+        "this bundle's payload is #{header.payload_encoding}/#{header.payload_compression}; active_sanction " \
+          "#{VERSION} reads #{ENCODING}/#{COMPRESSION}. Upgrade the gem"
+      end
+
+      sig { params(header: Header, digest: String, bytes: Integer).returns(String) }
+      def digest_message(header, digest, bytes)
+        "this bundle's records hash to #{digest} over #{bytes} bytes, not the #{header.payload_digest} over " \
+          "#{header.payload_bytes} its header declares. The file was damaged in transit or edited after it was " \
+          "written -- fetch it again rather than screening against it"
+      end
+    end
+  end
+end
+
+require "active_sanction/snapshot/bundle/header"
+require "active_sanction/snapshot/bundle/payload"
+require "active_sanction/snapshot/bundle/signature"

data/lib/active_sanction/snapshot.rb

@@ -0,0 +1,305 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "digest"
+require "json"
+require "time"
+require "active_sanction/error"
+require "active_sanction/entity"
+
+module ActiveSanction
+  # One source's entities as they stood at one moment, with a checksum over
+  # their content. This is the unit of persistence (#24) and the anchor for
+  # reproducibility.
+  #
+  #   ActiveSanction::Snapshot.new(
+  #     source:         :ofac_sdn,
+  #     entities:       [Entity, ...],
+  #     fetched_at:     Time.now.utc,
+  #     source_version: "2026-08-28"   # the publisher's own date, if it gives one
+  #   )
+  #
+  # A screening decision has to be reproducible months later, in front of an
+  # examiner. MatchResult (#33) stamps `checksum` onto every result, so "why
+  # did we clear this customer on 5 Jan" is answered by reloading the exact
+  # list version that was screened against. Without that the library produces
+  # unauditable results.
+  #
+  # Instances are frozen on construction and compare by value.
+  class Snapshot
+    extend T::Sig
+
+    # Raised when a stored snapshot's content no longer hashes to the checksum
+    # stored beside it: the file is corrupt, was edited, or was written by a
+    # serializer this version does not agree with. Never silently repaired --
+    # a snapshot that cannot prove what it contains cannot anchor an audit.
+    class ChecksumMismatch < IntegrityError; end
+
+    # Bumped whenever the serialized form changes shape. Stored snapshots carry
+    # the version they were written under so they can be migrated or discarded
+    # rather than silently misread; it is folded into the checksum, so content
+    # that means one thing under v1 and another under v2 cannot collide.
+    #
+    # v2 added Entity#dates_of_birth, which the UN adapter (#21) needed and the
+    # canonical model had no slot for.
+    #
+    # @api private
+    SCHEMA_VERSION = T.let(2, Integer)
+
+    # Canonical member order, matching the layout #to_h must produce.
+    #
+    # @api private
+    MEMBERS = T.let(
+      %i[source entities fetched_at checksum record_count schema_version source_version].freeze,
+      T::Array[Symbol]
+    )
+
+    # @api private
+    ALGORITHM = T.let("sha256", String)
+
+    sig { returns(Symbol) }
+    attr_reader :source
+
+    # Deliberately not `T::Array[Entity]`, and the one member of the canonical
+    # model that is not declared. The storage conformance group builds a
+    # snapshot out of half-deserialized hashes on purpose, to prove it catches
+    # a store that hands them back that way (#24); #entities! below states the
+    # real contract -- anything that serializes -- in a message written for
+    # whoever has to fix the adapter. An element type would raise a TypeError
+    # there instead, one layer too early to say anything useful.
+    sig { returns(T::Array[T.untyped]) }
+    attr_reader :entities
+
+    # UTC, truncated to the second, which is the precision #to_h serializes.
+    sig { returns(Time) }
+    attr_reader :fetched_at
+
+    # `sha256:` and 64 hex digits, over the content and nothing else.
+    sig { returns(String) }
+    attr_reader :checksum
+
+    sig { returns(Integer) }
+    attr_reader :record_count
+
+    sig { returns(Integer) }
+    attr_reader :schema_version
+
+    # The publisher's own version string where it gives one, which is not
+    # something every list does.
+    sig { returns(T.nilable(String)) }
+    attr_reader :source_version
+
+    # Rebuilds a snapshot from #to_h output, verifying the checksum as it goes.
+    # Accepts string keys, so a snapshot survives the round-trip through
+    # gzipped JSON that storage (#24) puts it through.
+    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 Snapshot attribute(s): #{unknown.join(", ")}" if unknown.any?
+
+      attributes[:entities] &&= attributes[:entities].map { |value| build_entity(value) }
+      # `new(**hash)` past required keyword parameters is one of the few things
+      # Sorbet cannot check statically. #initialize validates what arrives --
+      # including, here, the checksum -- which is where a bad round-trip is
+      # caught.
+      T.unsafe(self).new(**attributes)
+    end
+
+    # Entities that are already objects pass through untouched, so from_h is
+    # safe to call on a half-deserialized hash.
+    sig { params(value: T.untyped).returns(T.untyped) }
+    def self.build_entity(value)
+      value.is_a?(Hash) ? Entity.from_h(value) : value
+    end
+    private_class_method :build_entity
+
+    # The content address of one entity: the SHA-256 of its serialized form.
+    #
+    # What #checksum is built out of, and what the bundle format (#57) sorts a
+    # payload by -- one definition rather than two, because an order that
+    # disagreed with the checksum's would be reproducible in a way nothing here
+    # could check.
+    #
+    # @api private
+    sig { params(entity: T.untyped).returns(String) }
+    def self.fingerprint(entity) = Digest::SHA256.hexdigest(JSON.generate(entity.to_h))
+
+    # `checksum` and `record_count` are derived, not supplied. Passing them --
+    # which is what .from_h does with a stored snapshot -- asserts what the
+    # content should be, and construction fails if it is not.
+    sig do
+      params(source: T.untyped, entities: T.untyped, fetched_at: T.untyped, checksum: T.untyped,
+             record_count: T.untyped, schema_version: T.untyped, source_version: T.untyped,
+             trusted: T.untyped).void
+    end
+    def initialize(source:, entities:, fetched_at: nil, checksum: nil, record_count: nil,
+                   schema_version: SCHEMA_VERSION, source_version: nil, trusted: false)
+      @source = T.let(symbol!(:source, source), Symbol)
+      @entities = T.let(entities!(entities), T::Array[T.untyped])
+      @fetched_at = T.let(time!(fetched_at), Time)
+      @schema_version = T.let(version!(schema_version), Integer)
+      @source_version = T.let(string_or_nil(source_version), T.nilable(String))
+      @record_count = T.let(count!(record_count), Integer)
+      @checksum = T.let(checksum!(checksum), String)
+      @trusted = T.let(trusted == true, T::Boolean)
+      freeze
+    end
+
+    sig { returns(T::Boolean) }
+    def empty? = entities.empty?
+
+    # Whether this snapshot's *provenance* was verified: it came out of a
+    # bundle (#57) whose signature checked out under a public key the caller
+    # supplied. False for everything else, including a list this process
+    # fetched itself -- a sync proves that bytes parsed, not who published
+    # them.
+    #
+    # ### Why it is not a member
+    #
+    # It is out of MEMBERS, out of #to_h, out of the checksum and out of
+    # equality, because it is not a fact about the content. Two snapshots
+    # holding the same entities are the same list version whether or not one
+    # of them arrived signed, and a checksum that said otherwise would report
+    # a new list every time somebody imported one.
+    #
+    # ### It does not survive storage
+    #
+    #   store.write_snapshot(bundle_snapshot)
+    #   store.read_snapshot(:ofac_sdn).trusted?   # => false
+    #
+    # Deliberately, and it is the honest answer. A signature attests to the
+    # bytes of a bundle file; once those entities have been rewritten into a
+    # store's own gzipped JSON or its own table, nothing signed covers what is
+    # on disk, and a stored flag claiming otherwise would be the library
+    # laundering an attestation it no longer holds. What a store guarantees is
+    # its own -- the checksum, re-derived on every read.
+    #
+    # So a process that wants `MatchResult#verified?` to be true keeps the
+    # bundle's snapshot in memory: Storage::Memory holds the object it was
+    # given, and Matcher reads this off the very snapshot it indexed.
+    sig { returns(T::Boolean) }
+    def trusted? = @trusted
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def to_h
+      {
+        source: source,
+        entities: entities.map(&:to_h),
+        fetched_at: fetched_at.iso8601,
+        checksum: checksum,
+        record_count: record_count,
+        schema_version: schema_version,
+        source_version: source_version
+      }
+    end
+
+    # Two fetches of an unchanged list are the same snapshot with different
+    # timestamps, and the checksum is what says so; equality follows it rather
+    # than #to_h so a re-fetch does not read as a new list version.
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def ==(other)
+      return false unless other.instance_of?(self.class)
+
+      checksum == other.checksum
+    end
+    alias eql? ==
+
+    sig { returns(Integer) }
+    def hash
+      [self.class, checksum].hash
+    end
+
+    sig { returns(String) }
+    def inspect
+      "#<#{self.class} #{source} #{record_count} entities #{checksum} " \
+        "fetched_at=#{fetched_at.iso8601}#{" verified" if trusted?}>"
+    end
+
+    private
+
+    # Order is a fact about how a publisher happened to emit its file, not
+    # about what the file says, so each entity is digested on its own and the
+    # digests are sorted before being folded together. Duplicates survive that
+    # -- an entity listed twice hashes to two identical fingerprints -- and
+    # changing any field of any entity changes exactly one of them.
+    #
+    # `fetched_at` and `source_version` stay out: this is a checksum of
+    # content, and refetching an unchanged list has to reproduce it or it
+    # cannot answer "has this list changed since we last screened?".
+    sig { returns(String) }
+    def compute_checksum
+      digest = Digest::SHA256.new
+      digest << "#{schema_version}\n#{source}\n"
+      entities.map { |entity| Snapshot.fingerprint(entity) }
+              .sort
+              .each { |fingerprint| digest << fingerprint << "\n" }
+      -"#{ALGORITHM}:#{digest.hexdigest}"
+    end
+
+    sig { params(supplied: T.untyped).returns(String) }
+    def checksum!(supplied)
+      computed = compute_checksum
+      return computed if supplied.nil? || supplied.to_s == computed
+
+      raise ChecksumMismatch,
+            "#{source} snapshot content hashes to #{computed}, not the stored #{supplied} " \
+            "(schema_version #{schema_version})"
+    end
+
+    sig { params(value: T.untyped).returns(T::Array[T.untyped]) }
+    def entities!(value)
+      raise InvalidArgument, "entities must be an Array" unless value.is_a?(Array)
+
+      value.each do |entity|
+        raise InvalidArgument, "entities must respond to #to_h, got #{entity.class}" unless entity.respond_to?(:to_h)
+      end
+      value.dup.freeze
+    end
+
+    sig { params(value: T.untyped).returns(Integer) }
+    def count!(value)
+      return entities.size if value.nil? || value.to_i == entities.size
+
+      raise InvalidArgument, "record_count #{value} does not match the #{entities.size} entities given"
+    end
+
+    # Truncated to the second, which is the precision #to_h serializes, so a
+    # stored snapshot reloads to a value equal to the one that was written.
+    sig { params(value: T.untyped).returns(Time) }
+    def time!(value)
+      time = case value
+             when nil then Time.now
+             when Time then value
+             when String then Time.parse(value)
+             else raise InvalidArgument, "fetched_at is not a time: #{value.inspect}"
+             end
+      Time.at(time.to_i).utc
+    end
+
+    sig { params(value: T.untyped).returns(Integer) }
+    def version!(value)
+      integer = Integer(value)
+      raise InvalidArgument, "schema_version must be positive, got #{integer}" unless integer.positive?
+
+      integer
+    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)
+      return nil if value.nil?
+
+      string = value.to_s.strip
+      string.empty? ? nil : -string
+    end
+  end
+end