event_rail 0.3.0 → 0.5.0

data/lib/event_rail/internal/identity.rb

@@ -1,38 +1,56 @@
 require "active_support/core_ext/digest/uuid"
+require "active_support/core_ext/object/blank"
 require "bigdecimal"
 require "date"
 
 module EventRail
   module Internal
-    # Retry-stable publication identity.
+    # Publication identity: the ID an event derives, so that the same fact published
+    # again derives the same ID and a consumer can collapse the duplicates at-least-once
+    # delivery guarantees it will see.
     #
-    # The whole point is that the same logical fact, published again by the same
-    # execution, derives the same event ID -- so a consumer can collapse the
-    # duplicates at-least-once delivery guarantees it will see. That makes both the
-    # namespace and the encoding permanent compatibility state: changing either
-    # silently gives every future publication a different ID for an unchanged fact,
-    # which is why the golden vectors are asserted rather than merely computed.
+    # Two derivations, told apart by a leading tag so their inputs never coincide:
+    #
+    #   fact       ["fact", source, event_type, identity_list]
+    #              for an event with declared identity. Nothing about who published it,
+    #              when, or in which schema version: one fact, one ID, everywhere.
+    #   execution  ["execution", source, job_class, scope, event_type, version, SINGLETON]
+    #              for an event without declared identity, published inside a job. Stable
+    #              across that job's retries and across redeliveries of the event a
+    #              subscriber handles, and nothing more.
+    #
+    # The namespace, the tags, the component order and the byte encoding are permanent
+    # compatibility state, documented in the README with vectors other implementations
+    # can reproduce; changing any of them silently gives every future publication a
+    # different ID for an unchanged fact, which is why the vectors are asserted rather
+    # than merely computed.
     module Identity
       module_function
 
-      # Derived from the URL namespace rather than written as a literal, so the input
-      # that produced it stays visible and a typo cannot masquerade as a deliberate
-      # value. The golden-vector test pins the result.
-      NAMESPACE = Digest::UUID.uuid_v5(
-        Digest::UUID::URL_NAMESPACE, "https://github.com/event_rail/event_rail/identity/v1"
-      ).freeze
+      # A literal, owned by this project and named nowhere else, so no one else's
+      # derivation can land in the same space.
+      NAMESPACE = "21fedac0-42c6-443f-b01c-6980aab52f32".freeze
 
-      # The first publication of an event type in one execution needs no key: there is
-      # nothing to distinguish it from.
+      # Closes the execution rule's name: an undeclared event is identified by the
+      # execution and its type alone, which is why one execution publishes it once.
       SINGLETON = :__event_rail_singleton__
 
-      def derive(source:, job_class:, scope:, event_type:, version:, logical_identity:)
-        Digest::UUID.uuid_v5(
-          NAMESPACE,
-          encode([ source, job_class, scope, event_type, version, logical_identity ])
-        )
+      # `identity` is always a list: the declared attributes' values in declaration
+      # order, or one explicit publication identity. So an explicit "a" and a single
+      # declared attribute whose value is "a" name the same fact.
+      def fact(source:, event_type:, identity:)
+        raise ArgumentError, "fact identity must be a list; got #{identity.inspect}" unless identity.is_a?(Array)
+
+        uuid_v5(encode([ "fact", source, event_type, identity ]))
+      end
+
+      def execution(source:, job_class:, scope:, event_type:, version:)
+        uuid_v5(encode([ "execution", source, job_class, scope, event_type, version, SINGLETON ]))
       end
 
+      def uuid_v5(name) = Digest::UUID.uuid_v5(NAMESPACE, name)
+      private_class_method :uuid_v5
+
       # Length-delimited and type-tagged. Ruby's own Hash#hash is per-process, inspect
       # is not a format, and a plain join makes ["ab", "c"] and ["a", "bc"] the same
       # string. A tag also keeps 1 and "1" apart, so a call site that passes an integer
@@ -44,7 +62,7 @@ module EventRail
       def encode_component(value)
         tag, bytes = case value
         when SINGLETON then [ "*", "" ]
