active_sanction 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6c9a31bd72dfdc43d5614499a19aab837b55996b9644ae145b89da18b93bea6
-  data.tar.gz: 40cbea7b7fcf458307171ca953fb61864dce06da7733ece2ac17e4d27a43215d
+  metadata.gz: ffb2d77bf3207e3ef97a16269dcf91737e20d48871cc2aec9e747d4185793e52
+  data.tar.gz: eeca2cf2bb69972d83e15e982c2daea80969a636e4c88e86cbd29b670420098c
 SHA512:
-  metadata.gz: 892209a20496c2eea1185776a83725cb89ae6c7b40ba2385becf7870b78d8e1a6cf88734e29afec40153418dfa73ac275a3270b0bb16a80e56c3de6605e58652
-  data.tar.gz: e3330620e4c4f6c31c6a7e0c58b53bda9972628e9d6965798d56f666f7301b83ccc2edb42931d15b18b161c9480df96b5147edf0e94b77461e90e0958944ed46
+  metadata.gz: 748d59d2d06bb502eefd684a71c1abc74beb6b03d677eaf9a85c4563945c03fb7c9d69474988319d0ef1f03d4a68c328efd7d63ad14a62d33fa74ef4989e361b
+  data.tar.gz: dc9c4247f9e3ce24772a8045c4e7e0ea992ae7fbeb17c8f2f123f8a9ccf39fd741d7617a98cd67eef5968a16811c2cfc1b42a0c433df3da94d3b8e4f3f624f40

data/CHANGELOG.md

@@ -17,6 +17,58 @@ screening decision would come out as today.
 
 Nothing yet.
 
