event_rail 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e59345edd1e6e7570345e9b68df5be4b565e5705051d35f854076a64e8fc08b8
-  data.tar.gz: d1391a4e11a36c9a81df720b6cd1376e4ddc79a126fab0fa8988db435a4823b4
+  metadata.gz: 1a5dd4da961fafe8b7a42cadb79cc9fcad3f9da337181a6e53f93ac2e2495f80
+  data.tar.gz: adea011ca9a862030527c8178d67e7165e2d9e17b8902328ed96f698910c9835
 SHA512:
-  metadata.gz: a1bc401719f38d3f8fa654c1aba1df05451aaed81f813c7af74bb6c865ce90f35ccf48d579ec982627d973cd9f705e076b546303fd4b9759d5107dd5d99b9025
-  data.tar.gz: 6200d549898556da58c5d09ebe252373a10d73e4876494850cba5ae6f5603c2d2175b2744801eb02ab8ab57cd8ac9a7c65b7e2c9c34e63fc1906e872636bb8fa
+  metadata.gz: 382236795f226f5dad4979cb2fbb29cac28fd31a4bd0ca7bc77bd8b7b0f7f7279275a4e97f3df1550d3f7dd5fd826e2ed96a682ccdd8b792d0c6d6bd7af73e3a
+  data.tar.gz: b84bba4b3e33f2fd809c7f833cd8913655f555f298828f7080bc8c27e8925cbd02125e3503d2658444d27f16061bc555749235229935dfa1e9cf4342e2be470b

data/CHANGELOG.md

@@ -13,6 +13,63 @@ here unless a release changes how they behave.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-21
+
+### Changed
+
+- **`subscribes_to` now raises `EventRail::DeclarationError` when the event class it names
+  declares neither `event_type` nor `version`**, at the declaration itself. Previously such
+  a subscription was accepted and then never fired: publication matches subscribers by exact
+  event class, so a concrete subclass never reached the base's registration, and the class
+  without a contract could not be constructed to be published on its own. Because neither
+  declaration is inherited, this covers a shared abstract base such as `ApplicationEvent`
+  and equally a subclass of a concrete event that adds nothing of its own. Subscribe to each
+  concrete event class instead.
+
+## [0.2.0] - 2026-09-17
+
+### Added
+
+- `EventRail::TestHelper`, loaded by an explicit `require "event_rail/test_helper"` and not
+  by requiring the library. `EventRail::TestHelper.declare` opens a window in which event
+  contracts and subscriptions may be declared after application preparation has sealed the
+  registry, and `with_subscribers` activates a declared fixture subscriber for the duration
+  of one block, restoring the previous registry afterwards. Contracts declared in a window
+  go live when it closes; subscribers stay dormant until activated, so a fixture cannot fan
+  out in a later test that never mentions it.
+- `config.event_rail.roots`, defaulting to `%w[app/events app/jobs]` and appendable, naming
+  the directories discovery scans. Each entry is matched as a path suffix against the main
+  autoloader's roots, so one entry covers the host application and every engine. A
+  configured root beyond the default that is not an autoload root fails preparation with the
+  new `EventRail::ConfigurationError`; a default root the application has not created is
+  skipped.
+
+### Changed
+
+- **A concrete `EventRail::Event` subclass that declares `event_type` or `version` after
+  preparation now raises `EventRail::DeclarationError` at the declaration**, the same rule
+  subscriptions have always followed. Previously such a class was silently absent from the
+  contract index: it published cleanly, serialized cleanly, and failed only when a worker
+  tried to reconstruct it, with `UnknownEventTypeError`. Move the class under `app/events`,
+  add its root to `config.event_rail.roots`, or -- for a test fixture -- declare it inside
+  `EventRail::TestHelper.declare`. Abstract bases and classes never assigned to a constant
+  are unaffected.
+- A subscription declared on a class with no name now raises where it is declared. Active
+  Job cannot enqueue a job it cannot name, so this was never a working configuration; it was
+  previously dropped from the registry without comment.
+- Both late-declaration messages now name the declaration's own file and line, state that
+  discovery runs before `eager_load!` so `config.eager_load_paths` alone is never enough,
+  and offer both remedies. The advice to load such code from an autoload-once path is gone
+  as general guidance: it never applied to reloadable application code.
+
+### Fixed
+
+- A declaration arriving between a reload's constant unload and the registry rebuild is no
+  longer rejected as late. Rails deletes constants before running prepare callbacks and
+  nothing cleared the snapshot in between, so that window was indistinguishable from a
+  sealed registry -- reachable by any prepare callback ordered ahead of EventRail's,
+  including one belonging to a gem that loads earlier in the Gemfile.
+
 ## [0.1.0] - 2026-09-15
 
 ### Added
@@ -43,5 +100,7 @@ here unless a release changes how they behave.
 - A typed error hierarchy rooted at `EventRail::Error`, distinguishing declaration,
   casting, context, serialization, and publication failures.
 
-[Unreleased]: https://github.com/alexdmtv/event-rail/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/alexdmtv/event-rail/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/alexdmtv/event-rail/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/alexdmtv/event-rail/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/alexdmtv/event-rail/releases/tag/v0.1.0

data/README.md