-        when String then [ "s", value.b ]
+        when String then [ "s", utf8_bytes(value) ]
         when true then [ "b", "true" ]
         when false then [ "b", "false" ]
         when Integer then [ "i", value.to_s ]
@@ -67,6 +85,18 @@ module EventRail
         "#{tag}#{bytes.bytesize}:#{bytes}"
       end
 
+      # A string is hashed as its UTF-8 bytes, with no Unicode normalization: the same
+      # text in another normal form is another identity, so a producer must send the same
+      # bytes. Bytes that are not valid UTF-8 have no portable spelling at all.
+      def utf8_bytes(value)
+        utf8 = value.encoding == Encoding::UTF_8 ? value : value.encode(Encoding::UTF_8)
+        reject!(value, "valid UTF-8") unless utf8.valid_encoding?
+        utf8.b
+      rescue EncodingError
+        reject!(value, "valid UTF-8")
+      end
+      private_class_method :utf8_bytes
+
       # An identity component that is a structure cannot be canonicalized without
       # choosing an ordering and a separator that would then be permanent, and one
       # that is null cannot identify anything.

data/lib/event_rail/internal/notifications.rb

@@ -2,7 +2,7 @@ require "active_support/notifications"
 
 module EventRail
   module Internal
-    # Payloads for the four public notifications.
+    # Payloads for the five public notifications.
     #
     # Contract, identity, and lineage only. Domain data and extensions are excluded by
     # construction rather than by filtering, because a notification payload reaches logs

data/lib/event_rail/internal/registry.rb

@@ -140,6 +140,7 @@ module EventRail
             @building = true
             begin
               eager_load_conventional_roots
+              Stager.validate!
               prune_stale_declarations
               @snapshot = build_snapshot
             ensure

data/lib/event_rail/internal/stager.rb

@@ -0,0 +1,99 @@
+module EventRail
+  module Internal
+    # Finds the application's stager: what `EventRail.stage` hands an event's subscriber
+    # jobs to, in place of enqueuing them.
+    #
+    # Configured by name as a rule. A stager is usually an application model, which cannot be
+    # loaded while `config/application.rb` or an initializer runs and is replaced on every
+    # reload in development, so a class held by reference would either fail the boot or go
+    # stale. The name is resolved again on every staging, the way `belongs_to` resolves
+    # `class_name:`. An object is used as given, for a stager that is never reloaded.
+    module Stager
+      SETTING = "config.event_rail.stager".freeze
+      # Ruby's own rule for a constant name, Unicode included: an uppercase letter, then word
+      # characters.
+      CONSTANT_PATH = /\A(?:::)?[[:upper:]][[:word:]]*(?:::[[:upper:]][[:word:]]*)*\z/
+
+      module_function
+
+      # The configured value, or a configuration error when there is no Rails application
+      # to read it from: staging has nowhere else to find a stager.
+      def configured
+        unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+          raise ConfigurationError,
+            "EventRail.stage reads #{SETTING} from the Rails application, and there is none"
+        end
+
+        ::Rails.application.config.event_rail&.stager
+      end
+
+      def resolve(configured)
+        if configured.nil?
+          raise ConfigurationError,
+            "EventRail.stage needs a stager; set #{SETTING} to the name of a class that responds to stage(jobs)"
+        end
+
+        stager = configured.is_a?(String) || configured.is_a?(Symbol) ? constantize(configured.to_s) : configured
+        return stager if stager.respond_to?(:stage)
+
+        raise ConfigurationError, "#{SETTING} is #{configured.inspect}, which does not respond to stage(jobs)"
+      end
+
+      # Called from preparation, which runs after the autoloaders are set up and again on
+      # every reload, so a misspelled name or a missing method fails the boot that
+      # introduced it rather than the first staging. Nothing to check without a Rails
+      # application, or with no stager configured: an application that never stages needs
+      # none.
+      def validate!
+        return unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+        value = configured
+        resolve(value) unless value.nil?
+      end
+
+      # Only a constant the name itself denotes being missing is a configuration error: the
+      # name, or one of the namespaces it passes through. That is decided by where the lookup
+      # failed -- which constant was missing, and in which namespace -- rather than by comparing
+      # strings, so a name that passes through an alias of a namespace is judged by the
+      # namespace it reaches. Anything else raised while loading the stager is a bug in its
+      # file, left alone so its backtrace points there: a NameError naming no constant, one
+      # missing from some other namespace, or Zeitwerk's, which means the file exists and
+      # defines the wrong thing.
+      def constantize(name)
+        unless name.match?(CONSTANT_PATH)
+          raise ConfigurationError, "#{SETTING} is #{name.inspect}, which is not a constant name"
+        end
+
+        ActiveSupport::Inflector.constantize(name)
+      rescue NameError => error
+        raise if defined?(::Zeitwerk::NameError) && error.is_a?(::Zeitwerk::NameError)
+        raise unless missing_from(name, error)
+
+        raise ConfigurationError, "#{SETTING} names #{name.inspect}, which is not a constant"
+      end
+
+      def missing_from(name, error)
+        return false if error.name.nil?
+
+        receiver = begin
+          error.receiver
+        rescue ArgumentError
+          return false # raised by hand, with no namespace it was looked up in
+        end
+
+        segments = name.delete_prefix("::").split("::")
+        segments.each_index.any? do |index|
+          segments[index] == error.name.to_s && namespace(segments.first(index)).equal?(receiver)
+        end
+      end
+
+      def namespace(segments)
+        return Object if segments.empty?
+
+        ActiveSupport::Inflector.constantize(segments.join("::"))
+      rescue NameError
+        nil
+      end
+    end
+  end
+end