+## [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 +652,7 @@ 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.0...main
+[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/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
@@ -107,7 +107,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 +128,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 +167,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.
@@ -193,6 +228,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
 
 ```

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
@@ -157,7 +158,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 +288,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

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

data/lib/active_sanction/index.rb

@@ -144,6 +144,28 @@ module ActiveSanction
     # numbers again on another machine.
     POSTINGS_BUDGET = T.let(5_000, Integer)
 
+    # One posting: an Integer in an Array slot, which on a 64-bit CRuby is a
+    # tagged immediate and costs the slot and nothing else. See #profile,
+    # which is where these three are used and where their crudeness is
+    # admitted.
+    #
+    # @api private
+    POSTING_BYTES = T.let(8, Integer)
+
+    # One distinct feature: a short String -- a token, a trigram, a metaphone
+    # key -- plus its slot in a posting Hash and the empty Array header the
+    # slot points at. Measured as an order of magnitude rather than counted.
+    #
+    # @api private
+    FEATURE_BYTES = T.let(120, Integer)
+
+    # One indexed name: an Entry and the Normalizer::Form it holds, both small
+    # objects of references. The Entity and Name they point at belong to the
+    # snapshot and are not counted here.
+    #
+    # @api private
+    ENTRY_BYTES = T.let(200, Integer)
+
     # Entries, in the order they were indexed. The posting lists hold
     # positions in this array.
     sig { returns(T::Array[Entry]).checked(:tests) }
@@ -247,6 +269,45 @@ module ActiveSanction
       }
     end
 
+    # How big this index is, as the `index.build` event reports it: names,
+    # distinct features, postings, and an estimate of what it all weighs.
+    #
+    # Deliberately not #stats, and the difference is the one number #stats
+    # carries that this does not. Counting distinct entities means walking
+    # every entry and uniquing 47,000 ids, which is a fine thing to do in a
+    # benchmark and not a thing to do at the end of every index build -- it
+    # allocates at exactly the moment the heap is already at its peak, with
+    # the snapshot, the builder and the finished index all still alive. The
+    # event reports entity count from the snapshots it read instead, where it
+    # is already known.
+    #
+    # **`bytes` is an estimate, and deliberately a crude one.** Ruby offers no
+    # way to ask what an object graph weighs that does not either walk every
+    # object in the heap or lie, and an index is tens of millions of small
+    # objects. What it counts is the three things that dominate: a posting is
+    # an Integer in an Array slot, a distinct feature is a String plus its
+    # slot in a Hash, and an entry is a small object holding references. What
+    # it deliberately does not count is the Entities and Names themselves --
+    # those are the snapshot's, shared with it rather than owned here, and
+    # counting them would report the same megabytes twice to a host watching
+    # both.
+    #
+    # Good to within a factor a dashboard cares about, which is what "is the
+    # index growing?" and "will another list fit?" actually need. Anything
+    # finer wants a real heap profiler.
+    sig { returns(T::Hash[Symbol, Integer]).checked(:tests) }
+    def profile
+      keys = @tokens.size + @trigrams.size + @phonetics.size
+      # `each_value` rather than a two-parameter block over the Hash: iterating
+      # a Hash as pairs allocates a two-element Array per distinct feature,
+      # which is twenty thousand short-lived objects at the exact moment the
+      # heap is at its peak -- the snapshot, the builder and the finished
+      # index all still alive. #stats can afford that and a build cannot.
+      postings = [@tokens, @trigrams, @phonetics].sum { |space| space.each_value.sum(&:size) }
+      { names: entries.size, keys: keys, postings: postings,
+        bytes: (postings * POSTING_BYTES) + (keys * FEATURE_BYTES) + (entries.size * ENTRY_BYTES) }
+    end
+
     sig { returns(String) }
     def inspect = "#<#{self.class} #{size} names>"
 

data/lib/active_sanction/instrumentation/event.rb

@@ -0,0 +1,122 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module ActiveSanction
+  module Instrumentation
+    # One thing this library did, after it finished doing it.
+    #
+    #   ActiveSanction.configure do |c|
+    #     c.instrumenter = ->(event) { StatsD.timing("sanctions.#{event.name}", event.duration_ms) }
+    #   end
+    #
+    #   event.name       # => :fetch
+    #   event.duration   # => 2.418, seconds
+    #   event[:source]   # => :ofac_sdn
+    #   event[:bytes]    # => 12_845_056
+    #
+    # A subscriber is handed a finished event and never a running one. That is
+    # the difference between this and a block-based instrumenter, and it is
+    # deliberate: a subscriber that cannot wrap the work cannot retry it,
+    # cannot swallow its exception, and cannot leave a `begin` half-entered if
+    # it raises. The cost is that nothing here can time a stage from the
+    # outside -- which nothing needs to, since every event already carries its
+    # own duration.
+    #
+    # ### Every event carries a duration and enough to correlate it
+    #
+    # There are no anonymous timings. `duration` is monotonic seconds, taken
+    # across the stage this event describes, and `started_at` is the wall
+    # clock at its start -- both, because one answers "how long did it take"
+    # and the other answers "when, in the log I am reading beside this". Every
+    # event but `screen` names a `source`; `screen` names the snapshot
+    # checksums it consulted, which is the same question asked of a query.
+    #
+    # ### An event is emitted for work that raised
+    #
+    # With `error` set to the exception, and with whichever payload keys the
+    # stage had filled in before it failed. A publisher that starts timing out
+    # is exactly what a host is watching for, and an instrumentation layer
+    # that only reports successes cannot see it. See Instrumentation.
+    #
+    # Frozen, and its payload with it, so a subscriber cannot edit what the
+    # next one is handed.
+    class Event
+      extend T::Sig
+
+      # The stage this event describes -- one of Instrumentation::EVENTS.
+      sig { returns(Symbol) }
+      attr_reader :name
+
+      # What the stage measured, keyed as documented for each event name in
+      # docs/api_stability.md. Frozen.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      attr_reader :payload
+
+      # The wall clock when the stage started, UTC. For lining an event up
+      # against a log; `duration` is what to measure with.
+      sig { returns(Time) }
+      attr_reader :started_at
+
+      # Seconds the stage took, from a monotonic clock, so it is not moved by
+      # a clock adjustment mid-stage.
+      sig { returns(Float) }
+      attr_reader :duration
+
+      sig do
+        params(name: Symbol, payload: T::Hash[Symbol, T.untyped], started_at: Time, duration: Float).void
+      end
+      def initialize(name:, payload:, started_at:, duration:)
+        @name = T.let(name, Symbol)
+        @payload = T.let(payload.freeze, T::Hash[Symbol, T.untyped])
+        @started_at = T.let(started_at, Time)
+        @duration = T.let(duration, Float)
+        freeze
+      end
+
+      # One payload key, or nil for one this event does not carry.
+      sig { params(key: Symbol).returns(T.untyped) }
+      def [](key) = payload[key]
+
+      # Which list this was about, or nil for an event that is not about one
+      # -- `screen`, which is about a query, and `sync`, which is about a run.
+      sig { returns(T.nilable(Symbol)) }
+      def source = payload[:source]
+
+      # The exception the stage raised, or nil for one that finished. An event
+      # carrying one is a partial measurement: the keys the stage had not
+      # reached are absent rather than zero.
+      sig { returns(T.nilable(StandardError)) }
+      def error = payload[:error]
+
+      sig { returns(T::Boolean) }
+      def failed? = !error.nil?
+
+      # The wall clock when the stage finished. Derived from `started_at` and
+      # the monotonic duration rather than read again, so the two cannot
+      # disagree about how long this took.
+      sig { returns(Time) }
+      def finished_at = started_at + duration
+
+      # Milliseconds, which is what a metrics backend usually wants.
+      sig { returns(Float) }
+      def duration_ms = (duration * 1_000).round(3).to_f
+
+      # The whole event as one Hash, for a subscriber that forwards it
+      # somewhere structured. The payload is spread in at the top level, and
+      # its keys win over nothing -- `name`, `started_at` and `duration` are
+      # not payload keys on any event this library emits.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def to_h
+        { name: name, started_at: started_at, duration: duration }.merge(payload)
+      end
+
+      sig { returns(String) }
+      def to_s = "#{name} #{format("%.3f", duration)}s#{" #{source}" if source}#{" failed" if failed?}"
+
+      sig { returns(String) }
+      def inspect = "#<#{self.class} #{name} #{payload.inspect} #{format("%.3f", duration)}s>"
+    end
+  end
+end