active_sanction 1.0.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6c9a31bd72dfdc43d5614499a19aab837b55996b9644ae145b89da18b93bea6
-  data.tar.gz: 40cbea7b7fcf458307171ca953fb61864dce06da7733ece2ac17e4d27a43215d
+  metadata.gz: ecdae0214290d15cba0bf24838c8e4d2d2e004eaecb344c29aaa8c07d54da36b
+  data.tar.gz: c72d3f5baa535d081aae672de2013585e38c85c1cceb5c2a697d6cecc7d5f98a
 SHA512:
-  metadata.gz: 892209a20496c2eea1185776a83725cb89ae6c7b40ba2385becf7870b78d8e1a6cf88734e29afec40153418dfa73ac275a3270b0bb16a80e56c3de6605e58652
-  data.tar.gz: e3330620e4c4f6c31c6a7e0c58b53bda9972628e9d6965798d56f666f7301b83ccc2edb42931d15b18b161c9480df96b5147edf0e94b77461e90e0958944ed46
+  metadata.gz: 5fc3e4e17279f0220f903792d952d4aa1adfa1068504512f51cbacb2247cc4ae71710b38c4de6374810e0c48bcc03052a7149eff9a69dda9ebc02389e27c8f05
+  data.tar.gz: 34df5f7d1103073a4bd50956abc77e1e87a9a3c5a213be9c18a46a6e41ccbdd5db64fcf0c7b7437d4c52e33f6876ea581ba57e04a44baa95d3ecec1666a8e315

data/CHANGELOG.md

@@ -17,6 +17,113 @@ 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/`
+moved, `MATCHER_VERSION` stays at `1`, and a name scores today exactly what it scored
+under 1.0.0. Instrumentation is additive and off unless a host asks for it.
+
+### Added
+
+- **Instrumentation: six structured events, so a host can measure this library without
+  monkeypatching it** (#59). `ActiveSanction.configure { |c| c.instrumenter = ... }` takes
+  anything answering `#call(event)` and is handed a finished
+  `ActiveSanction::Instrumentation::Event` for each of `:fetch`, `:parse`, `:store`,
+  `:"index.build"`, `:screen` and `:sync` — every one carrying a duration and the ids
+  needed to correlate it, with no anonymous timings. The event names and every payload key
+  are public API, enumerated in [`docs/api_stability.md`](docs/api_stability.md) and on the
+  site's [instrumentation reference](https://babystep.tech/active_sanction/reference/instrumentation/),
+  and covered by the deprecation path from here.
+
+  **It is a measurement of the work and never part of it.** A subscriber that raises has its
+  exception caught, reported once through the configured logger, and dropped; the sync it
+  was watching finishes and returns the report it was going to return. The converse holds
+  too: a stage that raises emits its event with `error:` set and then the exception
+  continues exactly as if nothing were listening.
+
+  **Nothing is listening by default, and that costs nothing.** `nil` is a branch taken
+  before anything is allocated rather than a no-op object that gets called, so an
+  uninstrumented screening call builds no event and allocates no payload — which is the
+  only way a per-query event could be affordable at all. Measured rather than asserted:
+  building a matcher over 47,051 names allocates 262 more objects than before, out of
+  5.79 million, and `rake benchmark:latency` reports the same p50 either side of the change
+  (12.1–12.8 ms against a run-to-run spread that was already that wide).
+
+  Rails hosts get `ActiveSanction::Instrumentation::Notifications`, which republishes every
+  event into `ActiveSupport::Notifications` under `<event>.active_sanction`. It is an
+  adapter and not a dependency: **nothing in this gem requires ActiveSupport**, and building
+  one in a process that has not loaded it raises `ConfigurationError` rather than quietly
+  instrumenting nothing.
+
+  The issue asked for `ActiveSanction.instrumenter = ...`, and this is a configuration
+  setting instead. #55 ended process-global configuration deliberately, and a module-level
+  writer would have rebuilt the default client — dropping the matcher it had indexed every
+  stored list into — as a side effect of naming a subscriber. A `Matcher` takes its
+  instrumenter at build and freezes it with its weights, so a subscriber swapped halfway
+  through a batch cannot make half of it instrumented; that is the rule every other setting
+  on the query path already follows.
+
+- **`Sources::Base#warnings`**, defaulting to none. Every shipped adapter already exposed
+  it and the adapter rules already required it of a new one, but the base class never said
+  so — and the `:parse` event counts warnings for every source, which a count that is
+  sometimes a `NoMethodError` cannot do. An optional hook with a default implementation, so
+  no adapter outside this repository has to change.
+
 ## [1.0.1] - 2026-09-14
 
 A packaging and release-tooling release. **Nothing about screening changes**: no behaviour