data/lib/event_rail/internal/stamping.rb

@@ -3,28 +3,34 @@ require "securerandom"
 module EventRail
   module Internal
     # Turns a proposal into a stamped fact: resolves source, selects logical identity,
-    # derives a retry-stable ID, fixes occurrence time, and installs lineage. Fanout
+    # derives its ID, fixes occurrence time, and installs lineage. Fanout
     # is a separate concern layered on top of this.
     module Stamping
       module_function
 
-      Prepared = Struct.new(:event, :execution, :logical_key, :relayed, keyword_init: true) do
+      # `previous` is the record this publication found for its fact, nil for a first attempt, so
+      # a caller that fails before delivering anything can put it back (`abandon!`).
+      Prepared = Struct.new(:event, :execution, :logical_key, :relayed, :previous, keyword_init: true) do
         def relayed?
           relayed
         end
       end
 
-      def prepare(event, key: nil)
+      def prepare(event, identity: nil, source: nil)
         unless event.is_a?(Event)
           raise InvalidEvent, "#{event.inspect} is not an EventRail::Event"
         end
+        Metadata.validate_source!(source) unless source.nil?
 
-        return relay(event, key: key) if event.stamped?
+        return relay(event, identity: identity, source: source) if event.stamped?
+
+        validate_identity!(event, identity)
+        source = (source || event.class.default_source)&.dup&.freeze
+        raise InvalidMetadata, "source is required to publish #{event.class}" unless source
 
-        validate_key!(key)
         execution = Execution.current
-        logical_identity = resolve_logical_identity(event, key)
-        logical_key = [ event.event_type, event.version, Identity.encode_component(logical_identity) ].freeze
+        derived_id = derive_id(event, execution, source, declared_identity(event, identity))
+        logical_key = record_key(source, event, derived_id)
 
         recorded = execution&.derives_identity? ? execution.record(logical_key) : nil
         if recorded&.succeeded?
@@ -36,8 +42,7 @@ module EventRail
         extensions = Extensions.merge!(Current.extensions, event.extensions, error: InvalidEvent)
         detect_retry_mismatch!(event, recorded, extensions) if recorded
 
