active_sanction 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffb2d77bf3207e3ef97a16269dcf91737e20d48871cc2aec9e747d4185793e52
-  data.tar.gz: eeca2cf2bb69972d83e15e982c2daea80969a636e4c88e86cbd29b670420098c
+  metadata.gz: ecdae0214290d15cba0bf24838c8e4d2d2e004eaecb344c29aaa8c07d54da36b
+  data.tar.gz: c72d3f5baa535d081aae672de2013585e38c85c1cceb5c2a697d6cecc7d5f98a
 SHA512:
-  metadata.gz: 748d59d2d06bb502eefd684a71c1abc74beb6b03d677eaf9a85c4563945c03fb7c9d69474988319d0ef1f03d4a68c328efd7d63ad14a62d33fa74ef4989e361b
-  data.tar.gz: dc9c4247f9e3ce24772a8045c4e7e0ea992ae7fbeb17c8f2f123f8a9ccf39fd741d7617a98cd67eef5968a16811c2cfc1b42a0c433df3da94d3b8e4f3f624f40
+  metadata.gz: 5fc3e4e17279f0220f903792d952d4aa1adfa1068504512f51cbacb2247cc4ae71710b38c4de6374810e0c48bcc03052a7149eff9a69dda9ebc02389e27c8f05
+  data.tar.gz: 34df5f7d1103073a4bd50956abc77e1e87a9a3c5a213be9c18a46a6e41ccbdd5db64fcf0c7b7437d4c52e33f6876ea581ba57e04a44baa95d3ecec1666a8e315

data/CHANGELOG.md

@@ -17,6 +17,61 @@ screening decision would come out as today.
 
 Nothing yet.
 