@@ -600,6 +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.0.1...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

@@ -4,7 +4,7 @@ What this gem promises not to break, and what it reserves the right to change
 in any release.
 
 **The public surface is enumerated below, not inferred.** A constant being
-reachable does not make it public; nearly 500 of them are reachable and 137 are
+reachable does not make it public; over 500 of them are reachable and 142 are
 promised. Everything else is marked `@api private` in the source, is hidden
 from the rendered documentation, and may be renamed, moved or deleted in a
 patch release without a note anywhere. If you need something that is not on
@@ -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
@@ -107,7 +108,7 @@ on working.
 
 ## Contracts that are not constants
 
-Four promises here are about behaviour rather than about a name, and none of
+Five promises here are about behaviour rather than about a name, and none of
 them is enforceable by the surface spec.
 
 **The error hierarchy.** Within a major version an error does not move to a
@@ -128,6 +129,35 @@ anyone may produce or consume one, in any language.
 store written against one schema version keeps being readable; the file layout
 underneath a shipped store is not public and may change.
 
+**The instrumentation events.** `ActiveSanction::Instrumentation::EVENTS`
+names the six, and each one's payload keys are promised the same way a method
+signature is: within a major version a key is not removed, renamed, or made to
+mean something else, and a dashboard written against one keeps working. Keys
+may be **added** to an event — that is how a new measurement ships without a
+major version — so a subscriber reads the keys it knows and ignores the rest,
+and must not assume the set is closed.
+
+Every event carries `name`, `started_at` and `duration`, plus the keys below.
+`error` is present only when the stage raised, in which case the keys it had
+not reached yet are **absent rather than zero**.
+
+| Event | Payload keys |
+|---|---|
+| `:fetch` | `source`, `key`, `url`, `forced`, `conditional`, `status`, `not_modified`, `bytes` |
+| `:parse` | `source`, `bytes`, `records`, `warnings` |
+| `:store` | `source`, `snapshot_id`, `entities`, `store`, `imported` (on an import only) |
+| `:"index.build"` | `store`, `sources`, `snapshots`, `entities`, `names`, `keys`, `postings`, `bytes` |
+| `:screen` | `candidates`, `scored`, `results`, `threshold`, `limit`, `sources`, `snapshots` |
+| `:sync` | `sources`, `forced`, `concurrency`, `outcomes`, `updated`, `unchanged`, `failed`, `records` |
+
+Two things about them are contracts rather than incidental. **A `:fetch` event
+is one HTTP round trip** — a file served out of the payload cache after a 304
+costs no request and emits nothing, and a source re-fetching one because its
+cache was empty emits a second event rather than amending the first. And
+**`bytes` on `:"index.build"` is an estimate**, documented as one on
+`Index#profile`; it is good to within a factor a dashboard cares about and is
+not a heap measurement.
+
 **A `MatchResult` is reproducible.** The snapshot checksum, matcher version,
 weights and query it stamps are what let a screening decision be re-derived
 years later. Fields may be added to that stamp; the meaning of an existing one
@@ -138,6 +168,12 @@ does not change under it.
 Named here because their absence from the list is a decision rather than an
 oversight:
 
+- **The instrumenter contract's other half.** A subscriber is anything
+  answering `#call(event)`, and that is public. `Instrumentation.instrument`
+  and `.emit`, which the library's own stages call, are not: where an event is
+  emitted from is an implementation detail of the stage, and a host that
+  wanted to emit one of these names itself would be publishing a measurement
+  of something this library did not do.
 - **The matching internals** — `Index`, `Similarity`, `Phonetics`, and the
   scorer's `Adjustments` and `NameScore`. These are where accuracy work
   happens, and accuracy work that had to preserve a signature would stop.
@@ -158,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
 
@@ -172,6 +210,7 @@ ActiveSanction
 ActiveSanction::VERSION
 ActiveSanction::MATCHER_VERSION
 ActiveSanction::Client
+ActiveSanction::Client::CAPABILITIES
 ActiveSanction::Configuration
 ActiveSanction::Deprecation
 ActiveSanction::Configuration::DEFAULT_CACHE_DIRNAME
@@ -193,6 +232,16 @@ ActiveSanction::Configuration::DEFAULT_USER_AGENT
 ActiveSanction::Configuration::DEFAULT_XML_BACKEND
 ```
 
+### Instrumentation
+
+```
+ActiveSanction::Instrumentation
+ActiveSanction::Instrumentation::EVENTS
+ActiveSanction::Instrumentation::Event
+ActiveSanction::Instrumentation::Notifications
+ActiveSanction::Instrumentation::Notifications::NAMESPACE
+```
+
 ### The canonical record
 
 ```
@@ -255,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

@@ -5,6 +5,7 @@ require "sorbet-runtime"
 
 require "active_sanction/configuration"
 require "active_sanction/error"
+require "active_sanction/instrumentation"
 require "active_sanction/match_result"
 
 module ActiveSanction
@@ -78,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) }
@@ -157,7 +167,8 @@ module ActiveSanction
       @lock.synchronize do
         @matcher ||= with_configuration do
           Matcher.build(storage, sources: configuration.sources, weights: configuration.scorer_weights,
-                                 candidate_limit: configuration.candidate_limit, backend: backend)
+                                 candidate_limit: configuration.candidate_limit, backend: backend,
+                                 instrumenter: configuration.instrumenter)
         end
       end
     end
@@ -286,7 +297,14 @@ module ActiveSanction
     sig { params(path: T.untyped, verify_with: T.untyped).returns(Snapshot) }
     def import(path, verify_with: nil)
       snapshot = ::File.open(path.to_s, "rb") { |io| Snapshot::Bundle.read(io, verify_with: verify_with) }
-      with_configuration { storage.write_snapshot(snapshot) }
+      # The same `:store` event a sync emits, because it is the same fact: a
+      # list version was written to this store, and a host watching data
+      # freshness should not have to know which of the two ways it arrived.
+      fields = { source: snapshot.source, snapshot_id: snapshot.checksum, entities: snapshot.record_count,
+                 store: storage.class.name, imported: true }
+      Instrumentation.instrument(configuration.instrumenter, :store, fields) do
+        with_configuration { storage.write_snapshot(snapshot) }
+      end
       reload!
       snapshot
     end
@@ -321,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/configuration.rb

@@ -4,6 +4,7 @@
 require "sorbet-runtime"
 
 require "active_sanction/error"
+require "active_sanction/instrumentation"
 require "active_sanction/normalizer"
 require "active_sanction/scorer/weights"
 require "active_sanction/version"
@@ -245,6 +246,11 @@ module ActiveSanction
     sig { returns(T.untyped) }
     attr_reader :logger
 