-        source = event.class.default_source
-        event_id = recorded&.event&.id || derive_id(event, execution, source, logical_identity)
+        event_id = recorded&.event&.id || derived_id
         occurred_at = event.occurred_at || recorded&.event&.occurred_at || default_occurred_at(execution)
 
         stamped = event.send(
@@ -52,7 +57,7 @@ module EventRail
 
         execution.record!(logical_key, event: stamped, succeeded: false) if execution&.derives_identity?
 
-        Prepared.new(event: stamped, execution: execution, logical_key: logical_key, relayed: false)
+        Prepared.new(event: stamped, execution: execution, logical_key: logical_key, relayed: false, previous: recorded)
       end
 
       def succeeded!(prepared)
@@ -62,20 +67,38 @@ module EventRail
         execution.record!(prepared.logical_key, event: prepared.event, succeeded: true)
       end
 
-      # A relayed fact belongs to its origin. Its ID, source, occurrence time,
-      # correlation, and extensions are preserved, and the relaying application's own
-      # context extensions are deliberately not merged in: local baggage is not part of
-      # somebody else's event. Only a missing causation is filled, because the local
-      # message genuinely is what caused this relay.
-      def relay(event, key:)
-        unless key.nil?
+      # Undoes `prepare` for a publication that failed before handing anything over, restoring
+      # what the execution recorded before it: nothing for a first attempt, the earlier failed
+      # attempt otherwise. Without this a failure that delivered nothing would still turn the
+      # next publication of the fact into a retry, bound to a payload nobody received.
+      def abandon!(prepared)
+        execution = prepared.execution
+        return unless execution&.derives_identity?
+
+        execution.restore!(prepared.logical_key, prepared.previous)
+      end
+
+      # A relayed fact belongs to its origin. Its ID, source, occurrence time, lineage
+      # -- an absent causation included -- and extensions are preserved, and the relaying
+      # application's own context is deliberately not merged in: local baggage is not
+      # part of somebody else's event. Two producers may use the same ID, so the source is
+      # part of what makes a relay a repetition, and a relay retried with a different
+      # payload is refused exactly as a local publication is.
+      def relay(event, identity:, source:)
+        unless identity.nil?
           raise PublicationError,
             "#{event.event_type.inspect} already carries the event ID #{event.id.inspect}, so a publication " \
-            "key cannot apply to it"
+            "identity cannot apply to it"
+        end
+        if source && source != event.source
+          raise InvalidMetadata,
+            "#{event.event_type.inspect} #{event.id.inspect} already comes from #{event.source.inspect}; " \
+            "publishing it as #{source.inspect} would re-attribute somebody else's fact"
         end
 
         execution = Execution.current
-        logical_key = [ event.event_type, event.version, Identity.encode_component(event.id) ].freeze
+        logical_key = record_key(event.source, event, event.id)
+        recorded = nil
 
         if execution&.derives_identity?
           recorded = execution.record(logical_key)
@@ -84,71 +107,71 @@ module EventRail
               event_type: event.event_type, version: event.version, event_id: event.id
             )
           end
+          detect_retry_mismatch!(event, recorded, event.extensions) if recorded
+          execution.record!(logical_key, event: event, succeeded: false)
         end
 
-        relayed = if event.causation_id.nil? && Current.message_id
-          event.send(
-            :__stamp__,
-            id: event.id,
-            source: event.source,
-            occurred_at: event.occurred_at,
-            correlation_id: event.correlation_id,
-            causation_id: Current.message_id,
-            extensions: event.extensions
-          )
-        else
-          event
-        end
-
-        execution.record!(logical_key, event: relayed, succeeded: false) if execution&.derives_identity?
-
-        Prepared.new(event: relayed, execution: execution, logical_key: logical_key, relayed: true)
+        Prepared.new(event: event, execution: execution, logical_key: logical_key, relayed: true, previous: recorded)
       end
       private_class_method :relay
 
