event_rail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e59345edd1e6e7570345e9b68df5be4b565e5705051d35f854076a64e8fc08b8
+  data.tar.gz: d1391a4e11a36c9a81df720b6cd1376e4ddc79a126fab0fa8988db435a4823b4
+SHA512:
+  metadata.gz: a1bc401719f38d3f8fa654c1aba1df05451aaed81f813c7af74bb6c865ce90f35ccf48d579ec982627d973cd9f705e076b546303fd4b9759d5107dd5d99b9025
+  data.tar.gz: 6200d549898556da58c5d09ebe252373a10d73e4876494850cba5ae6f5603c2d2175b2744801eb02ab8ab57cd8ac9a7c65b7e2c9c34e63fc1906e872636bb8fa

data/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to EventRail are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+While the version is below 1.0 the public API may change in a minor release.
+
+This file tracks the **gem** version only. An event's own `version` is a separate
+integer contract declared per event class, and the queue representation carries its own
+private format version; neither is derived from the gem version and neither appears
+here unless a release changes how they behave.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-15
+
+### Added
+
+- `EventRail::Event` and `EventRail::Data`: immutable, recursively frozen Active Model
+  value objects with strict casting that refuses to discard information, an `attributes`
+  view of cast values, and a `data` projection that is the single portable written form.
+- `EventRail.publish`, returning a frozen `EventRail::Publication` carrying the stamped
+  event and the accepted and skipped subscribers.
+- `subscribes_to`, discovering subscribers from the conventional `app/events` and
+  `app/jobs` roots of the host application and every engine during Rails preparation,
+  and validating each one at boot.
+- Retry-stable event identity derived as a UUIDv5 over source, executing job class,
+  execution scope, event type, version, and logical publication identity, with an
+  explicit `key:` and a declarative `identity_by` for selecting that identity.
+- `EventRail::JobContext`, an opt-in Active Job concern propagating logical context
+  through one reserved key in the job's serialized data.
+- `EventRail::Current` and `EventRail.with_context` for establishing and reading
+  message, correlation, and causation identifiers, origin time, and string-keyed
+  extensions.
+- `EventRail::Envelope` and `EventRail::Contract` for crossing a network boundary, with
+  the codec and the inbound allowlist owned by the application.
+- `EventRail::PortableType`, an opt-in contract for custom attribute types whose
+  `portable_examples` are round-tripped through JSON when the attribute is declared.
+- Four `ActiveSupport::Notifications` events -- `publish.event_rail`,
+  `enqueue_subscriber.event_rail`, `deserialize.event_rail`, and
+  `perform_subscriber.event_rail` -- carrying contract, identity, and lineage only.
+- 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
+[0.1.0]: https://github.com/alexdmtv/event-rail/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# Contributing
+
+EventRail is under initial development. Please open an issue before proposing a substantial API change.
+
+Run `bin/test` and `bin/rubocop` before submitting a change.
+
+To run the suite against a specific Rails version, generate the per-Rails gemfiles first
+-- they are derived from the root `Gemfile` and are not committed:
+
+```sh
+bundle exec appraisal generate
+bundle exec appraisal install
+BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle exec rake test
+```

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Alex Dmitriev
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,364 @@
+# EventRail
+
+[![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.
+
+EventRail is not ready for production use yet. The public API is still being implemented and validated.
+
+## Requirements
+
+- Ruby 3.3 or newer
+- Rails 7.2, 8.0, or 8.1
+
+EventRail depends on Active Support, Active Model, Active Job, Railties, and Zeitwerk. It does not require Active Record.
+
+## Installation
+
+```ruby
+# doc:illustrative
+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.
+
+## Job integration
+
+One explicit inclusion, on each job base class that should carry logical context:
+
+```ruby
+class ApplicationJob < ActiveJob::Base
+  include EventRail::JobContext
+end
+```
+
+That is the entire integration. EventRail does not prepend `ActiveJob::Base` globally, because changing serialization for jobs whose owners never asked for it is surprising, and it does not edit `ApplicationJob` from a generator, because applications may have several job bases or a customized one. Ordinary jobs that do not opt in are untouched.
+
+## Events and nested data
+
+Events use Active Model types and validations. Nested objects can be modeled as immutable `EventRail::Data` values, including arrays of typed objects:
+
+```ruby
+module Docs
+  class LineItem < EventRail::Data
+    attribute :product_id, :string
+    attribute :quantity, :integer
+
+    validates :product_id, presence: true
+    validates :quantity, numericality: { greater_than: 0 }
+  end
+
+  class OrderPlaced < EventRail::Event
+    event_type "docs.order_placed"
+    version 1
+    default_source "acme.orders"
+    identity_by :order_id
+
+    attribute :order_id, :string
+    attribute :total, :decimal
+    attribute :placed_at, :datetime
+    attribute :line_items, LineItem, array: true
+    attribute :properties
+
+    validates :order_id, presence: true
+  end
+end
+
+event = Docs::OrderPlaced.new(
+  order_id: "A-1001",
+  total: "49.90",
+  placed_at: "2026-09-01T10:30:00+02:00",
+  line_items: [ { product_id: "P-1", quantity: 2 } ],
+  properties: { "channel" => "web" },
+  extensions: { "tenant" => "north" }
+)
+
+event.order_id                  # => "A-1001"
+event.total                     # => BigDecimal("49.9")
+event.line_items.first.quantity # => 2
+```
+
+Two views of the same payload, for two different jobs:
+
+```ruby
+event.attributes # cast values of the declared types: BigDecimal, Time, LineItem
+event.data       # the portable projection: JSON primitives, arrays, string-keyed hashes
+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.
+
+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:
+
+```ruby
+module Docs
+  Weight = Struct.new(:grams)
+
+  class WeightType < ActiveModel::Type::Value
+    include EventRail::PortableType
+
+    def cast(value) = value.is_a?(Weight) || value.nil? ? value : Weight.new(Integer(value))
+    def serialize(value) = value&.grams
+    def deserialize(value) = value && Weight.new(value)
+    def portable_examples = [ Weight.new(0), Weight.new(2500) ]
+  end
+
+  class ParcelShipped < EventRail::Event
+    event_type "docs.parcel_shipped"
+    version 1
+    default_source "acme.shipping"
+    identity_by :parcel_id
+
+    attribute :parcel_id, :string
+    attribute :weight, WeightType.new
+  end
+end
+
+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.
+
+## Publishing
+
+```ruby
+module Docs
+  class OnOrderPlacedJob < ApplicationJob
+    subscribes_to OrderPlaced
+
+    def perform(event)
+      Rails.logger.info("charging #{event.order_id} idempotently on #{event.id}")
+    end
+  end
+end
+
+publication = EventRail.publish(
+  Docs::OrderPlaced.new(order_id: "A-1002", total: "10.00", placed_at: Time.now.utc.iso8601)
+)
+
+publication.event                # the stamped, immutable fact
+publication.accepted_subscribers # subscribers whose enqueue was accepted
+publication.skipped_subscribers  # subscribers whose own enqueue callback declined
+```
+
+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.
+
+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.
+
+### At-least-once delivery, and what that means for subscribers
+
+Fanout is individual `perform_later` calls, one per subscriber. Jobs already accepted are never rolled back when a later subscriber's enqueue fails, and the retry repeats complete fanout under the same event ID. A subscriber must therefore be idempotent, and `event.id` is the key to be idempotent on: it is stable across retries of the publishing execution and across redeliveries of a subscriber's own cause.
+
+No ordering is promised, between subscribers or between events.
+
+Retries, backoff, discarding, and dead-letter handling stay where they already are: each subscriber's own Active Job configuration and the configured queue adapter. EventRail adds no retry policy of its own and no failure queue.
+
+### Publishing inside a database transaction
+
+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.
+
+### Replay-safe publishers
+
+A publisher that applies a state transition and then publishes should make the transition idempotent and attempt publication unconditionally:
+
+```ruby
+module Docs
+  class PlaceOrderJob < ApplicationJob
+    def perform(order_id)
+      order = { id: order_id, placed: true } # stands in for an idempotent state transition
+      EventRail.publish(Docs::OrderPlaced.new(order_id: order[:id], total: "1.00", placed_at: Time.now.utc.iso8601))
+    end
+  end
+end
+```
+
+Guarding publication behind "did I already transition?" is the failure mode to avoid: a crash between the transition and the enqueue then leaves an event that is never published. Attempting publication every time is safe, because a second publication of the same logical fact in the same execution is rejected as a duplicate, and a retry after a failed fanout reuses the identity already stamped.
+
+## 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.
+
+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:
+
+```ruby
+EventRail.publish(
+  Docs::OrderPlaced.new(order_id: "A-1003", total: "5.00", placed_at: Time.now.utc.iso8601),
+  key: "adjustment-7"
+)
+```
+
+Changing `identity_by`, changing `default_source`, or renaming a subscriber class all change the identities that derive from them, so each is a breaking change. Outside a job execution, events receive random IDs.
+
+`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.
+
+## Logical context
+
+Application-owned ingress code establishes context; EventRail ships no HTTP middleware and no controller concern, and harvests nothing from headers, Rails current state, or tracing baggage.
+
+```ruby
+EventRail.with_context(message_id: "req-abc", extensions: { "tenant" => "north" }) do
+  EventRail.publish(Docs::OrderPlaced.new(order_id: "A-1004", total: "7.00", placed_at: Time.now.utc.iso8601))
+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.
+
+### Reading context
+
+A job that includes `EventRail::JobContext` runs with context already installed, and reads it from `EventRail::Current`:
+
+```ruby
+class ReconcileOrderJob < ApplicationJob
+  def perform
+    EventRail::Current.message_id     # this job's logical message
+    EventRail::Current.correlation_id # constant across the whole causal tree
+    EventRail::Current.causation_id   # what caused this job
+    EventRail::Current.originated_at  # when the flow started, a UTC Time
+    EventRail::Current.extensions     # frozen string-keyed baggage
+  end
+end
+```
+
+Those five readers are the whole surface. Outside a job they return `nil`, except `extensions`, which is always a frozen hash.
+
+A subscriber is the case where they are usually unnecessary. Its logical message is the event it is handling rather than the job delivering it, so `Current.message_id` **is** `event.id`, and correlation, causation, and extensions all come from the event that is already the method argument:
+
+```ruby
+class SendReceiptJob < ApplicationJob
+  subscribes_to Docs::OrderPlaced
+
+  def perform(event)
+    event.id             # == EventRail::Current.message_id
+    event.correlation_id # == EventRail::Current.correlation_id
+    event.extensions     # == EventRail::Current.extensions
+  end
+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.
+
+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.
+
+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.
+
+Under fiber isolation a fiber spawned by application code starts with no context at all, which is the isolation working as asked. Code that fans out over its own fibers and publishes from them should re-establish context inside each fiber rather than rely on inheriting it. A job running on a fiber-based worker needs none of that: its context arrives in the job's own serialized data, not from an ambient parent.
+
+OpenTelemetry is not required. When standard Active Job instrumentation is installed, its own carrier and ambient span continue to work; EventRail never copies trace context or baggage into durable event metadata.
+
+## Versioning events
+
+`event_type` and `version` form the durable, language-neutral contract, independent of Ruby class names. A compatible optional addition may keep the same version: an older worker preserves the unknown field as opaque data with no reader and includes it again on export. Removing, renaming, requiring, or retyping a field, changing its meaning, or changing identity requires a new version and a distinct class, and the old class stays registered while messages that reference it can still arrive.
+
+EventRail provides no upcasting and no schema registry.
+
+## Fixed safety limits
+
+| Value | Limit |
+| --- | ---: |
+| Event, correlation, causation, or boundary identifier | 512 bytes |
+| Source | 255 bytes |
+| Event type | 255 bytes |
+| Extension entries | 32 |
+| Extension key | 64 bytes |
+| Extension value | 1,024 bytes |
+| Total extension key and value bytes | 8,192 bytes |
+| Raw structure nesting depth | 32 |
+
+Extension keys and values must be strings. Framework metadata names, tracing names, and the `eventrail.` prefix are reserved. There is no universal payload byte limit, because adapters and transports impose different ones.
+
+## Testing
+
+Application tests use Active Job's own helpers and nothing from EventRail:
+
+```ruby
+# 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 ])
+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.
+
+## Notifications
+
+Four `ActiveSupport::Notifications` events, all in block form so Rails' own exception keys report failures:
+
+| Name | Additional payload |
+| --- | --- |
+| `publish.event_rail` | `subscriber_count`, `accepted`, `skipped` |
+| `enqueue_subscriber.event_rail` | `job_class`, `outcome` (`accepted`, `skipped`, `failed`) |
+| `deserialize.event_rail` | `format_version` |
+| `perform_subscriber.event_rail` | `job_class` |
+
+Every payload carries `event_type`, `event_version`, `event_id`, `source`, `correlation_id`, and `causation_id`. None carries domain data or extensions. Handlers run synchronously under normal Rails semantics, so they should neither raise nor do slow work.
+
+## Crossing a network boundary
+
+`EventRail::Envelope` is the format-neutral boundary. It exposes contract, metadata, and the portable data projection through readers, and produces no bytes, no canonical hash, and no content type: those decisions belong to whoever owns the transport.
+
+```ruby
+# doc:illustrative
+envelope = EventRail::Envelope.of(publication.event)
+payload  = MyCloudEventsCodec.encode(envelope)   # the application owns every byte
+```
+
+Inbound, the application maps a contract to a class with its own allowlist and then reconstructs explicitly. A type name arriving over a network never names a Ruby constant, and the internal queue registry does not authorize external input:
+
+```ruby
+# doc:illustrative
+ACCEPTED = { [ "partner.invoice_issued", 1 ] => Billing::InvoiceIssued }.freeze
+
+event_class = ACCEPTED.fetch([ envelope.event_type, envelope.version ])
+EventRail.publish(envelope.to_event(event_class))
+```
+
+A relayed event keeps its origin's ID, source, occurrence time, correlation, and extensions; the relaying application's own context extensions are not merged into it, and only a missing causation is filled.
+
+Loop prevention is application policy: an export policy that refuses to export an event whose source is not the local application stops a relayed event from bouncing back to the system it came from. EventRail has no concept of internal versus external, direction, topic, or transport marker.
+
+Acknowledge a consumed message only after publication succeeds, and leave retry and dead-lettering to the transport.
+
+## Upgrading and rolling back
+
+The private Active Job representation and the job context entry each carry their own version, independent of any event's schema version. Both evolve as staged, read-before-write deployments:
+
+1. Deploy a release that reads the old and the new form everywhere, while still writing the old one.
+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.
+
+## Development
+
+Run the core tests and linter with:
+
+```sh
+bin/test
+bin/rubocop
+```
+
+The Appraisal gemfiles cover Rails 7.2, 8.0, and 8.1. The CI matrix covers Ruby 3.3, 3.4, and 4.0.
+
+## Contributing and security
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the local workflow and [SECURITY.md](SECURITY.md) for reporting security issues.
+
+## License
+
+EventRail is available under the [MIT License](MIT-LICENSE).

data/SECURITY.md

@@ -0,0 +1,3 @@
+# Security Policy
+
+EventRail has not published a stable release yet. Please report suspected vulnerabilities privately through GitHub's security advisory interface rather than a public issue.

data/lib/event_rail/contract.rb

@@ -0,0 +1,44 @@
+module EventRail
+  # The durable identity of an event schema: a stable type and an integer compatibility
+  # version, independent of any Ruby class name. Constants may move; this does not.
+  class Contract
+    attr_reader :event_type, :version
+
+    def self.of(event_class)
+      new(event_type: event_class.event_type, version: event_class.version)
+    end
+
+    def initialize(event_type:, version:)
+      unless event_type.is_a?(String) && !event_type.empty? && event_type.valid_encoding?
+        raise InvalidContract, "event_type must be a non-empty valid string; got #{event_type.inspect}"
+      end
+      if event_type.bytesize > Limits::MAX_EVENT_TYPE_BYTES
+        raise InvalidContract, "event_type exceeds #{Limits::MAX_EVENT_TYPE_BYTES} bytes"
+      end
+      unless version.is_a?(Integer) && version.positive?
+        raise InvalidContract, "version must be a positive integer; got #{version.inspect}"
+      end
+
+      @event_type = event_type.dup.freeze
+      @version = version
+      freeze
+    end
+
+    def ==(other)
+      other.instance_of?(self.class) && other.event_type == event_type && other.version == version
+    end
+    alias_method :eql?, :==
+
+    def hash
+      [ self.class, event_type, version ].hash
+    end
+
+    def to_s
+      "#{event_type}/#{version}"
+    end
+
+    def inspect
+      "#<EventRail::Contract #{self}>"
+    end
+  end
+end

data/lib/event_rail/current.rb

@@ -0,0 +1,95 @@
+require "active_support/current_attributes"
+require "securerandom"
+
+module EventRail
+  # Execution-scoped lineage, and nothing else.
+  #
+  # Publication state is deliberately not here: the Rails executor resets current
+  # attributes around a job's execution but not around a job performed inside
+  # another, so a shared map would behave differently in test than in production.
+  # `Internal::Execution` owns that instead.
+  #
+  # `ActiveSupport::IsolatedExecutionState` defaults to thread isolation, so a host
+  # running fiber-per-request must set `config.active_support.isolation_level = :fiber`
+  # for lineage to be isolated per request. EventRail documents that requirement
+  # rather than claiming an isolation it cannot provide.
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :message_id, :correlation_id, :causation_id, :originated_at, :extensions
+
+    def extensions
+      super || Internal::Extensions::EMPTY
+    end
+  end
+
+  class << self
+    # Establishes logical context for an application-owned ingress boundary: a
+    # middleware, a controller hook, a consumer draining a queue, a CLI entry point,
+    # a scheduler. EventRail ships no HTTP middleware and harvests nothing from
+    # headers, Rails current state, or tracing baggage -- what propagates is what the
+    # application installed here.
+    #
+    # A nested scope inherits lineage and may add extensions. It may not replace an
+    # identifier, the origin time, or an extension value with a different one: that
+    # would rewrite the lineage of a flow already in progress rather than describe it.
+    def with_context(message_id: nil, correlation_id: nil, originated_at: nil, extensions: {})
+      inherited = {
+        message_id: Current.message_id,
+        correlation_id: Current.correlation_id,
+        causation_id: Current.causation_id,
+        originated_at: Current.originated_at,
+        extensions: Current.extensions
+      }
+
+      resolved_message_id = resolve_context_identifier(:message_id, message_id, inherited[:message_id]) ||
+        SecureRandom.uuid.freeze
+      resolved_correlation_id = resolve_context_identifier(:correlation_id, correlation_id, inherited[:correlation_id]) ||
+        resolved_message_id
+      resolved_originated_at = resolve_context_time(originated_at, inherited[:originated_at])
+      resolved_extensions = Internal::Extensions.merge!(
+        inherited[:extensions], extensions, error: InvalidContext
+      )
+
+      execution = Internal::Execution.new(scope: resolved_message_id, started_at: resolved_originated_at)
+
+      # A nested scope keeps its parent's causation: the message that caused this flow
+      # does not change because the application opened an inner block.
+      Internal::Context.establish(
+        message_id: resolved_message_id,
+        correlation_id: resolved_correlation_id,
+        causation_id: inherited[:causation_id],
+        originated_at: resolved_originated_at,
+        extensions: resolved_extensions
+      ) do
+        Internal::Execution.wrap(execution) { yield }
+      end
+    end
+
+    private
+      def resolve_context_identifier(name, supplied, inherited)
+        return inherited if supplied.nil?
+
+        Metadata.validate_identifier!(supplied, field: name.to_s)
+        frozen = supplied.dup.freeze
+        if inherited && inherited != frozen
+          raise InvalidContext,
+            "#{name} is already #{inherited.inspect} in this context and cannot be replaced with #{frozen.inspect}"
+        end
+
+        frozen
+      rescue InvalidMetadata => error
+        raise InvalidContext, error.message
+      end
+
+      def resolve_context_time(supplied, inherited)
+        return inherited || Internal::Timestamp.normalize(Time.now.utc, field: "originated_at", error: InvalidContext) if supplied.nil?
+
+        normalized = Internal::Timestamp.normalize(supplied, field: "originated_at", error: InvalidContext)
+        if inherited && inherited != normalized
+          raise InvalidContext,
+            "originated_at is already #{inherited.iso8601(6)} in this context and cannot be replaced"
+        end
+
+        normalized
+      end
+  end
+end

data/lib/event_rail/data.rb

@@ -0,0 +1,4 @@
+module EventRail
+  class Data < Internal::AttributeRecord
+  end
+end