+    # Anything answering `#call(event)`, or nil for the default, which is that
+    # nothing is listening. See #instrumenter= and Instrumentation.
+    sig { returns(T.untyped) }
+    attr_reader :instrumenter
+
     sig { void }
     def initialize
       @user_agent = T.let(DEFAULT_USER_AGENT, String)
@@ -267,6 +273,7 @@ module ActiveSanction
       @normalizer_dictionary = T.let(Normalizer::Dictionary.default, Normalizer::Dictionary)
       @scorer_weights = T.let(Scorer::Weights.default, Scorer::Weights)
       @logger = T.let(nil, T.untyped)
+      @instrumenter = T.let(nil, T.untyped)
       @storage = T.let(nil, T.nilable(Storage::Base))
       @default_storage = T.let(nil, T.nilable(Storage::Base))
     end
@@ -569,6 +576,38 @@ module ActiveSanction
       @logger = value
     end
 
+    # Where this library's structured events go: a lambda, a Method, or any
+    # object answering `#call(event)`.
+    #
+    #   c.instrumenter = ->(event) { StatsD.timing("sanctions.#{event.name}", event.duration_ms) }
+    #   c.instrumenter = ActiveSanction::Instrumentation::Notifications.new   # a Rails host
+    #
+    # Six events -- `:fetch`, `:parse`, `:store`, `:"index.build"`, `:screen`
+    # and `:sync` -- each carrying a duration and the ids needed to correlate
+    # it. Their payload keys are public API; see Instrumentation, which is
+    # where all of it is documented, and docs/api_stability.md, which
+    # enumerates the keys.
+    #
+    # The default is nil, and nil is a branch rather than a no-op object: an
+    # installation that instruments nothing pays nothing, which is the only
+    # way a per-query event could be affordable at all.
+    #
+    # This is read where a stage is *built* rather than where it runs -- a
+    # Matcher takes its instrumenter at `build` and freezes it, the way it
+    # freezes its weights -- so changing it here affects the next matcher,
+    # sync or fetcher and never one already running. That is the same rule
+    # every other setting on the query path follows, and it is what keeps a
+    # batch from being half one set of numbers and half another.
+    sig { params(value: T.untyped).void }
+    def instrumenter=(value)
+      unless value.nil? || value.respond_to?(:call)
+        raise ConfigurationError,
+              "instrumenter must respond to #call(event), got #{value.class}. See ActiveSanction::Instrumentation."
+      end
+
+      @instrumenter = value
+    end
+
     sig { returns(String) }
     def self.default_storage_dir
       -File.expand_path(File.join(Dir.home, DEFAULT_STORAGE_DIRNAME))

data/lib/active_sanction/fetcher.rb

@@ -5,6 +5,7 @@ require "sorbet-runtime"
 
 require "active_sanction/error"
 require "active_sanction/http_client"
+require "active_sanction/instrumentation"
 require "active_sanction/validators"
 require "active_sanction/validator_store"
 require "active_sanction/fetcher/result"
@@ -64,20 +65,28 @@ module ActiveSanction
     sig { returns(T.untyped) }
     attr_reader :logger
 
+    # Where the `:fetch` event goes, or nil for nothing listening. See
+    # Instrumentation.
+    sig { returns(T.untyped) }
+    attr_reader :instrumenter
+
     # The store defaults to disk, so the second run of a cron job benefits and
     # not merely the second call in one process. A caller that would rather
     # keep nothing between runs passes ValidatorStore::Memory.new.
     sig do
-      params(client: HttpClient, store: T.untyped, stale_after: T.nilable(Numeric), logger: T.untyped).void
+      params(client: HttpClient, store: T.untyped, stale_after: T.nilable(Numeric), logger: T.untyped,
+             instrumenter: T.untyped).void
     end
     def initialize(client: HttpClient.new,
                    store: ValidatorStore::FileSystem.new,
                    stale_after: ActiveSanction.config.stale_after,
-                   logger: ActiveSanction.config.logger)
+                   logger: ActiveSanction.config.logger,
+                   instrumenter: ActiveSanction.config.instrumenter)
       @client = T.let(client, HttpClient)
       @store = T.let(store, T.untyped)
       @stale_after = T.let(stale_after, T.nilable(Numeric))
       @logger = T.let(logger, T.untyped)