-      # 1. An explicit event ID wins, which is the relay path above.
-      # 2. An explicit call-site key.
-      # 3. The event class's declared identity attributes.
-      # 4. A singleton marker, for the first publication of that type in an execution.
-      def resolve_logical_identity(event, key)
-        return key if key
+      # One record per published event, whether it was stamped here or arrives stamped:
+      # so publishing the stamped result of a failed local publication is a retry of it,
+      # and publishing it again after success is a duplicate. Frozen binary copies, so a
+      # caller mutating the string it passed cannot move a record, and so a relayed ID is
+      # compared as the opaque bytes it is, whatever they hold.
+      def record_key(source, event, id)
+        [ source.b.freeze, event.event_type, event.version, id.b.freeze ].freeze
+      end
+      private_class_method :record_key
 
-        declared = event.class.identity_by
-        return Identity::SINGLETON if declared.empty?
+      # The fact an event declares itself to be, as a list: an explicit publication
+      # identity, or the class's declared identity attributes in declaration order. Nil
+      # when it declares none. An explicit identity and a single declared attribute with
+      # the same value name the same fact.
+      def declared_identity(event, identity)
+        return [ identity ] if identity
 
-        declared.map { |name| event.public_send(name) }
+        declared = event.class.identity_by
+        declared.empty? ? nil : declared.map { |name| event.public_send(name) }
       end
-      private_class_method :resolve_logical_identity
+      private_class_method :declared_identity
 
-      # A key spelled as an integer at one call site and as its decimal string at
-      # another would derive two identities for one fact, and nothing would report it.
-      def validate_key!(key)
-        return if key.nil?
+      # A publication identity names a fact across every execution, so it is a string --
+      # an integer at one call site and its decimal spelling at another would be two
+      # facts -- and it cannot contradict an identity the class already declares.
+      def validate_identity!(event, identity)
+        return if identity.nil?
 
-        unless key.is_a?(String) && !key.empty? && key.valid_encoding?
-          raise PublicationError, "publication key must be a non-empty string; got #{key.inspect}"
+        unless event.class.identity_by.empty?
+          raise PublicationError,
+            "#{event.class} declares #{event.class.identity_by.join(", ")} as its identity, so a publication " \
+            "identity cannot apply to it"
+        end
+        unless identity.is_a?(String) && !identity.empty? && identity.valid_encoding?
+          raise PublicationError, "publication identity must be a non-empty string; got #{identity.inspect}"
         end
-        if key.bytesize > Limits::MAX_IDENTIFIER_BYTES
-          raise PublicationError, "publication key exceeds #{Limits::MAX_IDENTIFIER_BYTES} bytes"
+        if identity.bytesize > Limits::MAX_IDENTIFIER_BYTES
+          raise PublicationError, "publication identity exceeds #{Limits::MAX_IDENTIFIER_BYTES} bytes"
         end
       end
-      private_class_method :validate_key!
-
-      def derive_id(event, execution, source, logical_identity)
-        return SecureRandom.uuid.freeze unless execution&.derives_identity?
-
-        unless source
-          raise InvalidMetadata, "source is required to publish #{event.class}"
+      private_class_method :validate_identity!
+
+      # A declared fact's ID depends on nothing but the fact. Without one, an ID derived
+      # from the execution is stable across its retries and redeliveries; outside any
+      # execution there is nothing stable to derive from, and the ID is random, in time
+      # order so a downstream log indexes it well.
+      def derive_id(event, execution, source, declared)
+        if declared
+          Identity.fact(source: source, event_type: event.event_type, identity: declared).freeze
+        elsif execution&.derives_identity?
+          Identity.execution(
+            source: source, job_class: execution.job_class, scope: execution.scope,
+            event_type: event.event_type, version: event.version
+          ).freeze
+        else
+          SecureRandom.uuid_v7.freeze
         end
-
-        Identity.derive(
-          source: source,
-          job_class: execution.job_class,
-          scope: execution.scope,
-          event_type: event.event_type,
-          version: event.version,
-          logical_identity: logical_identity
-        ).freeze
       end
       private_class_method :derive_id
 

data/lib/event_rail/job_context.rb

@@ -106,8 +106,11 @@ module EventRail
           entry["extensions"], error: InvalidContext
         )
 
+        # The scope an undeclared follow-up's ID derives from. A subscriber's is the event
+        # it handles, by source as well as ID, since two producers may use one ID; its
+        # logical message and causation stay the event's ID.
         execution = Internal::Execution.new(
-          job_class: self.class.name, scope: message_id, started_at: started_at
+          job_class: self.class.name, scope: event ? [ event.source, event.id ] : message_id, started_at: started_at
         )
 
         Internal::Context.establish(

data/lib/event_rail/publish.rb

@@ -7,6 +7,9 @@ module EventRail
     #
     #   publication = EventRail.publish(Orders::OrderPlaced.new(order_id: order.id))
     #
+    # `identity:` names the fact for an event whose class declares no `identity_by`;
+    # `source:` publishes a locally built event on behalf of another producer.
+    #
     # Individual enqueue calls, not `perform_all_later`. Bulk enqueue skips each job's
     # own `enqueue` callbacks on several adapters, and those callbacks are exactly where
     # an application puts uniqueness, concurrency, and feature-flag decisions that this
@@ -15,10 +18,12 @@ module EventRail
     # Delivery is at-least-once. Jobs already accepted are not rolled back when a later
     # subscriber's enqueue fails, and the retry repeats complete fanout under the same
     # event ID, so a subscriber may see the same event more than once.
-    def publish(event, key: nil)
+    def publish(event, identity: nil, source: nil, **unknown)
+      reject_unknown_keywords!(:publish, unknown)
+
       Internal::Transaction.check!
 
-      prepared = Internal::Stamping.prepare(event, key: key)
+      prepared = Internal::Stamping.prepare(event, identity: identity, source: source)
       stamped = prepared.event
       subscribers = Internal::Registry.subscribers_for(stamped.class)
 
@@ -45,6 +50,15 @@ module EventRail
     end
 
     private
+      def reject_unknown_keywords!(verb, unknown)
+        if unknown.key?(:key)
+          raise ArgumentError,
+            "#{verb}'s key: is now identity:, and it names a fact across every job rather than within one; " \
+            "check the value names one occurrence per source and event type before renaming it"
+        end
+        raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.keys.map(&:inspect).join(", ")}" if unknown.any?
+      end
+
       # Three outcomes, not two. Active Job returns false both when an adapter reports
       # failure and when an enqueue callback aborts, so the return value alone cannot
       # tell a fault from a decision. The job instance can, through `enqueue_error`, and

data/lib/event_rail/railtie.rb

@@ -12,6 +12,12 @@ module EventRail
     config.event_rail = ActiveSupport::OrderedOptions.new
     config.event_rail.roots = Internal::Registry::DEFAULT_ROOTS.dup
 
+    # What `EventRail.stage` hands an event's subscriber jobs to: the name of a constant,
+    # resolved on every staging so a reloaded class is always the current one, or an object
+    # for a stager that is never reloaded. Either responds to `stage(jobs)`. Assigned
+    # explicitly, so the option exists before an application sets it.
+    config.event_rail.stager = nil
+
     config.to_prepare do
       # Unqualified, so lexical lookup reaches the private Internal namespace that a
       # qualified EventRail::Internal reference would be refused.

data/lib/event_rail/stage.rb