+## [1.1.1] - 2026-09-14
+
+### Added
+
+- **The conformance groups ship** (#144). `require "active_sanction/testing"` loads the two
+  shared example groups that define what a source adapter and a storage adapter must do, so
+  an adapter written in your own application is held to the same contract the built-in ones
+  are:
+
+  ```ruby
+  # spec/spec_helper.rb
+  require "active_sanction/testing"
+
+  # spec/internal_watchlist_spec.rb
+  RSpec.describe MyCompany::InternalWatchlist do
+    it_behaves_like "a sanction source", fixture: "internal_watchlist/list.csv"
+  end
+  ```
+
+  They were always the stated contract — `docs/api_stability.md` calls them "the executable
+  statement of what [the extension points] require" — and they lived under `spec/`, which is
+  excluded from the packaged gem. The audience for the promise was the one group of people
+  who could not run it. Fixture paths resolve under `spec/fixtures` unless
+  `ActiveSanction::Testing.fixture_root` says otherwise, and an absolute path is taken as it
+  stands.
+
+  **`require "active_sanction"` does not load any of it**, so nothing reaches a production
+  process; requiring it without RSpec says so rather than failing somewhere stranger. The
+  group names and the options they take are public API from here, and a group gaining an
+  example is a minor with a note here naming it.
+
+- **Preparing a release is a button** (#146). `Prepare release` in the Actions tab takes a
+  version, bumps `VERSION`, moves the accrued `Unreleased` section under a dated heading,
+  fixes the changelog's link definitions, regenerates the site data that carries the
+  version, and opens a pull request. `release.yml` verifies all of that and writes none of
+  it, so until now it was a hand-edit somebody had to remember — and hand-edits to this
+  particular shape have already gone wrong silently once, when two open pull requests
+  merged cleanly in sequence and filed a feature under a patch release that did not contain
+  it.
+
+  The edits are [`bin/prepare_release`](bin/prepare_release), with a spec over them, so the
+  workflow is reviewable as Ruby and `bin/prepare_release 1.2.3` does the same thing on a
+  laptop. It refuses a version that does not come after the current one, and refuses to
+  prepare a release out of an empty `Unreleased` — which `release.yml` also refuses, but
+  only after the gem is published. Nothing is tagged or pushed to `main`: the output is a
+  pull request, and the version number stays a judgment a person makes.
+
+- **`Client#supports?`** (#144), so a caller can ask what an implementation does rather than
+  find out by rescuing `NoMethodError`. This client supports all of
+  `Client::CAPABILITIES`; the method is for the implementations that are not this class —
+  one answering screening questions against data somebody else keeps fresh has no `sync!`
+  to offer. An unrecognised capability is `false` rather than an error, deliberately unlike
+  `Configuration`: the caller asking is usually written against a newer version than the one
+  answering, and wants a fallback path rather than an exception.
+
 ## [1.1.0] - 2026-09-14
 
 **A minor, because it adds.** Nothing that existed changed: no behaviour under `lib/`
@@ -652,7 +707,8 @@ summarized here because they are what a reader of a first release most needs:
 - Recall at the default threshold is 0.939 overall on the labeled set, and every record this
   version misses is named in the committed accuracy report.
 
-[Unreleased]: https://github.com/Babystep-Technologies/active_sanction/compare/v1.1.0...main
+[Unreleased]: https://github.com/Babystep-Technologies/active_sanction/compare/v1.1.1...main
+[1.1.1]: https://github.com/Babystep-Technologies/active_sanction/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/Babystep-Technologies/active_sanction/compare/v1.0.1...v1.1.0
 [1.0.1]: https://github.com/Babystep-Technologies/active_sanction/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/Babystep-Technologies/active_sanction/releases/tag/v1.0.0

data/CONTRIBUTING.md

@@ -234,10 +234,27 @@ comment restating the name would be noise.
 
 `bundle exec rake install` installs the gem locally.
 
-A release is a tag. Bump `VERSION` in
-[`lib/active_sanction/version.rb`](lib/active_sanction/version.rb), move the
-`Unreleased` section of [`CHANGELOG.md`](CHANGELOG.md) under the new version
-with its date, and merge that.
+A release is a tag, and two facts have to be true on `main` before one can
+exist: `VERSION` says the version, and `CHANGELOG.md` has a section for it.
+`release.yml` checks both and writes neither.
+
+**Putting them there is a button too.** Open
+[`Prepare release`](https://github.com/Babystep-Technologies/active_sanction/actions/workflows/prepare-release.yml),
+press **Run workflow**, enter `1.2.3`. It bumps `VERSION`, moves the accrued
+`Unreleased` section under a dated `## [1.2.3]` heading, leaves a fresh empty
+`Unreleased` behind, fixes the link definitions at the foot of the changelog,
+regenerates the one site data file that carries the version, and opens a pull
+request. CI runs on it like any other.
+
+The edits are [`bin/prepare_release`](bin/prepare_release), so
+`bin/prepare_release 1.2.3` does exactly the same thing on your machine if you
+would rather commit it yourself. It refuses a version that does not come after
+the current one, and refuses to prepare a release out of an empty `Unreleased`
+— which `release.yml` also refuses, but only in the job that writes the GitHub
+release, long after the gem is published.
+
+**Read the moved changelog section before merging.** It becomes the release
+note verbatim.
 
 Then the tag, which you can let the workflow write or write yourself.
 

data/README.md

@@ -288,7 +288,7 @@ A source registered from outside this gem is a first-class source: a bank's inte
 
 There is no scaffold generator, deliberately. Roughly eight adapters at maturity do not repay one that has to be kept in step with `Sources::Base`, the conformance spec and the parser toolkits, and that goes stale silently when it is not; the document plus the closest existing adapter to copy does the same job with none of the upkeep.
 
-Every source adapter is held to one shared example group, `"a sanction source"` (`spec/support/shared_examples/sanction_source.rb`), which checks what everything downstream of an adapter assumes and cannot check for itself — a declared key, jurisdiction, authority and URL; `Entity` objects with unique, deterministic ids; dates as `PartialDate`; a round trip through `#to_h`; the publisher's own text kept in `remarks`. It is the floor and not the ceiling, so every adapter still writes its own spec on top.
+Every source adapter is held to one shared example group, `"a sanction source"` — shipped, so an adapter written outside this repository is held to it too: `require "active_sanction/testing"`. It checks what everything downstream of an adapter assumes and cannot check for itself — a declared key, jurisdiction, authority and URL; `Entity` objects with unique, deterministic ids; dates as `PartialDate`; a round trip through `#to_h`; the publisher's own text kept in `remarks`. It is the floor and not the ceiling, so every adapter still writes its own spec on top.
 
 ## How it works
 

data/docs/adding_a_source.md

@@ -691,7 +691,7 @@ There is one option: `remarks: false`, for a list that publishes no free text of
 its own anywhere — Canada is the only launch source that qualifies. It has to be
 asked for, so that dropping a remark by accident stays a failure.
 
-The group lives in `spec/support/shared_examples/sanction_source.rb` and checks
+The group lives in `lib/active_sanction/testing/sanction_source.rb`, reaches a suite through `require "active_sanction/testing"`, and checks
 what everything downstream assumes and cannot check for itself: that the adapter
 declares a key, a jurisdiction, an authority and a URL and registers itself; that
 `#parse` returns Entities with unique, deterministic ids, a canonical type and at

data/docs/api_stability.md

@@ -96,10 +96,11 @@ watchlist, a store backed by somebody's own database — and those authors are
 not reading this repository's release notes. So the required methods of each,
 their arguments and what they must return do not change within a major version,
 and the shared conformance groups
-([`spec/active_sanction/sources/conformance_spec.rb`](../spec/active_sanction/sources/conformance_spec.rb),
-[`spec/active_sanction/storage/conformance_spec.rb`](../spec/active_sanction/storage/conformance_spec.rb))
+([`lib/active_sanction/testing/sanction_source.rb`](../lib/active_sanction/testing/sanction_source.rb),
+[`lib/active_sanction/testing/storage_adapter.rb`](../lib/active_sanction/testing/storage_adapter.rb))
 are the executable statement of what they require. An adapter that passes them
-today passes them for the life of the major version.
+today passes them for the life of the major version — and **they ship**, so an
+adapter outside this repository can run them: `require "active_sanction/testing"`.
 
 New *optional* hooks may be added — a method with a default implementation on
 the base class is not a break, because an adapter that does not define it goes
@@ -193,8 +194,10 @@ oversight:
   themselves are public — they are how an adapter is written — but the classes
   that do the reading underneath them are not.
 - **Anything under `spec/`, `benchmark/`, `canary/` or `bin/`.** None of it
-  ships in the gem. The one exception in spirit is the two conformance groups,
-  which do not ship either but which an adapter author is expected to run.
+  ships in the gem. The two conformance groups used to be the exception in
+  spirit — expected to be run by adapter authors who had no way to get them —
+  and they are now under `lib/active_sanction/testing/` and public, which is
+  what the section above is about.
 
 ## The enumerated public surface
 
@@ -207,6 +210,7 @@ ActiveSanction
 ActiveSanction::VERSION
 ActiveSanction::MATCHER_VERSION
 ActiveSanction::Client
+ActiveSanction::Client::CAPABILITIES
 ActiveSanction::Configuration
 ActiveSanction::Deprecation
 ActiveSanction::Configuration::DEFAULT_CACHE_DIRNAME
@@ -300,6 +304,29 @@ ActiveSanction::Parsers::Warning
 ActiveSanction::Parsers::ColumnShape
 ```
 
+### Testing your own adapter
+
+```
+ActiveSanction::Testing
+ActiveSanction::Testing::DEFAULT_FIXTURE_ROOT
+ActiveSanction::Testing::StorageAdapterDefaults
+```
+
+Loaded by `require "active_sanction/testing"`, never by `require
+"active_sanction"`. The two shared example group **names** — `"a sanction
+source"` and `"a storage adapter"` — are public on the same terms as the
+constants: a group is not renamed or removed within a major version, and the
+options it accepts do not change meaning under an adapter that passes it
+today.
+
+New examples may be **added** to a group, and that is not a breaking change
+even though it can turn a passing adapter red. It is the same promise the
+extension points make read from the other side: what the group checks is what
+`Sources::Base` and `Storage::Base` required all along, and an adapter that
+fails a newly added example was always violating the contract — the group
+merely started saying so. Additions land in a minor, with a `CHANGELOG.md`
+entry naming them.
+
 ### Storage, and what a fetch remembers
 
 ```

data/lib/active_sanction/client.rb

@@ -79,6 +79,15 @@ module ActiveSanction
   class Client
     extend T::Sig
 
+    # What a client may be asked to do. Every one of them is a public method
+    # on this class, and this class supports all of them; see #supports?, and
+    # the note there on why an unknown name is false rather than an error.
+    #
+    # A name is not removed from this list within a major version, and a new
+    # one may be added -- which is the same promise the enumerated public
+    # surface makes, for the same reason.
+    CAPABILITIES = T.let(%i[screen screen_all sync diff rescreen doctor export import].freeze, T::Array[Symbol])
+
     # The settings this client answers from, frozen. Reading one is how a host
     # asks what a client is: `client.configuration.user_agent`.
     sig { returns(Configuration) }
@@ -330,6 +339,34 @@ module ActiveSanction
     sig { returns(T::Boolean) }
     def loaded? = !@lock.synchronize { @matcher }.nil?
 
+    # Whether this client does a thing, asked rather than assumed:
+    #
+    #   client.supports?(:sync)    # => true
+    #   client.supports?(:diff)    # => true
+    #
+    # This client supports all of CAPABILITIES -- it fetches, parses, stores
+    # and screens on the machine it runs on, and there is nothing in the list
+    # it cannot do. The method exists for the ones that are not this class.
+    # #56 was closed because `Client` already is the interface an out-of-tree
+    # implementation duck-types, and the one thing a duck-typed interface
+    # cannot express is *absence*: an implementation that answers screening
+    # questions against data somebody else keeps fresh has no `sync!` to
+    # offer, and a caller that cannot ask ends up finding out by rescuing
+    # NoMethodError.
+    #
+    # ### An unknown capability is false rather than an error
+    #
+    # Deliberately unlike Configuration, where an unrecognised setting raises
+    # because a silently dropped one is a client running on a default somebody
+    # thinks they changed. The direction here is the opposite: this is a
+    # forward-compatibility question, and the caller asking it is usually
+    # written against a newer version than the one answering. A host asking
+    # `supports?(:something_1_4_added)` of a 1.2 client wants `false` and a
+    # fallback path, not an exception -- raising would make the method useless
+    # for the one job it has.
+    sig { params(capability: T.untyped).returns(T::Boolean) }
+    def supports?(capability) = CAPABILITIES.include?(capability.to_sym)
+
     sig { returns(String) }
     def inspect
       named = sources ? T.must(sources).join(", ") : "every registered 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

data/lib/active_sanction/testing/storage_adapter.rb

@@ -0,0 +1,319 @@
+# typed: ignore
+# frozen_string_literal: true
+
+# The contract every storage 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::Storage::Memory do
+#     it_behaves_like "a storage adapter"
+#   end
+#
+# An adapter that needs something to be constructed -- a root directory, a
+# connection -- says how in the customization block, which is evaluated after
+# this group and so wins. It is a method rather than a `let` because a couple
+# of the examples need a second, independent store:
+#
+#   RSpec.describe ActiveSanction::Storage::FileSystem do
+#     it_behaves_like "a storage adapter" do
+#       def build_store = described_class.new(root: Dir.mktmpdir)
+#     end
+#   end
+#
+# ### What this is for
+#
+# The matcher (#33) is written against Storage::Base and never against a
+# concrete store, which is the whole point of the interface: an installation
+# swaps gzipped JSON for Postgres without touching the code that decides
+# whether two names are the same person. That only holds if every adapter
+# really does mean the same thing by these five methods, and "the same thing"
+# is otherwise a paragraph in a design document that each new adapter
+# re-interprets. Here it is executable.
+#
+# Most of what it checks is a way of losing records quietly. A store that
+# returns an empty snapshot for a source nobody ever synced, one that drops the
+# third of four entities on the way back, one that reorders them, one that
+# accumulates two writes of a list instead of replacing it -- none of those
+# raise, all of them return something that looks like a sanctions list, and the
+# report they produce says the name you screened is clear.
+#
+# ### What it does not do
+#
+# It says nothing about durability, concurrency or performance, which are the
+# things the adapters genuinely differ on: that a FileSystem write is atomic
+# (#24), that an ActiveRecord write is one transaction (#25), that a Memory
+# store is safe to screen from on many threads. Those are properties of one
+# implementation and each adapter's own spec has to make them.
+RSpec.shared_examples "a storage adapter" do
+  include ActiveSanction::Testing::StorageAdapterDefaults
+
+  let(:store) { build_store }
+  let(:ofac) { snapshot(:ofac_sdn, %w[2674 1234]) }
+  let(:un) { snapshot(:un_consolidated, %w[QDi.001]) }
+
+  # A record carrying every kind of member the canonical model has, because
+  # what a store loses is usually nested: a store that persists names and drops
+  # identifiers passes a contract written against bare strings.
+  def entity(source, ref)
+    ActiveSanction::Entity.new(
+      source: source, source_ref: ref, type: :individual,
+      names: [ActiveSanction::Name.new(value: "AL ZAWAHIRI #{ref}, Aiman", kind: :primary)],
+      addresses: [ActiveSanction::Address.new(country: "EG", city: "Cairo")],
+      identifiers: [ActiveSanction::Identifier.new(kind: :passport, value: ref, country: "EG")],
+      dates_of_birth: [ActiveSanction::PartialDate.parse("1951-06-19")],
+      nationalities: ["EG"], programs: ["SDGT"],
+      listed_on: ActiveSanction::PartialDate.parse("2001-09-23"),
+      remarks: "DOB 19 Jun 1951; POB Egypt"
+    )
+  end
+
+  def snapshot(source, refs)
+    ActiveSanction::Snapshot.new(
+      source: source, entities: refs.map { |ref| entity(source, ref) },
+      fetched_at: Time.utc(2026, 8, 28, 9, 30, 0), source_version: "Thu, 28 Aug 2026 09:00:00 GMT"
+    )
+  end
+
+  def entity_refs(entities) = entities.map(&:source_ref)
+
+  describe "a source that has never been synced" do
+    # Nil says "we have never fetched this". An empty snapshot says "this list
+    # has nobody on it", which no sanctions list has ever said, and a caller
+    # that cannot tell them apart screens against nothing and reports clear.
+    it "reads back as nil rather than as a list with nobody on it" do
+      expect(store.read_snapshot(:ofac_sdn)).to be_nil
+    end
+
+    it "has no metadata to report" do
+      expect(store.snapshot_meta(:ofac_sdn)).to be_nil
+    end
+
+    it "is not among the stored sources" do
+      expect(store.sources).not_to include(:ofac_sdn)
+    end
+
+    it "is not reported as stored" do
+      expect(store).not_to be_stored(:ofac_sdn)
+    end
+
+    # The other half of returning nil: a caller that named the list itself gets
+    # an exception rather than an empty result it has to remember to check.
+    it "raises when a caller asks for it by name" do
+      expect { store.fetch_snapshot(:ofac_sdn) }.to raise_error(ActiveSanction::Storage::MissingSnapshot)
+    end
+
+    it "deletes without complaint, and says there was nothing to delete" do
+      expect(store.delete_snapshot(:ofac_sdn)).to be_falsey
+    end
+  end
+
+  describe "what comes back out" do
+    before { store.write_snapshot(ofac) }
+
+    it "returns the snapshot that was written" do
+      expect(store.read_snapshot(:ofac_sdn)).to eq(ofac)
+    end
+
+    # Snapshot#== compares checksums, so the example above passes for a store
+    # that kept the checksum and lost the list. This is the one that does not.
+    it "returns every record, field for field" do
+      expect(store.read_snapshot(:ofac_sdn).entities.map(&:to_h)).to eq(ofac.entities.map(&:to_h))
+    end
+
+    # A store that hands back half-deserialized records makes every caller
+    # downstream coerce before it can read a name.
+    it "returns Entities, not the hashes they serialize to" do
+      expect(store.read_snapshot(:ofac_sdn).entities).to all(be_an(ActiveSanction::Entity))
+    end
+
+    # Order is not in the checksum -- Snapshot sorts fingerprints before
+    # folding them -- so nothing else catches a store that returns its rows in
+    # whatever order the database felt like. A report whose rows move between
+    # two runs against an unchanged list is a report an examiner cannot cite.
+    it "returns the records in the order they were written" do
+      expect(entity_refs(store.read_snapshot(:ofac_sdn).entities)).to eq(entity_refs(ofac.entities))
+    end
+
+    it "returns the checksum the snapshot was written with" do
+      expect(store.read_snapshot(:ofac_sdn).checksum).to eq(ofac.checksum)
+    end
+
+    # To the second, which is what Snapshot#to_h serializes. An adapter that
+    # loses it cannot answer how old the list it is screening against is (#34).
+    it "returns the time the list was fetched" do
+      expect(store.read_snapshot(:ofac_sdn).fetched_at).to eq(ofac.fetched_at)
+    end
+
+    it "returns the publisher's own version marker" do
+      expect(store.read_snapshot(:ofac_sdn).source_version).to eq(ofac.source_version)
+    end
+
+    # Keys arrive as symbols from an adapter and as strings from anything that
+    # has been through JSON or a command line.
+    it "answers to the source name spelled as a string" do
+      expect(store.read_snapshot("ofac_sdn")).to eq(ofac)
+    end
+
+    it "lists the source it stored" do
+      expect(store.sources).to eq([:ofac_sdn])
+    end
+  end
+
+  describe "what it refuses" do
+    # A Hash of the right shape carries a checksum somebody typed; only a
+    # Snapshot carries one computed over its own content, and that is the whole
+    # basis on which a stored list can be cited months later.
+    it "refuses to store something that is not a Snapshot" do
+      expect { store.write_snapshot(ofac.to_h) }.to raise_error(ArgumentError)
+    end
+
+    # Source keys are typed by humans and are directory names to any adapter
+    # that writes files, so they are held to one rule everywhere.
+    it "refuses a name that is not a usable source key" do
+      expect { store.read_snapshot("") }.to raise_error(ActiveSanction::Error)
+    end
+  end
+
+  describe "writing" do
+    it "returns the snapshot it stored" do
+      expect(store.write_snapshot(ofac)).to eq(ofac)
+    end
+
+    # A sync replaces a list; it does not add to one. A store that accumulates
+    # holds a delisted person forever, which is a false hit on every screening
+    # run from then on.
+    it "replaces a list rather than accumulating two of them" do
+      store.write_snapshot(ofac)
+      store.write_snapshot(snapshot(:ofac_sdn, %w[9999]))
+
+      expect(entity_refs(store.read_snapshot(:ofac_sdn).entities)).to eq(%w[9999])
+    end
+
+    it "files a rewritten source once" do
+      store.write_snapshot(ofac)
+      store.write_snapshot(snapshot(:ofac_sdn, %w[9999]))
+
+      expect(store.sources).to eq([:ofac_sdn])
+    end
+
+    # Per-source isolation is the rule sync orchestration (#34) is built on: one
+    # list failing must leave the others exactly as they were.
+    it "leaves the other lists alone" do
+      store.write_snapshot(un)
+      store.write_snapshot(ofac)
+
+      expect(store.read_snapshot(:un_consolidated)).to eq(un)
+    end
+
+    it "sorts the sources it lists, so a summary does not reshuffle itself" do
+      store.write_snapshot(un)
+      store.write_snapshot(ofac)
+
+      expect(store.sources).to eq(%i[ofac_sdn un_consolidated])
+    end
+  end
+
+  describe "#snapshot_meta" do
+    before { store.write_snapshot(ofac) }
+
+    it "reports what was stored without being asked for the list" do
+      expect(store.snapshot_meta(:ofac_sdn)).to eq(ActiveSanction::Storage::Meta.from_snapshot(ofac))
+    end
+
+    it "counts the records" do
+      expect(store.snapshot_meta(:ofac_sdn).record_count).to eq(2)
+    end
+
+    # What a match result cites (#33). A meta whose checksum is not the stored
+    # snapshot's cannot answer which list version cleared a customer.
+    it "carries the stored snapshot's checksum" do
+      expect(store.snapshot_meta(:ofac_sdn).checksum).to eq(ofac.checksum)
+    end
+  end
+
+  describe "#each_entity" do
+    before do
+      store.write_snapshot(ofac)
+      store.write_snapshot(un)
+    end
+
+    it "yields every record of every stored list" do
+      expect(store.each_entity.to_a.size).to eq(3)
+    end
+
+    it "yields Entities" do
+      expect(store.each_entity.to_a).to all(be_an(ActiveSanction::Entity))
+    end
+
+    # The index build (#31) walks every entity of every list. Handing it an
+    # array of ~25,000 records built before the first one is yielded is a cost
+    # nothing here needs to pay.
+    it "returns an Enumerator rather than an array when given no block" do
+      expect(store.each_entity).to be_an(Enumerator)
+    end
+
+    it "stops when the caller stops" do
+      yielded = []
+      store.each_entity do |entity|
+        yielded << entity
+        break if yielded.any?
+      end
+
+      expect(yielded.size).to eq(1)
+    end
+
+    it "yields only the lists it was asked for" do
+      expect(entity_refs(store.each_entity(sources: %i[un_consolidated]).to_a)).to eq(%w[QDi.001])
+    end
+
+    it "takes one source named on its own" do
+      expect(store.each_entity(sources: :un_consolidated).to_a.size).to eq(1)
+    end
+
+    # Screening two of the three lists an application configured, and saying
+    # nothing about the third, is the failure this contract exists to prevent.
+    it "refuses to quietly skip a named list that was never synced" do
+      expect { store.each_entity(sources: %i[ofac_sdn eu_fsf]).to_a }
+        .to raise_error(ActiveSanction::Storage::MissingSnapshot)
+    end
+
+    it "yields nothing from an empty store" do
+      expect(build_store.each_entity.to_a).to be_empty
+    end
+  end
+
+  describe "removing a list" do
+    before { store.write_snapshot(ofac) }
+
+    it "reports that there was one to remove" do
+      expect(store.delete_snapshot(:ofac_sdn)).to be_truthy
+    end
+
+    it "forgets the snapshot" do
+      store.delete_snapshot(:ofac_sdn)
+
+      expect(store.read_snapshot(:ofac_sdn)).to be_nil
+    end
+
+    it "stops listing the source" do
+      store.delete_snapshot(:ofac_sdn)
+
+      expect(store.sources).to be_empty
+    end
+
+    it "leaves the other lists alone" do
+      store.write_snapshot(un)
+      store.delete_snapshot(:ofac_sdn)
+
+      expect(store.read_snapshot(:un_consolidated)).to eq(un)
+    end
+
+    it "empties the whole store on #clear" do
+      store.write_snapshot(un)
+      store.clear
+
+      expect(store).to be_empty
+    end
+  end
+end

data/lib/active_sanction/testing/storage_adapter_defaults.rb

@@ -0,0 +1,25 @@
+# typed: ignore
+# frozen_string_literal: true
+
+# How the storage conformance group builds the adapter it is testing.
+#
+# In a module, and in a file of its own, for two reasons that are both about
+# not defining a method twice. A group is free to override `build_store` in the
+# customization block it passes to `it_behaves_like` -- which is how an adapter
+# that cannot be built by `.new` alone gets held to the contract -- and
+# defining a method over one the group already had would warn, since this suite
+# runs with Ruby warnings on. Keeping it out of the shared example group's own
+# file is the same rule one level up: the conformance spec loads that file
+# again inside an RSpec sandbox, and a module reopened there would redefine
+# whatever it holds.
+#
+# Namespaced, because it ships: a bare `StorageAdapterDefaults` at the top
+# level would be this gem putting a name into a host's global namespace to
+# save itself two words.
+module ActiveSanction
+  module Testing
+    module StorageAdapterDefaults
+      def build_store = described_class.new
+    end
+  end
+end

data/lib/active_sanction/testing.rb

@@ -0,0 +1,119 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "pathname"
+require "sorbet-runtime"
+
+require "active_sanction"
+
+module ActiveSanction
+  # The conformance groups, shipped, so that an adapter written outside this
+  # repository can prove it conforms.
+  #
+  #   # spec/spec_helper.rb, in your application
+  #   require "active_sanction/testing"
+  #
+  #   # spec/internal_watchlist_spec.rb
+  #   RSpec.describe MyCompany::InternalWatchlist do
+  #     it_behaves_like "a sanction source", fixture: "internal_watchlist/list.csv"
+  #   end
+  #
+  #   RSpec.describe MyCompany::PostgresStore do
+  #     it_behaves_like "a storage adapter" do
+  #       def build_store = described_class.new(url: ENV.fetch("DATABASE_URL"))
+  #     end
+  #   end
+  #
+  # Two groups: **"a sanction source"** for a Sources::Base subclass, and
+  # **"a storage adapter"** for a Storage::Base implementation. Each is
+  # documented at the top of its own file.
+  #
+  # ### Why this is in `lib/` and not in `spec/`
+  #
+  # `docs/api_stability.md` names Sources::Base, Storage::Base and
+  # ValidatorStore as the three extension points carrying the strongest
+  # guarantee, and says of these groups that they "are the executable
+  # statement of what they require. An adapter that passes them today passes
+  # them for the life of the major version."
+  #
+  # That promise is addressed to people who install this gem, and until this
+  # file existed it was kept only for adapters living in this repository:
+  # `spec/` is excluded from the package, so the executable statement shipped
+  # nowhere and the guarantee was a paragraph again for everyone it was
+  # written for. A conformance suite that its audience cannot run is a
+  # conformance suite in name.
+  #
+  # ### Requiring it is opt-in, and costs a host nothing
+  #
+  # `require "active_sanction"` does not load this, and nothing under `lib/`
+  # requires it. It is loaded by a suite that asked for it, needs RSpec
+  # already loaded, and says so rather than failing somewhere stranger if it
+  # is not.
+  #
+  # ### What they do not do
+  #
+  # Neither group knows anything about *your* list. They are the floor: that
+  # an adapter declares what it must, produces Entities of the right shape,
+  # gives every record a stable id, and reports what it could not read. Only a
+  # spec that knows which of your fixture's records is a vessel can check that
+  # you read it correctly, and you still write that one.
+  module Testing
+    extend T::Sig
+
+    # Where "a sanction source" looks for the fixture a group names, relative
+    # to the working directory a suite runs from. `spec/fixtures` is where
+    # RSpec projects put them, which makes the default right for most callers
+    # and the setting below right for the rest.
+    DEFAULT_FIXTURE_ROOT = T.let("spec/fixtures", String)
+
+    class << self
+      extend T::Sig
+
+      # Where fixture paths are resolved from. Set it when a project keeps
+      # them somewhere other than `spec/fixtures`:
+      #
+      #   ActiveSanction::Testing.fixture_root = "test/data/sanctions"
+      #
+      # Relative to the working directory, which for a suite is the project
+      # root. An absolute path passed to `fixture:` ignores this entirely.
+      sig { params(value: T.untyped).void }
+      def fixture_root=(value)
+        @fixture_root = T.let(value&.to_s, T.nilable(String))
+      end
+
+      sig { returns(String) }
+      def fixture_root
+        @fixture_root ||= T.let(nil, T.nilable(String))
+        File.expand_path(@fixture_root || DEFAULT_FIXTURE_ROOT, Dir.pwd)
+      end
+
+      # One fixture, as an absolute path. An absolute path is returned as it
+      # stands, so a project that generates a fixture into a temporary
+      # directory can name it directly.
+      #
+      # Missing files are refused here rather than at `File.binread`, because
+      # a conformance run against a fixture that is not there should say which
+      # fixture and where it looked -- the two facts needed to fix it.
+      sig { params(path: T.untyped).returns(String) }
+      def fixture_path(path)
+        name = path.to_s
+        resolved = Pathname.new(name).absolute? ? name : File.expand_path(name, fixture_root)
+        return resolved if File.file?(resolved)
+
+        raise ArgumentError,
+              "no fixture at #{resolved}. Paths are resolved under #{fixture_root} -- " \
+              "set ActiveSanction::Testing.fixture_root if yours live somewhere else."
+      end
+    end
+  end
+end
+
+unless defined?(RSpec)
+  raise LoadError,
+        "active_sanction/testing defines RSpec shared example groups, and RSpec is not loaded. " \
+        "Require it from your spec_helper, after rspec itself."
+end
+
+require "active_sanction/testing/storage_adapter_defaults"
+require "active_sanction/testing/sanction_source"
+require "active_sanction/testing/storage_adapter"

data/lib/active_sanction/version.rb

@@ -6,7 +6,7 @@ module ActiveSanction
   # new source adapter, a storage fix or a documentation release -- none of
   # which change what a name scores. MATCHER_VERSION, below, is the one that
   # answers that question.
-  VERSION = "1.1.0"
+  VERSION = "1.1.1"
 
   # Which matching pipeline scored a decision, stamped onto every MatchResult
   # and bumped whenever a change to the normalizer, the index, the similarity

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_sanction
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Marshall Shen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-14 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csv
@@ -201,6 +201,10 @@ files:
 - lib/active_sanction/sync.rb
 - lib/active_sanction/sync/report.rb
 - lib/active_sanction/sync/result.rb
+- lib/active_sanction/testing.rb
+- lib/active_sanction/testing/sanction_source.rb
+- lib/active_sanction/testing/storage_adapter.rb
+- lib/active_sanction/testing/storage_adapter_defaults.rb
 - lib/active_sanction/validator_store.rb
 - lib/active_sanction/validator_store/file_system.rb
 - lib/active_sanction/validator_store/memory.rb