+      @instrumenter = T.let(instrumenter, T.untyped)
     end
 
     # Fetches conditionally and buffers the body, like HttpClient#get.
@@ -91,12 +100,17 @@ module ActiveSanction
     # `force: true` sends no validators, so the publisher has no way to answer
     # 304. For the operator who suspects the cached copy is wrong and wants the
     # bytes regardless of what the ETag says.
+    # `source:` is which list this file belongs to, and is only ever read by
+    # instrumentation: a multi-file source files its validators under
+    # `:"ofac_sdn-sdn"` and the rest, and a dashboard asking which *list* is
+    # degrading wants `:ofac_sdn`. Defaults to the fetch key, which is right
+    # for every single-file source and for a caller fetching a bare URL.
     sig do
-      params(url: T.untyped, key: T.untyped, force: T::Boolean, headers: T::Hash[T.untyped, T.untyped])
-        .returns(Result)
+      params(url: T.untyped, key: T.untyped, force: T::Boolean, headers: T::Hash[T.untyped, T.untyped],
+             source: T.untyped).returns(Result)
     end
-    def fetch(url, key: url, force: false, headers: {})
-      conditional(url, key, force, headers) { |request| client.get(url, headers: request) }
+    def fetch(url, key: url, force: false, headers: {}, source: nil)
+      conditional(url, key, force, headers, source) { |request| client.get(url, headers: request) }
     end
 
     # Streams conditionally to disk, like HttpClient#download. A 304 writes
@@ -104,10 +118,10 @@ module ActiveSanction
     # is left exactly as the last download left it.
     sig do
       params(url: T.untyped, to: T.untyped, key: T.untyped, force: T::Boolean,
-             headers: T::Hash[T.untyped, T.untyped]).returns(Result)
+             headers: T::Hash[T.untyped, T.untyped], source: T.untyped).returns(Result)
     end
-    def download(url, to:, key: url, force: false, headers: {})
-      conditional(url, key, force, headers) { |request| client.download(url, to: to, headers: request) }
+    def download(url, to:, key: url, force: false, headers: {}, source: nil)
+      conditional(url, key, force, headers, source) { |request| client.download(url, to: to, headers: request) }
     end
 
     # Whether a sync is due, answered locally and without a request.
@@ -149,14 +163,26 @@ module ActiveSanction
 
     sig do
       params(url: T.untyped, key: T.untyped, force: T::Boolean, headers: T::Hash[T.untyped, T.untyped],
+             source: T.untyped,
              block: T.proc.params(request: T::Hash[T.untyped, T.untyped]).returns(HttpClient::Response))
         .returns(Result)
     end
-    def conditional(url, key, force, headers, &block)
+    def conditional(url, key, force, headers, source, &block)
       stored = force ? nil : usable(key, url)
       log_request(key, url, stored, force)
-      response = block.call(merge(headers, stored))
-      record(key, url, stored, response)
+      # One event per HTTP round trip, which is why `forced` is on it: a file
+      # served out of the payload cache after a 304 costs no request and emits
+      # nothing, and a source re-fetching one because its cache was empty
+      # emits a second event rather than amending the first.
+      fields = { source: source || key, key: key, url: url.to_s, forced: force }
+      Instrumentation.instrument(instrumenter, :fetch, fields) do |event|
+        response = block.call(merge(headers, stored))
+        event[:status] = response.status
+        event[:not_modified] = response.not_modified?
+        event[:bytes] = response.body.to_s.bytesize
+        event[:conditional] = !stored.nil?
+        record(key, url, stored, response)
+      end
     end
 
     # Validators stored against a different URL are not merely useless, they