@@ -0,0 +1,79 @@
+require "active_support/notifications"
+
+module EventRail
+  class << self
+    # Stages an event: stamps it exactly as `publish` does, builds one job per declared
+    # subscriber without enqueuing any, and hands them all to the application's stager in one
+    # call, inside the caller's database transaction.
+    #
+    #   Order.transaction do
+    #     order.update!(state: "shipped")
+    #     EventRail.stage(Orders::OrderShipped.new(order_id: order.id))
+    #   end
+    #
+    # The stager (`config.event_rail.stager`) persists the jobs with that transaction, all or
+    # nothing, or raises, and hands them to the queue once it commits. So the intent to
+    # deliver commits or rolls back with the state change it reports. Delivery itself is the
+    # stager's: its hand-over, its relay, the queue, and each subscriber's own enqueue
+    # callbacks, which run when a job is enqueued rather than here.
+    #
+    # Unlike `publish`, staging inside an open transaction is the point, so there is no
+    # transaction check. Whether the right transaction is open is the stager's to judge: only
+    # it knows which database it writes to.
+    def stage(event, identity: nil, source: nil, **unknown)
+      reject_unknown_keywords!(:stage, unknown)
+
+      # Every check that can fail on configuration or readiness runs before stamping, which
+      # records the fact in the current execution: a failure here must not leave a record that
+      # makes the next staging in the same attempt look like a retry. Readiness before the
+      # stager, so staging from an initializer says "not ready" rather than failing to find a
+      # class the autoloader cannot load yet.
+      configured = Internal::Stager.configured
+      snapshot = Internal::Registry.snapshot
+      stager = Internal::Stager.resolve(configured)
+
+      prepared = Internal::Stamping.prepare(event, identity: identity, source: source)
+      stamped = prepared.event
+      handed_over = false
+
+      begin
+        jobs = snapshot.subscribers_for(stamped.class).map { |job_class| staged_job(job_class, stamped) }.freeze
+
+        ActiveSupport::Notifications.instrument("stage.event_rail", Internal::Notifications.payload_for(stamped)) do |payload|
+          payload[:subscriber_count] = jobs.length
+          handed_over = true
+
+          # Called even with no jobs, so the stager's own transaction check applies whether or
+          # not the event has subscribers yet: otherwise adding the first one would make a
+          # previously silent call site start raising. A copy, so the stager may sort or trim
+          # its argument without touching what the result reports.
+          stager.stage(jobs.dup)
+        end
+      ensure
+        # A failure before the stager was called -- a subscriber that cannot be built, a
+        # notification handler failing as the block starts -- handed nothing over, so it must
+        # not leave the fact recorded: the next staging in this attempt is a first staging, not
+        # a retry bound to a payload no stager saw. From the stager on, a failure leaves the
+        # fact unfinished, and staging it again is a retry.
+        Internal::Stamping.abandon!(prepared) unless handed_over
+      end
+
+      # After the notification block, as for `publish`.
+      Internal::Stamping.succeeded!(prepared)
+
+      StagedPublication.new(event: stamped, staged_jobs: jobs)
+    end
+
+    private
+      # The job `perform_later` would have built, without the enqueue. Its context entry is
+      # built now, while the staging context is current, so the stager may serialize the job
+      # whenever and wherever it likes and still write what enqueuing it here would have
+      # written. Through the entry alone, not `serialize`: serializing would resolve and
+      # memoize the job's queue and priority blocks inside the caller's context and run its
+      # argument serializers for nothing. Every subscriber includes JobContext; preparation
+      # refuses one that does not.
+      def staged_job(job_class, event)
+        job_class.new(event).tap { |job| job.send(:__event_rail_entry__) }
+      end
+  end
+end

data/lib/event_rail/staged_publication.rb

@@ -0,0 +1,34 @@
+module EventRail
+  # What `EventRail.stage` returns: the stamped fact, and the subscriber jobs handed to the
+  # stager in place of being enqueued.
+  #
+  # Not a `Publication`. Accepted and skipped are outcomes of an enqueue, and staging performs
+  # none: whether each job reaches the queue, and whether a subscriber's own enqueue callback
+  # declines it, is decided later, when the stager hands it over. The jobs are here so a
+  # caller can match their IDs with what its stager wrote.
+  class StagedPublication
+    attr_reader :event, :staged_jobs
+
+    def initialize(event:, staged_jobs:)
+      @event = event
+      @staged_jobs = staged_jobs.dup.freeze
+      freeze
+    end
+
+    def staged_subscribers
+      staged_jobs.map(&:class)
+    end
+
+    def subscriber_count
+      staged_jobs.length
+    end
+
+    def id
+      event.id
+    end
+
+    def inspect
+      "#<EventRail::StagedPublication event=#{event.inspect} staged=#{subscriber_count}>"
+    end
+  end
+end

data/lib/event_rail/version.rb

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