@@ -2,9 +2,43 @@
 
 [![CI](https://github.com/alexdmtv/event-rail/actions/workflows/ci.yml/badge.svg)](https://github.com/alexdmtv/event-rail/actions/workflows/ci.yml)
 
-EventRail is an early-stage Rails library for immutable domain events and durable fanout through ordinary Active Job subscribers. It builds on Rails conventions instead of introducing a transport, command bus, dependency-injection container, or replacement job runtime.
+When a Rails application grows, the code that places an order ends up naming everything that should happen next: send the confirmation email, update the loyalty balance, notify the warehouse, write the analytics row. Each addition is another dependency in the one place that can least afford them.
 
-EventRail is not ready for production use yet. The public API is still being implemented and validated.
+There are two ways for one part of an application to reach another. The synchronous one — call a method, get an answer — Ruby hands you for free, and it is the one above: the caller names the callee. The other inverts it. One part announces a fact, and whoever cares subscribes. The dependency does not vanish: a subscriber still names the event, and the event belongs to the code that publishes it. But it points the other way, and it is far narrower: a dependency on something that happened, not on how the other side works. What matters is the side that accumulates. Code that invokes every interested party learns a new name for each one; code that announces a fact learns nothing.
+
+Rails ships no way to express the second. `ActiveSupport::Notifications` is in-process and untyped, Active Record callbacks are the coupling you were trying to escape, and an event store asks you to adopt a storage model in order to send one message across a boundary.
+
+EventRail is that second interface. An event is an immutable, versioned value. Every subscriber is an ordinary Active Job that keeps its own queue, retry policy, and concurrency limits, and delivery goes through the queue adapter you already run. The publisher never names a subscriber. There is no transport, no registration API, and no runtime of its own.
+
+EventRail is pre-1.0: the public API may change in a minor release, and every change is documented in the [CHANGELOG](CHANGELOG.md). Delivery semantics, safety limits, and the notification contract are settled and documented below.
+
+## When to use EventRail
+
+EventRail is narrow on purpose: durable fanout across a boundary inside one application, where each subscriber retries independently and the same fact keeps the same identity across every retry and every hop. Reaching for an event store to get that means adopting its storage model too: entities as streams, state rebuilt from history. That is a large commitment for what is, at the boundary, one message. If you want that commitment, or something else entirely, these fit better.
+
+| If you need | Use | Because |
+| --- | --- | --- |
+| An event log: audit history, replay, rebuilding read models | [Rails Event Store](https://railseventstore.org) | It is a store. Events persist in the same transaction as the state that produced them, which also closes the dual-write gap below. |
+| Handlers that run inside the same request | [downstream](https://github.com/palkan/downstream) | Delivery is synchronous by default, async opt-in per subscriber. |
+| In-process decoupling and nothing more | `ActiveSupport::Notifications` | Already in your application. No gem, no contract, no queue. |
+| Events to be the system of record, not a message | [Sequent](https://www.sequent.io) | A full event-sourcing framework: commands, aggregates, projectors. |
+
+**Why not call `perform_later` three times?** That is already durable fanout, and for three jobs in one method it is the right answer. EventRail earns its place when the publisher should not know its subscribers, when the payload needs a versioned contract that outlives a worker running older code, and when a retry must not produce a second copy of a fact already recorded.
+
+### What it gives you
+
+- **Retry-stable identity**, derived from the publishing execution rather than generated, so a redelivered cause produces the same event rather than a second copy of it. Idempotency holds across hops, not only across one subscriber's retries.
+- **Subscribers that are the jobs**, each keeping its own queue, retry policy, and concurrency limits rather than sharing the single wrapper job other gems route subscribers through.
+- **Boot-time validation**: a wrong `perform` arity, a missing `EventRail::JobContext`, or a late declaration fails the boot that introduced it rather than the first publication in production.
+- **A typed boundary**: a `Date`, a `BigDecimal`, a record, or a GlobalID is refused rather than serialized into something a worker cannot restore.
+- **Your own layout**: discovery matches a path suffix against the autoload roots Rails already has, covering engines and a packwerk-style `packs/billing/app/jobs` with no configuration.
+- **No Active Record**, table, migration, or initializer.
+
+### What it does not do
+
+- **No event log and no synchronous handlers.** No history, replay, read-model rebuild, or browser UI, and every subscriber crosses the queue.
+- **No outbox, and so a dual-write gap.** Publication is refused inside a transaction, so a publisher commits and then publishes, and a process that dies between the two loses the event. Publishing from a job makes that recoverable, because the retry republishes under the same identity (see [Replay-safe publishers](#replay-safe-publishers)); from a controller action there is no such guarantee. An application that wants recovery beyond that can record an intent and republish it from a sweeper, but a republication from a different job derives a different event ID, so the intent's own key belongs in the payload for consumers to deduplicate on.
+- **Discovery is enforced, not advisory.** A subscriber outside a [discovery root](#where-discovery-looks) fails the boot rather than being quietly ignored: a silent delivery bug traded for a loud startup error, at the price of a layout rule.
 
 ## Requirements
 
@@ -20,7 +54,7 @@ EventRail depends on Active Support, Active Model, Active Job, Railties, and Zei
 gem "event_rail"
 ```
 
-Then run `bundle install`. There is no initializer to generate and nothing to configure: EventRail initializes itself through a Railtie, and every safety limit is a fixed documented constant.
+Then run `bundle install`. There is no initializer to generate and nothing you have to configure: EventRail initializes itself through a Railtie, every safety limit is a fixed documented constant, and the one option it does expose, [where it looks for events and subscribers](#where-discovery-looks), has a default that most applications never change.
 
 ## Job integration
 
@@ -88,13 +122,13 @@ event.metadata   # immutable metadata; not yet stamped
 
 `attributes` is Active Model's own meaning and is what application code reads. `data` is the single written form that both the queue representation and the public envelope use, so a `Date`, a `BigDecimal`, or a nested Ruby object never reaches a queue adapter or a codec.
 
-Casting refuses to discard information rather than substituting a plausible value. `"abc"` is not `0`, `true` is not `"t"`, a timestamp needs an explicit offset, and a date attribute will not silently drop a time of day. An untyped attribute accepts only recursively JSON-like values — strings, integers, finite floats, booleans, `nil`, arrays, string-keyed hashes — bounded in nesting depth and forbidden from using the `_aj_` prefix Active Job reserves in its own argument encoding. Records, GlobalID values, arbitrary Ruby objects, non-finite numbers, undeclared attributes, and callable defaults are rejected.
+Casting refuses to discard information rather than substituting a plausible value. `"abc"` is not `0`, `true` is not `"t"`, a timestamp needs an explicit offset, and a date attribute will not silently drop a time of day. An untyped attribute accepts only recursively JSON-like values: strings, integers, finite floats, booleans, `nil`, arrays, and string-keyed hashes. Those are bounded in nesting depth and forbidden from using the `_aj_` prefix Active Job reserves in its own argument encoding. Records, GlobalID values, arbitrary Ruby objects, non-finite numbers, undeclared attributes, and callable defaults are rejected.
 
 Constructed events, nested data, metadata, and every contained value are recursively immutable. Two events of one class with equal payload and equal metadata are equal values, which is what lets `assert_enqueued_with(args: [event])` match a published event.
 
 ### Custom attribute types
 
-A custom Active Model type may be used as an attribute type. Rails' `serialize` is documented as producing a value "usable by the database", and a database driver accepts a `Date` or a `BigDecimal` object -- a queue does not, and Active Job does not recurse into a serializer's output, so such a value would reach the adapter raw. Including `EventRail::PortableType` narrows the promise to a JSON primitive, array, or string-keyed hash, and `portable_examples` makes the promise checkable:
+A custom Active Model type may be used as an attribute type. Rails' `serialize` is documented as producing a value "usable by the database", and a database driver accepts a `Date` or a `BigDecimal` object. A queue does not, and Active Job does not recurse into a serializer's output, so such a value would reach the adapter raw. Including `EventRail::PortableType` narrows the promise to a JSON primitive, array, or string-keyed hash, and `portable_examples` makes the promise checkable:
 
 ```ruby
 module Docs
@@ -124,17 +158,37 @@ Docs::ParcelShipped.new(parcel_id: "P-1", weight: 2500).data
 # => { "parcel_id" => "P-1", "weight" => 2500 }
 ```
 
-Every example is round-tripped through JSON when the attribute is declared, so a type that cannot hold up fails at class definition rather than at the first enqueue. A type whose cast value is already a portable scalar -- a plain `:string` subclass, say -- needs none of this.
+Every example is round-tripped through JSON when the attribute is declared, so a type that cannot hold up fails at class definition rather than at the first enqueue. A type whose cast value is already a portable scalar (a plain `:string` subclass, say) needs none of this.
 
 ## Publishing
 
 ```ruby
 module Docs
-  class OnOrderPlacedJob < ApplicationJob
-    subscribes_to OrderPlaced
+  # app/jobs/billing/charge_card_job.rb
+  module Billing
+    class ChargeCardJob < ApplicationJob
+      queue_as :payments
+      retry_on Timeout::Error, attempts: 10
+
+      subscribes_to OrderPlaced
 
-    def perform(event)
-      Rails.logger.info("charging #{event.order_id} idempotently on #{event.id}")
+      def perform(event)
+        Rails.logger.info("charging #{event.order_id} idempotently on #{event.id}")
+      end
+    end
+  end
+
+  # packs/analytics/app/jobs/analytics/record_order_job.rb
+  module Analytics
+    class RecordOrderJob < ApplicationJob
+      queue_as :low
+      discard_on ActiveJob::DeserializationError
+
+      subscribes_to OrderPlaced
+
+      def perform(event)
+        Rails.logger.info("recording #{event.order_id}")
+      end
     end
   end
 end
@@ -148,11 +202,31 @@ publication.accepted_subscribers # subscribers whose enqueue was accepted
 publication.skipped_subscribers  # subscribers whose own enqueue callback declined
 ```
 
+Billing and analytics do not know about each other, and the publishing code names neither. Adding a third subscriber is adding a file; the code that publishes `OrderPlaced` never changes. Each one keeps its own queue and its own failure policy, because each one is just a job. A payment that retries for ten attempts and an analytics write that is discarded when its event can no longer be loaded are the same fanout, configured separately.
+
 Subscribers are discovered from the conventional `app/events` and `app/jobs` roots of the host application and every engine, during Rails preparation. There is no registration API, no initializer, and no registry to query.
 
-`subscribes_to` is exact and not inherited: a subclass of a subscriber is a different job and receives nothing. A subscriber must define its own `perform` taking exactly one required positional event parameter, must not have subclasses, and must include `EventRail::JobContext`. Each of those is checked during preparation, so a mistake fails the boot that introduced it rather than the first publication.
+### Where discovery looks
+
+```ruby
+# doc:illustrative
+# config/application.rb
+config.event_rail.roots << "app/subscribers"   # default: %w[app/events app/jobs]
+```
+
+Each entry is matched as a path suffix against the autoload roots Rails already has, so one entry covers the host application, every engine, and a packwerk-style `packs/billing/app/jobs` without naming any of them. Appending is additive: the defaults stay in effect.
+
+Two things to know before reaching for it. A configured root is eager-loaded during preparation in **every** environment, so naming something broad like `app/models` loads that directory for the application and every engine on each boot and each reload; moving the file is usually the better fix. And a root you name that is not an autoload root of the application or any engine fails preparation with `EventRail::ConfigurationError`, so a typo is a boot error rather than a directory that silently discovers nothing. A *default* root the application has not created is simply skipped, so a fresh application with no `app/events` directory boots normally.
+
+`subscribes_to` is exact and not inherited on either side. A subclass of a subscriber is a different job and receives nothing. A subscriber must define its own `perform` taking exactly one required positional event parameter, must not have subclasses, and must include `EventRail::JobContext`. Each of those is checked during preparation, so a mistake fails the boot that introduced it rather than the first publication. The event class a subscription names must declare a contract of its own. Neither `event_type` nor `version` is inherited, so a shared abstract base and a subclass that adds nothing of its own are both refused, and refused at the declaration itself rather than during preparation, because the class is already loaded by the time the macro reads it. A class that declares one of the two and not the other is a broken contract rather than a base, and still fails preparation naming the event class.
+
+A subscriber must also be reachable by name, because Active Job enqueues a job by name. Declaring a subscription on a class that has none raises immediately, so `Foo.const_set(:Bar, Class.new(ApplicationJob) { subscribes_to Baz })` is not supported; name the class first. The check is on the name the class carries, not on whether a constant resolves to it, so a class with a name nothing resolves to is still dropped from the registry without comment; that is a deliberate limit, not an oversight.
 
-A subscriber declared outside those roots must be loaded before preparation finishes, or declaring it raises: EventRail refuses to run with a subscriber it cannot see at boot. A subscriber required from an initializer works, but initializers run before the main autoloader exists, so such a file has to bring its own event class and job base rather than referencing autoloaded constants. Declaring a subscriber after preparation -- from a test file, or from a lazily autoloaded path outside `app/events` and `app/jobs` -- raises for the same reason, so a test that needs a throwaway subscriber should define it in a file under a conventional root of the test application instead.
+One rule covers both halves of discovery: **an event contract or a subscription declared after preparation has sealed the registry raises**, naming the file and line and the two ways to fix it. EventRail refuses to run with a subscriber that would receive nothing, or with an event class a worker could not reconstruct from the queue.
+
+Adding the directory to `config.eager_load_paths` is never enough on its own, and the reason is Rails' own ordering: prepare callbacks run *before* `eager_load!`, so a reloadable class outside a discovery root cannot be loaded in time in any environment. Either move the file under a discovery root, or [add its root](#where-discovery-looks).
+
+Two exceptions. Code that is not reloadable at all, such as a gem or a file plainly required from an initializer, ran its declaration before preparation, so it is already registered; such a file has to bring its own event class and job base, because initializers run before the main autoloader exists. And a test suite loads after preparation by definition, which is what [`EventRail::TestHelper`](#tests-that-need-their-own-fixtures) is for.
 
 ### At-least-once delivery, and what that means for subscribers
 
@@ -166,7 +240,7 @@ Retries, backoff, discarding, and dead-letter handling stay where they already a
 
 Don't. Publication raises `EventRail::TransactionalPublicationError` when a transaction is open, in every environment, and the fix is to publish after the transaction commits.
 
-Both queue deferral settings are wrong inside a transaction, in opposite directions. With `enqueue_after_transaction_commit` on, the enqueue is deferred past the point where its failure can be reported, so a publication that silently enqueued nothing looks successful. With it off, the enqueue announces a fact that a rollback then contradicts. The check is on the open transaction itself, so it does not depend on the setting — or on Active Record being present at all.
+Both queue deferral settings are wrong inside a transaction, in opposite directions. With `enqueue_after_transaction_commit` on, the enqueue is deferred past the point where its failure can be reported, so a publication that silently enqueued nothing looks successful. With it off, the enqueue announces a fact that a rollback then contradicts. The check is on the open transaction itself, so it does not depend on the setting, or on Active Record being present at all.
 
 ### Replay-safe publishers
 
@@ -187,7 +261,7 @@ Guarding publication behind "did I already transition?" is the failure mode to a
 
 ## Identity, occurrence time, and source
 
-Inside an opted-in job, an event's ID is derived from a permanent EventRail namespace and the resolved source, executing job class, execution scope, event type, version, and logical identity. The execution scope is the same value the event records as its causation: a regular job's own ID, or, for a subscriber, the ID of the event it is handling. That is what makes identity survive more than one hop — a follow-up event published while handling a redelivered cause derives the ID it derived the first time.
+Inside an opted-in job, an event's ID is derived from a permanent EventRail namespace and the resolved source, executing job class, execution scope, event type, version, and logical identity. The execution scope is the same value the event records as its causation: a regular job's own ID, or, for a subscriber, the ID of the event it is handling. That is what makes identity survive more than one hop: a follow-up event published while handling a redelivered cause derives the ID it derived the first time.
 
 Logical identity is chosen in this order: an explicit event ID (an inbound external event), an explicit `key:` passed to `publish`, the class's `identity_by` attributes, or a singleton marker for the first publication of that type in the execution. Provide an explicit key when neither declared identity nor the singleton default can tell two legitimate publications apart:
 
@@ -202,7 +276,7 @@ Changing `identity_by`, changing `default_source`, or renaming a subscriber clas
 
 `occurred_at` is the logical publication time: an explicit timezone-aware value is preserved as the same instant, and otherwise it is the start of the current execution, stable across that execution's retries and never inherited from a cause. Use a persisted domain timestamp when business occurrence time matters. Stored times are UTC at microsecond precision.
 
-`source` identifies a logical producer — not an environment, queue, topic, cluster, or deployment. Any bounded non-empty string is accepted; a stable namespaced value such as `acme.orders` is recommended, and EventRail does no URI parsing.
+`source` identifies a logical producer, not an environment, queue, topic, cluster, or deployment. Any bounded non-empty string is accepted; a stable namespaced value such as `acme.orders` is recommended, and EventRail does no URI parsing.
 
 ## Logical context
 
@@ -216,7 +290,7 @@ end
 
 A nested scope inherits lineage and may add extensions or repeat identical values; replacing an inherited identifier, origin time, or extension value fails rather than rewriting the lineage of a flow already in progress.
 
-Context extensions are durable baggage: opted-in child jobs carry them, and published events merge them with event-local extensions, rejecting conflicting values. They are not the place for domain data — that belongs in declared attributes.
+Context extensions are durable baggage: opted-in child jobs carry them, and published events merge them with event-local extensions, rejecting conflicting values. They are not the place for domain data; that belongs in declared attributes.
 
 ### Reading context
 
@@ -250,9 +324,9 @@ class SendReceiptJob < ApplicationJob
 end
 ```
 
-Reach for `Current` in a subscriber only to hand lineage to something that does not take the event -- a log line, an outbound request header, an APM tag.
+Reach for `Current` in a subscriber only to hand lineage to something that does not take the event: a log line, an outbound request header, an APM tag.
 
-Lineage is isolated per unit of concurrent execution through `ActiveSupport::IsolatedExecutionState`, which defaults to thread isolation. **A host running fibers -- a fiber-per-request server, or a worker that runs jobs on fibers -- must set `config.active_support.isolation_level = :fiber`**, or lineage will be shared between concurrent fibers. That setting is Rails-wide rather than EventRail's, and it governs both `EventRail::Current` and EventRail's own publication state. EventRail documents the requirement rather than claiming an isolation it cannot provide.
+Lineage is isolated per unit of concurrent execution through `ActiveSupport::IsolatedExecutionState`, which defaults to thread isolation. **A host running fibers, whether a fiber-per-request server or a worker that runs jobs on fibers, must set `config.active_support.isolation_level = :fiber`**, or lineage will be shared between concurrent fibers. That setting is Rails-wide rather than EventRail's, and it governs both `EventRail::Current` and EventRail's own publication state. EventRail documents the requirement rather than claiming an isolation it cannot provide.
 
 Leaving it wrong fails loudly rather than silently: under thread isolation two concurrent fibers each establishing context raise `InvalidContext`, because the second inherits the first's identifiers and replacing them is refused. The rule that stops lineage being rewritten mid-flow doubles as a misconfiguration detector.
 
@@ -289,11 +363,67 @@ Application tests use Active Job's own helpers and nothing from EventRail:
 # doc:illustrative
 publication = EventRail.publish(Docs::OrderPlaced.new(order_id: "A-1005", total: "1.00", placed_at: Time.now.utc.iso8601))
 
-assert_enqueued_with(job: Docs::OnOrderPlacedJob, args: [ publication.event ])
+assert_enqueued_with(job: Docs::Billing::ChargeCardJob, args: [ publication.event ])
 perform_enqueued_jobs
 ```
 
-`assert_enqueued_with(args:)` works because events are value objects. For observability assertions, subscribe to the notifications below. EventRail ships no assertion library, observer, or contract-test helper.
+`assert_enqueued_with(args:)` works because events are value objects. For observability assertions, subscribe to the notifications below. EventRail ships no assertion library, observer, or contract-test helper; Active Job's helpers are the whole assertion surface.
+
+### Tests that need their own fixtures
+
+A test file loads after preparation, so declaring a throwaway event or subscriber in one would raise. `EventRail::TestHelper` is the door for it, and it is opt-in:
+
+```ruby
+# doc:illustrative
+# test/test_helper.rb
+require "event_rail/test_helper"
+
+class ActiveSupport::TestCase
+  include EventRail::TestHelper
+end
+```
+
+Declare fixtures at file scope, in a window:
+
+```ruby
+EventRail::TestHelper.declare do
+  module OrderTests
+    class Placed < EventRail::Event
+      event_type "docs.order_tests_placed"
+      version 1
+      default_source "tests"
+
+      attribute :order_id, :string
+    end
+
+    class AuditJob < ApplicationJob
+      subscribes_to Placed
+
+      def perform(event) = Rails.logger.info(event.order_id)
+    end
+  end
+end
+```
+
+**A subscriber declared in a window receives nothing until you activate it.** That is deliberate: a fixture that went live on declaration would fan out in every later test in the process, including tests that never mention it. Activate it for one block:
+
+```ruby
+# doc:illustrative
+test "publication fans out to the audit job" do
+  with_subscribers(OrderTests::AuditJob) do
+    publication = EventRail.publish(OrderTests::Placed.new(order_id: "o-1"))
+
+    assert_enqueued_with(job: OrderTests::AuditJob, args: [ publication.event ])
+    perform_enqueued_jobs
+  end
+end
+```
+
+The previous registry is restored when the block exits, including when it raises, and nested activations are additive. Activation applies the same validation preparation does, so an abstract fixture fails there rather than at delivery.
+
+Event contracts behave differently from subscribers on purpose: they are registered when the window closes and stay registered, because `assert_enqueued_with` deserializes the job it is comparing and so needs the contract outside any block. A class cannot be unloaded, which has one consequence worth knowing: **give each fixture a unique `event_type`, and declare it once, at file scope.** Two live classes claiming one type and version fail every later rebuild for the rest of the process, and a declaration inside a test method reopens the same constant and runs the writer again on a sealed registry.
+
+Activation replaces a process-wide registry, so it is not safe under `parallelize(with: :threads)`. Process-based parallelisation, the Rails default, is unaffected.
 
 ## Notifications
 
@@ -342,7 +472,7 @@ The private Active Job representation and the job context entry each carry their
 2. Only then deploy a release that writes the new form.
 3. Remove the old reader only after every queued message in the old form is drained or expired.
 
-Rolling back reverses that: a rollback is safe only to a release that can still read what the newer release wrote. A change to how an individual value is written is a different matter — that encoding is shared with the public envelope, so it is a breaking public change rather than a private format bump.
+Rolling back reverses that: a rollback is safe only to a release that can still read what the newer release wrote. A change to how an individual value is written is a different matter: that encoding is shared with the public envelope, so it is a breaking public change rather than a private format bump.
 
 ## Development
 

data/lib/event_rail/errors.rb

@@ -13,6 +13,12 @@ module EventRail
   class DeclarationError < Error
   end
 
+  # An application's own configuration is wrong: a discovery root that is not an autoload
+  # root of the application or any engine. Distinct from a declaration fault, which is about
+  # a class body, and raised at preparation so it fails the boot that introduced it.
+  class ConfigurationError < Error
+  end
+
   # A value cannot become the declared type without discarding information, or is not
   # portable at all.
   class CastingError < Error

data/lib/event_rail/event.rb

@@ -43,6 +43,12 @@ module EventRail
           raise DeclarationError, "event_type exceeds #{Limits::MAX_EVENT_TYPE_BYTES} bytes"
         end
 
+        # Only a change is a declaration. Re-running a class body that sets the same value --
+        # a `load` rather than a `require`, a reopened class -- alters no contract, so the
+        # index is already correct and rejecting it would be a false positive.
+        unless @event_type == value
+          Internal::Registry.declare_contract(self, caller_locations(1, 1).first)
+        end
         @event_type = value.dup.freeze
       end
 
@@ -53,6 +59,9 @@ module EventRail
           raise DeclarationError, "version must be a positive integer"
         end
 
+        unless @event_version == value
+          Internal::Registry.declare_contract(self, caller_locations(1, 1).first)
+        end
         @event_version = value
       end
 

data/lib/event_rail/internal/registry.rb

@@ -12,7 +12,14 @@ module EventRail
     # to have no subscribers: the first is a boot-order bug and raises, the second is a
     # legitimate zero-delivery publication.
     class Registry
-      CONVENTIONAL_ROOTS = %w[app/events app/jobs].freeze
+      # The conventional discovery roots. Matched as a path suffix against the main
+      # autoloader's roots, which is what makes one entry cover the host application, every
+      # engine, and packwerk-style `packs/*/app/jobs` without naming any of them.
+      #
+      # An application may append through `config.event_rail.roots`. The default is copied
+      # rather than shared, so `<<` works and cannot mutate this constant.
+      DEFAULT_ROOTS = %w[app/events app/jobs].freeze
+      CONVENTIONAL_ROOTS = DEFAULT_ROOTS
 
       Snapshot = Struct.new(:subscribers, :contracts, keyword_init: true) do
         def subscribers_for(event_class)
@@ -34,23 +41,69 @@ module EventRail
       @pending = []
       @snapshot = nil
       @building = false
+      # A test declaration window, opened by EventRail::TestHelper.declare. Distinct from
+      # @building: a window routes subscriptions to the dormant fixture set rather than to
+      # the live pending list, which is what keeps a fixture from fanning out to every
+      # later test in the process.
+      @window = false
+      @fixtures = []
+      # Set from `before_class_unload`, which fires first in a reload cycle, and cleared when
+      # preparation finishes. Rails deletes the constants and only then runs prepare
+      # callbacks, and nothing clears the snapshot in between -- so without this flag the
+      # window between the two is indistinguishable from a sealed registry, and a legal
+      # declaration arriving there would be rejected for lateness.
+      @reloading = false
+      # Subscribers activated for the duration of a block, and the snapshot and fixture set
+      # to restore when it exits. A stack, so nested activations are additive.
+      @active_fixtures = []
+      @activations = []
 
       class << self
         # Appending is idempotent per job class: the macro may be called more than once
         # in one body, and the declarations themselves live on the job class.
-        def declare(job_class)
+        def declare(job_class, location = nil)
           @monitor.synchronize do
-            if @snapshot && !@building
+            if @window
+              @fixtures << job_class unless @fixtures.include?(job_class)
+              next
+            end
+
+            if @snapshot && !@building && !@reloading
               raise DeclarationError,
-                "#{job_class} declared a subscription after EventRail finished preparing, so it would receive no " \
-                "deliveries. Move it under a conventional app/events or app/jobs root, or load it from an " \
-                "autoload-once path or plain require before application preparation."
+                "#{named(job_class)}#{" (#{at(location)})" if location} declared a subscription after EventRail finished " \
+                "preparing, so it would receive no deliveries. #{discovery_advice}. A subscriber in a gem that is " \
+                "not loaded at boot can be required from an initializer. In a test, define it inside " \
+                "EventRail::TestHelper.declare."
             end
 
             @pending << job_class unless @pending.include?(job_class)
           end
         end
 
+        # The contract half of the sealing rule, called from the writer form of
+        # `EventRail::Event.event_type` and `.version`. A check only: contracts are collected
+        # by rescanning `EventRail::Event.descendants` when a snapshot is built, so there is
+        # no pending list for events and nothing here to keep reload-safe.
+        #
+        # Named classes only. An unnamed class can never enter the index -- `build_contracts`
+        # selects through `live?`, which resolves the constant the name denotes -- so checking
+        # one would reject every inline event definition in a test suite for no guarantee
+        # gained.
+        def declare_contract(event_class, location = nil)
+          return if event_class.name.nil?
+
+          @monitor.synchronize do
+            next unless @snapshot
+            next if @building || @reloading || @window
+
+            raise DeclarationError,
+              "#{named(event_class)}#{" (#{at(location)})" if location} declared an event contract after EventRail " \
+              "finished preparing, so a worker could not reconstruct it from the queue. #{discovery_advice}. An " \
+              "event class in a gem that is not loaded at boot can be required from an initializer. In a test, " \
+              "define it inside EventRail::TestHelper.declare."
+          end
+        end
+
         def snapshot
           snapshot = @snapshot
           return snapshot if snapshot
@@ -64,6 +117,17 @@ module EventRail
           !@snapshot.nil?
         end
 
+        # Marks the start of a reload cycle. Registered once from a Railtie initializer, never
+        # from preparation: a callback registered inside `prepare` would be added again on
+        # every reload and accumulate for the life of the process.
+        def reloading!
+          @monitor.synchronize { @reloading = true }
+        end
+
+        def reloading?
+          @reloading
+        end
+
         def subscribers_for(event_class)
           snapshot.subscribers_for(event_class)
         end
@@ -80,6 +144,11 @@ module EventRail
               @snapshot = build_snapshot
             ensure
               @building = previously_building
+              # Cleared here rather than from a reloader callback because the two reload paths
+              # differ: a console `reload!` runs prepare twice, the executor path that serves a
+              # request runs it once. The end of preparation is the only point correct for
+              # both. In `ensure`, so a failed prepare does not leave sealing disabled.
+              @reloading = false
             end
           end
           @snapshot
@@ -100,11 +169,90 @@ module EventRail
           end
         end
 
+        # Opens a test declaration window. Subscriptions declared inside become dormant
+        # fixtures; event contracts declared inside are indexed when the window closes,
+        # because `build_contracts` rescans `EventRail::Event.descendants` and a named class
+        # stays there for the life of the process.
+        #
+        # The monitor is held across the yield, as `reopen` does, because a window is opened
+        # at file scope before any test runs. `activate` deliberately does not, since it
+        # yields to arbitrary test code.
+        def declare_fixtures
+          @monitor.synchronize do
+            unless @activations.empty?
+              raise ArgumentError,
+                "a declaration window cannot be opened inside with_subscribers, because closing it rebuilds the " \
+                "registry and would discard the activation"
+            end
+
+            previously = @window
+            @window = true
+            begin
+              yield
+            ensure
+              @window = previously
+            end
+
+            # Rebuilding here is what puts window-declared contracts in the index. Nothing
+            # is eager-loaded: the window body has already run.
+            @snapshot = build_snapshot(extra_subscribers: @active_fixtures) if @snapshot
+          end
+        end
+
+        # Activates dormant fixture subscribers for the duration of the block, then restores
+        # the previous snapshot. The block runs outside the monitor: a test may spawn a
+        # thread that calls `prepare`, and holding the lock across the yield would deadlock
+        # it.
+        def activate(job_classes)
+          restore = nil
+
+          @monitor.synchronize do
+            validate_activation!(job_classes)
+
+            # Built before anything is committed: `build_snapshot` applies the same
+            # validation preparation does, so an abstract or context-less fixture raises
+            # here. Assigning first would leave the failed fixture active for every later
+            # activation in the process.
+            # Deduplicated: activating a fixture that an enclosing block already activated
+            # must not register it twice, which would double its fanout -- the same defect
+            # `prune_stale_declarations` exists to prevent on the reload path.
+            fixtures = (@active_fixtures + job_classes).uniq
+            candidate = build_snapshot(extra_subscribers: fixtures)
+
+            restore = [ @snapshot, @active_fixtures ]
+            @snapshot = candidate
+            @active_fixtures = fixtures
+            @activations.push(restore)
+          end
+
+          begin
+            yield
+          ensure
+            @monitor.synchronize do
+              @snapshot, @active_fixtures = restore
+              @activations.pop
+            end
+          end
+        end
+
+        def fixtures
+          @fixtures.dup.freeze
+        end
+
         def reset!
           @monitor.synchronize do
             @pending = []
             @snapshot = nil
             @building = false
+            @window = false
+            @reloading = false
+            @active_fixtures = []
+            @activations = []
+            # @fixtures is deliberately not cleared, for the same reason the pending list is
+            # pruned rather than emptied: a fixture is declared once at file scope and its
+            # window never runs again, so clearing it would leave every later activation in
+            # the process unable to find it. Fixtures are dormant, so keeping them changes
+            # no snapshot.
           end
         end
 
@@ -118,8 +266,11 @@ module EventRail
             loader = Rails.autoloaders.main
             return unless loader.respond_to?(:eager_load_dir)
 
+            roots = configured_roots
+            validate_roots!(roots, loader)
+
             loader.dirs.each do |dir|
-              next unless CONVENTIONAL_ROOTS.any? { |root| dir.end_with?("/#{root}") }
+              next unless roots.any? { |root| dir.end_with?("/#{root}") }
               next unless Dir.exist?(dir)
 
               begin
@@ -132,6 +283,75 @@ module EventRail
             end
           end
 
+          # Both late-declaration messages share this. It interpolates the configured roots
+          # rather than hardcoding the defaults, and it names the ordering fact that makes the
+          # obvious fix wrong: Rails runs prepare callbacks before `eager_load!`, so adding a
+          # directory to `eager_load_paths` is always too late.
+          def discovery_advice
+            # Falls back to the default rather than raising: this builds the text of another
+            # error, and a misconfigured roots value has its own error from `validate_roots!`
+            # at preparation.
+            roots = configured_roots
+            roots = DEFAULT_ROOTS.dup unless well_formed_roots?(roots)
+            "EventRail discovers #{roots.join(" and ")} in the application and its engines, and discovery runs " \
+              "before eager_load!, so adding the directory to eager_load_paths is not enough: move the file under " \
+              "#{roots.first}, or add its root to config.event_rail.roots (which eager-loads that directory " \
+              "during preparation in every environment)"
+          end
+
+          # `to_s` on a class whose `name` was overridden still reports the anonymous form, and
+          # the name is what an adopter searches for.
+          def named(klass)
+            klass.name || klass.inspect
+          end
+
+          # Relative to the application root, so the message names the file the way an editor
+          # does rather than with an absolute path.
+          def at(location)
+            path = location.path
+            root = Rails.root.to_s if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+            path = path.delete_prefix("#{root}/") if root
+
+            "#{path}:#{location.lineno}"
+          end
+
+          # Copied on every read, so the registry never holds a reference the application can
+          # mutate afterwards and repeated reloads cannot accumulate entries.
+          def configured_roots
+            configured =
+              if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+                Rails.application.config.event_rail&.roots
+              end
+
+            (configured || DEFAULT_ROOTS).dup
+          end
+
+          def well_formed_roots?(roots)
+            roots.is_a?(Array) && roots.all? { |root| root.is_a?(String) && !root.empty? }
+          end
+
+          # Only entries beyond the default are checked. Rails registers an `app/*` directory
+          # with the main loader only when it exists, so a freshly generated application that
+          # has not created `app/events` yet has no such root -- validating the defaults would
+          # fail its boot before it had written a single event. A missing default is a
+          # convention not yet used; a missing entry the application typed is a mistake.
+          def validate_roots!(roots, loader)
+            unless well_formed_roots?(roots)
+              raise ConfigurationError,
+                "config.event_rail.roots must be an array of non-empty strings; got #{roots.inspect}"
+            end
+
+            dirs = loader.dirs.map(&:to_s)
+
+            (roots - DEFAULT_ROOTS).each do |root|
+              next if dirs.any? { |dir| dir.end_with?("/#{root}") }
+
+              raise ConfigurationError,
+                "config.event_rail.roots names #{root.inspect}, which is not an autoload root of the application " \
+                "or any engine"
+            end
+          end
+
           # A reload replaces class objects while leaving the previous ones reachable
           # from this list. An entry survives only if the constant its own name denotes
           # is still this exact object, which is what distinguishes a live class from a
@@ -156,11 +376,17 @@ module EventRail
             resolved.equal?(klass)
           end
 
-          def build_snapshot
+          # `extra_subscribers` carries fixtures activated for a block. They are not added to
+          # the pending list, so the next rebuild without them drops them again.
+          def build_snapshot(extra_subscribers: EMPTY_SUBSCRIBERS)
             contracts = build_contracts
             subscribers = {}
 
-            @pending.each do |job_class|
+            # The pending list is filtered here, not only pruned by preparation. A snapshot
+            # may be built without a preceding prune -- `activate` does exactly that -- and
+            # the list can hold an entry whose macro ran before a later argument raised, so
+            # a snapshot must never validate a class the constant no longer denotes.
+            (@pending.select { |job_class| live?(job_class) } + extra_subscribers).uniq.each do |job_class|
               validate_subscriber!(job_class)
 
               job_class.event_rail_subscriptions.each do |event_class|
@@ -186,6 +412,30 @@ module EventRail
             ContractIndex.build(concrete)
           end
 
+          # These are caller mistakes in a test, not failures of the library's declaration
+          # rules, so they raise ArgumentError: an adopter rescuing EventRail::Error should
+          # not catch them.
+          def validate_activation!(job_classes)
+            job_classes.each do |job_class|
+              if job_class.name.nil?
+                raise ArgumentError,
+                  "#{job_class.inspect} has no name, and Active Job cannot enqueue a job it cannot name; " \
+                  "assign the class to a constant"
+              end
+
+              next if @fixtures.include?(job_class)
+
+              if @pending.include?(job_class)
+                raise ArgumentError,
+                  "#{job_class} is already a live subscriber; with_subscribers is for fixtures declared in a test"
+              end
+
+              raise ArgumentError,
+                "#{job_class} was not declared inside EventRail::TestHelper.declare, so with_subscribers cannot " \
+                "activate it"
+            end
+          end
+
           def validate_subscriber!(job_class)
             unless job_class.instance_methods(false).include?(:perform) ||
                 job_class.private_instance_methods(false).include?(:perform)

data/lib/event_rail/railtie.rb

@@ -6,10 +6,31 @@ module EventRail
     # eager_load!, so no reloadable constant outside a conventional root can already be
     # loaded here -- which is exactly why one declared there raises later instead of
     # silently receiving nothing.
+    # The directories discovery scans, matched as a path suffix against the main
+    # autoloader's roots. An application appends to it; the default is a mutable copy, so
+    # `config.event_rail.roots << "app/subscribers"` works.
+    config.event_rail = ActiveSupport::OrderedOptions.new
+    config.event_rail.roots = Internal::Registry::DEFAULT_ROOTS.dup
+
     config.to_prepare do
       # Unqualified, so lexical lookup reaches the private Internal namespace that a
       # qualified EventRail::Internal reference would be refused.
       Internal::Registry.prepare
     end
+
+    # A reload deletes the constants and only then runs prepare callbacks, and nothing
+    # clears the snapshot in between -- so a declaration arriving in that window would be
+    # rejected for lateness even though the imminent prepare would have registered it. That
+    # window is reachable by any prepare callback ordered ahead of EventRail's, which is the
+    # case for one registered directly on the reloader from an initializer, or belonging to
+    # a gem that loads earlier in the Gemfile.
+    #
+    # An initializer rather than a prepare block: registering the callback from `prepare`
+    # would add it again on every reload.
+    initializer "event_rail.mark_reload_window" do |app|
+      if app.config.reloading_enabled?
+        app.reloader.before_class_unload { Internal::Registry.reloading! }
+      end
+    end
   end
 end

data/lib/event_rail/subscriptions.rb

@@ -16,10 +16,12 @@ module EventRail
   # missing that inclusion fails application preparation with a precise message
   # instead of a bare NoMethodError on the macro.
   module Subscriptions
-    # Declares the exact event classes this job handles. The relationship is recorded
-    # for preparation to validate: `perform` is usually defined after this line, and
-    # whether this class has subclasses is not knowable until everything is loaded, so
-    # only what can be judged immediately is judged here.
+    # Declares the exact event classes this job handles. Only what can be judged
+    # immediately is judged here: that each argument is an event class, that it declares an
+    # event_type or a version, that it is not a repeat, and that this job has a name. The rest
+    # is recorded for preparation to validate, because `perform` is usually defined after
+    # this line and whether this class has subclasses is not knowable until everything is
+    # loaded.
     def subscribes_to(*event_classes)
       if event_classes.empty?
         raise DeclarationError, "#{self} must name at least one event class to subscribe to"
@@ -32,6 +34,19 @@ module EventRail
           raise DeclarationError,
             "#{self} cannot subscribe to #{event_class.inspect}, which is not an EventRail::Event class"
         end
+        # Judged here rather than during preparation because it is already knowable: the
+        # constant reference above has loaded the event class, so in any ordinary load order
+        # its contract is final. A class that declares neither half is an abstract base, or a
+        # subclass that declared none of its own, and either way publication -- which matches
+        # subscribers by exact class -- could never reach it.
+        unless event_class.concrete?
+          raise DeclarationError,
+            "#{self} cannot subscribe to #{event_class}, which declares neither event_type nor version and so " \
+            "can never be published; the subscription would receive nothing. Neither declaration is inherited, " \
+            "so a subclass of a concrete event needs its own. Subscribe to each concrete event class instead, " \
+            "or, if #{event_class} declares its contract outside its own class body, make that run before this " \
+            "subscription is declared."
+        end
         if own.include?(event_class)
           raise DeclarationError, "#{self} already declares a subscription to #{event_class}"
         end
@@ -39,7 +54,20 @@ module EventRail
         own << event_class
       end
 
-      Internal::Registry.declare(self)
+      # Checked here rather than during preparation, and after the arguments above rather
+      # than before them. Active Job cannot enqueue a job it cannot name, so an anonymous
+      # subscriber is never a working configuration -- but preparation is the wrong place to
+      # say so: the macro has already recorded the class by then, and rejecting it there
+      # would make every later rebuild in the process fail, including in unrelated tests.
+      # After the argument checks, because a bad argument on an anonymous class deserves the
+      # specific error rather than this one.
+      if name.nil?
+        raise DeclarationError,
+          "#{inspect} declared a subscription but has no name, and Active Job cannot enqueue a job it cannot " \
+          "name; assign the class to a constant"
+      end
+
+      Internal::Registry.declare(self, caller_locations(1, 1).first)
       include Internal::SubscriberExecution unless include?(Internal::SubscriberExecution)
 
       event_rail_subscriptions

data/lib/event_rail/test_helper.rb

@@ -0,0 +1,74 @@
+require "event_rail"
+
+module EventRail
+  # Test support, loaded only by an explicit `require "event_rail/test_helper"`. Requiring
+  # the library does not load it, and requiring it does not by itself weaken the rule that
+  # a declaration arriving after preparation is an error.
+  #
+  #   # test/test_helper.rb
+  #   require "event_rail/test_helper"
+  #
+  #   class ActiveSupport::TestCase
+  #     include EventRail::TestHelper
+  #   end
+  #
+  # Including the module adds `with_subscribers` and nothing else. `declare` stays a module
+  # method rather than becoming an instance method on every test case, because the name is
+  # general enough to collide.
+  module TestHelper
+    # Opens a window in which event contracts and subscriptions may be declared even though
+    # preparation has already sealed the registry. Fixtures go at file scope, once per
+    # process:
+    #
+    #   EventRail::TestHelper.declare do
+    #     module OrderTests
+    #       class Placed < EventRail::Event
+    #         event_type "tests.order_placed"
+    #         version 1
+    #         default_source "tests"
+    #
+    #         attribute :order_id, :string
+    #       end
+    #
+    #       class AuditJob < ApplicationJob
+    #         subscribes_to Placed
+    #
+    #         def perform(event) = (self.class.seen << event)
+    #       end
+    #     end
+    #   end
+    #
+    # Contracts declared here are indexed when the window closes and stay indexed: a class
+    # cannot be unloaded, so two fixtures claiming one event type and version fail every
+    # later rebuild, not just the first. Give each fixture a unique type, and declare it at
+    # file scope -- a declaration inside a test method reopens the same constant and runs the
+    # writer again on a sealed registry.
+    #
+    # Subscriptions declared here are dormant. They receive nothing until `with_subscribers`
+    # activates them, so a fixture cannot fan out in a later test that never mentions it.
+    def self.declare(&block)
+      # Unqualified, so lexical lookup reaches the private Internal namespace that a
+      # qualified EventRail::Internal reference would be refused.
+      Internal::Registry.declare_fixtures(&block)
+    end
+
+    # Activates fixture subscribers for the duration of the block and restores the previous
+    # registry afterwards, including when the block raises. Nested calls are additive.
+    #
+    #   test "publication fans out to the audit job" do
+    #     with_subscribers(OrderTests::AuditJob) do
+    #       publication = EventRail.publish(OrderTests::Placed.new(order_id: "o-1"))
+    #
+    #       assert_enqueued_with job: OrderTests::AuditJob, args: [ publication.event ]
+    #     end
+    #   end
+    #
+    # The registry snapshot this replaces is process-wide, so activation is not safe under
+    # thread-based test parallelisation (`parallelize(with: :threads)`). Process-based
+    # parallelisation, which is the Rails default, is unaffected because each worker has its
+    # own registry.
+    def with_subscribers(*job_classes, &block)
+      Internal::Registry.activate(job_classes.flatten, &block)
+    end
+  end
+end

data/lib/event_rail/version.rb

@@ -1,3 +1,3 @@
 module EventRail
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: event_rail
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Alex Dmitriev
@@ -153,6 +153,7 @@ files:
 - lib/event_rail/publish.rb
 - lib/event_rail/railtie.rb
 - lib/event_rail/subscriptions.rb
+- lib/event_rail/test_helper.rb
 - lib/event_rail/version.rb
 homepage: https://github.com/alexdmtv/event-rail
 licenses: