tcb 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77ac348140af6f18f4416932f320bc474f3131c14903c592cf83f352a02e1297
-  data.tar.gz: 4f5462a8425eb01612a3e6ffb3b89c8c848504db97d8a2fb913c7961abbc67b2
+  metadata.gz: e9fdc75ccfefebb2cb421260d89276f946b42f3d0f9e7ed90438b1d2cce1da8c
+  data.tar.gz: d48eee8151fc7ea5b2339f8949fc68bd6f04b61062007aff2f335e2f2f1b367d
 SHA512:
-  metadata.gz: 2eed8f7a67fcef1a356262a854b707964a2d5eb15c910a5a508368fc602e7f0892742e0ff24035a26f7542ae9de14740288db7fe07655d7e13e25a444db8799e
-  data.tar.gz: d41fd603ec8b6cc729396ea7ac5b9b692bd983b080f59e8f1df23faab88976563bd460513ed0634d25fba6a3911f77e583e8508c0ce455997347ed25eef00e12
+  metadata.gz: 5b8d0a0de064464890a11e71649dbb587fa032cccfd6d57ebaebfe350303ad725519cf7c8b66e8ec48d9b6092d8082e8167daa9d81d3d1cdc632cb3c50f67107
+  data.tar.gz: cccbab25a067c195d236f8e83796099d4eae236061021d3fe9a7547016a79b5a4f1bb22d525d9ce8cd506d5eb14be865c31e0417dbb1cc5ef9c8eb2ed52384d3

data/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-05-22
+
+### Added
+
+- `TCB.reactions_for(event_class)` — returns all handler classes registered for an event across all domain modules; returns `[]` if none
+- `ensure_reaction` DSL — declares guaranteed delivery handlers via outbox pattern; used as `on EventClass, ensure_reaction(Handler)`
+- `TCB::OutboxEntry` — value object carrying outbox entry state: `id`, `event_id`, `stream_id`, `version`, `handler_class`, `status`, `locked_at`, `delivered_at`, `error`, `created_at`
+- `TCB::OutboxStore::InMemory` — thread-safe in-memory outbox store for tests
+- `TCB::OutboxStore::ActiveRecord` — ActiveRecord persistence adapter for outbox entries; drop-in replacement for `OutboxStore::InMemory`
+- `TCB::OutboxRelay` — single polling cycle: recover stale locks → lock pending → fetch envelopes → invoke handler → mark delivered/failed
+- `Configuration#outbox_store_class` — declares which outbox store adapter to use (`OutboxStore::InMemory` or `OutboxStore::ActiveRecord`); store is instantiated per domain module during configuration
+- `Configuration#outbox_registrations` — collected outbox handler registrations across domain modules, each carrying a reference to its domain's store instance
+- `DomainContext#outbox_table_name` — derives per-domain outbox table name (`..._outbox` suffix)
+- Per-domain `OutboxRecord` AR model defined dynamically for domain modules with outbox registrations; analogous to `EventRecord`
+- Rails generator `tcb:outbox` — generates outbox migration and job scaffold per domain module
+- Outbox migration template — table with `id` (string UUID, primary key), `event_id`, `stream_id`, `version`, `handler_class`, `status`, `locked_at`, `delivered_at`, `error`, `created_at`; indexes on `:status`, `[:status, :locked_at]`, `[:stream_id, :version]`
+- Outbox job template — `ApplicationJob` wrapper around `OutboxRelay` for SolidQueue/Sidekiq integration
+
+## [0.6.2] - 2026-05-07
+
+### Fixed
+
+- `tcb:install` generator — `TCB.domain_modules=` moved into `Rails.application.config.to_prepare` block; bare initializer runs before Zeitwerk loads application constants, causing `NameError` when domain modules reference Rails classes such as `ApplicationJob` or `ApplicationRecord`
+
 ## [0.6.1] - 2026-05-06
 
 ### Fixed

data/README.md

@@ -1,10 +1,59 @@
 # TCB
 
-A lightweight, thread-safe event and command runtime for Domain-Driven Design on Rails.
+Is your codebase using every form of coupling except the one architects actually recommend?
+How much does a feature request cost you now?
+
+TCB gives each concern its own place, a clean domain language, and a full record
+of everything that happened, so you can understand and evolve your business logic
+with confidence.
+
+Imagine the following scenario. An order is placed. Stock gets reserved. The customer is notified.
+Now imagine each piece in its own domain, reacting independently, easy to test in isolation,
+simple to evolve as your business grows, and the full picture always visible.
+
+```ruby
+PlaceOrder = Data.define(:order_id, :customer)
+def Sales.place!(order_id:, customer:) = TCB.dispatch(PlaceOrder.new(order_id:, customer:))
+
+correlation_id = Sales.place!(order_id: 42, customer: "Alice")
+#   Sales             → OrderPlaced        persisted, published
+#     Warehouse       → StockReserved      reacts automatically, same correlation
+#       Notifications → CustomerNotified   reacts automatically, same correlation
 
-TCB gives Rails applications a clean domain language. Events, aggregates, and handlers are plain Ruby. No framework inheritance, no infrastructure details leaking into your domain.
+TCB.read_correlation(correlation_id).to_a # => all three events, across all three domains, in order
+```
+
+A lightweight, thread-safe event and command runtime for Domain-Driven Design on Rails.
+Events, aggregates, and handlers are plain Ruby. No framework inheritance, no infrastructure
+details leaking into your domain.
+
+Rails can change. Your domains should change only when your business demands it.
+Clean domain code pays compound interest. It's easier to reason about, easier to test,
+and easier for AI agents to work with. TCB keeps your domain that way.
+Rails takes care of the rest.
+
+
+## Contents
+
+- [Installation](#installation)
+- [Event Bus](#event-bus)
+- [TCB::HandlesEvents](#tcbhandlesevents)
+- [TCB::HandlesCommands](#tcbhandlescommands)
+- [Domain-Driven Design](#domain-driven-design)
+- [Guaranteed Delivery with the Outbox Pattern](#guaranteed-delivery-with-the-outbox-pattern)
+- [Configuration](#configuration)
+- [Reading Events](#reading-events)
+- [Correlation and Causation Tracking](#correlation-and-causation-tracking)
+- [Reading a Correlation Chain](#reading-a-correlation-chain)
+- [Inspecting Reactions](#inspecting-reactions)
+- [Event Store Adapters](#event-store-adapters)
+- [Generators](#generators)
+- [Error Handling](#error-handling)
+- [Graceful Shutdown](#graceful-shutdown)
+- [Testing](#testing)
+- [Why `Data.define`](#why-datadefine)
 
-TCB uses a command and event bus as an architectural coordination mechanism. Commands are decisions routed to exactly one handler. Events are facts broadcast to any number of reactions. The goal is to isolate side-effects, allow independent evolution of behaviors, and support an increasing number of business-significant events.
+---
 
 ## Installation
 
@@ -46,11 +95,11 @@ bus.publish(UserRegistered.new(id: 1, email: "alice@example.com"))
 
 ### Execution model
 
-TCB::EventBus uses a single background thread to process events. Publishing is non-blocking — the event is placed on a queue and control returns to the caller immediately. The dispatcher thread processes events in FIFO order. Handlers for a given event execute sequentially within the dispatcher thread.
+TCB::EventBus uses a single background thread to process events. Publishing is non-blocking. The event is placed on a queue and control returns to the caller immediately. The dispatcher thread processes events in FIFO order. Handlers for a given event execute sequentially within the dispatcher thread.
 
 This design favors determinism and simplicity: events are always processed in the order they were published, and handlers cannot race with each other.
 
-For tests and simple use cases, `sync: true` executes handlers in the caller thread immediately — no background thread, no queue:
+For tests and simple use cases, `sync: true` executes handlers in the caller thread immediately, no background thread, no queue:
 
 ```ruby
 bus = TCB::EventBus.new(sync: true)
@@ -77,7 +126,7 @@ The event queue is unbounded by default. If handlers are slower than the rate of
 TCB::EventBus.new(max_queue_size: 10_000)
 ```
 
-When the queue is full, `publish` blocks until space is available. The right value depends on your event volume and handler latency — measure before deciding.
+When the queue is full, `publish` blocks until space is available. The right value depends on your event volume and handler latency. Measure before deciding.
 
 ---
 
@@ -137,10 +186,10 @@ module Notifications
 end
 ```
 
-Event classes can come from anywhere. Cross-module reactions are the norm, not the exception. Each handler is isolated. Ine failure does not prevent others from executing.
+Event classes can come from anywhere. Cross-module reactions are the norm, not the exception. Each handler is isolated. One failure does not prevent others from executing.
 
 Domain modules are declared once at the top level, before infrastructure is configured.
-This is the only place TCB needs to know about your bounded contexts — all reactions,
+This is the only place TCB needs to know about your bounded contexts. All reactions,
 persistence rules, and handler mappings live inside each module itself.
 
 ```ruby
@@ -154,7 +203,7 @@ end
 
 `TCB.domain_modules=` wires up subscriptions and command routing from all modules.
 `TCB.configure` provides the infrastructure they run on. The two are intentionally
-separate — domain modules don't change between environments, infrastructure does.
+separate. Domain modules don't change between environments, infrastructure does.
 
 ---
 
@@ -229,32 +278,24 @@ The domain module is a boundary. Everything inside speaks the domain language. N
 module Sales
   include TCB::Domain
 
-  # Facade
   def self.place!(order_id:, customer:)
     TCB.dispatch(PlaceOrder.new(order_id: order_id, customer: customer))
   end
 
-  # Events
   OrderPlaced = Data.define(:order_id, :customer)
 
-  # Commands
   PlaceOrder = Data.define(:order_id, :customer) do
     def validate!
       raise ArgumentError, "customer required" if customer.nil?
     end
   end
 
-  # Persistence
   persist events(
     OrderPlaced,
     stream_id_from_event: :order_id
   )
 
-  # Commands
   handle PlaceOrder, with(PlaceOrderHandler)
-
-  # Reactions
-  on OrderPlaced, react_with(Warehouse::ReserveStock)
 end
 ```
 
@@ -366,11 +407,108 @@ end
 
 ---
 
+## Guaranteed Delivery with the Outbox Pattern
+
+`on Event, Handler` delivers reactions synchronously and best-effort. If the process crashes mid-dispatch, or a handler calls an external service that fails, the reaction is lost. For cross-domain reactions that must eventually succeed, like sending emails, enqueuing jobs, notifying external systems, TCB offers `ensure_reaction`.
+
+```ruby
+module Invoicing
+  include TCB::Domain
+
+  OrderPlaced = Data.define(:order_id)
+
+  persist events(OrderPlaced, stream_id_from_event: :order_id)
+
+  on OrderPlaced, ensure_reaction(SendInvoice, NotifyAccounting)
+end
+```
+
+`ensure_reaction` does not call your handlers inline. Instead, `TCB.record` writes outbox entries atomically alongside the event, in the same database transaction. A background job polls the outbox, invokes each handler, and marks the entry delivered. If the process crashes before the job runs, the entries remain pending and will be picked up on the next poll.
+
+> `ensure_reaction` requires the event to be persisted. `persist events(...)` must be declared in the same domain module.
+
+### Setup
+
+If your outbox handlers call Rails infrastructure — ActiveJob, mailers, or other application classes — place your full configuration in `config/initializers/tcb.rb`. This ensures Rails is fully loaded when handlers execute:
+
+```ruby
+# config/initializers/tcb.rb
+Rails.application.config.to_prepare do
+  TCB.reset!
+  TCB.domain_modules = [Sales, Warehouse, Notifications]
+
+  TCB.configure do |c|
+    case Rails.env
+    when "test"
+      c.event_bus          = TCB::EventBus.new(sync: true)
+      c.event_store        = TCB::EventStore::InMemory.new
+      c.outbox_store_class = TCB::OutboxStore::InMemory
+    when "development"
+      c.event_bus          = TCB::EventBus.new(handle_signals: false, shutdown_timeout: 10.0)
+      c.event_store        = TCB::EventStore::ActiveRecord.new
+      c.outbox_store_class = TCB::OutboxStore::ActiveRecord
+    when "production"
+      c.event_bus          = TCB::EventBus.new(handle_signals: true, shutdown_timeout: 30.0)
+      c.event_store        = TCB::EventStore::ActiveRecord.new
+      c.outbox_store_class = TCB::OutboxStore::ActiveRecord
+    end
+  end
+end
+```
+
+`OutboxStore::InMemory` is a drop-in replacement for tests. Entries live in memory and do not require a migration.
+
+### Generator
+
+Generate the outbox migration and job scaffold for a domain module:
+
+```CLI
+bin/rails generate tcb:outbox invoicing
+```
+
+This creates:
+
+- `db/migrate/..._create_invoicing_outbox.rb` — the outbox table
+- `app/jobs/invoicing_outbox_job.rb` — a job that runs one relay cycle
+
+```ruby
+class InvoicingOutboxJob < ApplicationJob
+  queue_as :default
+
+  def perform
+    TCB::OutboxRelay.new(
+      outbox_store: Invoicing::OutboxRecord,
+      event_store:  TCB.config.event_store,
+      lock_timeout: 300
+    ).run
+  end
+end
+```
+
+Schedule this job to run periodically. Each `perform` call runs one polling cycle: recover stale locks → lock pending entries → fetch events → invoke handlers → mark delivered or failed.
+
+
+With Solid Queue (Rails 8 default), add a recurring job to `config/recurring.yml`:
+
+```yaml
+invoicing_outbox:
+  class: InvoicingOutboxJob
+  schedule: every 30 seconds
+```
+
+Pick an interval based on your latency tolerance. Every 30 seconds is a reasonable starting point for most applications.
+
+### Failure handling
+
+If a handler raises, the entry is marked `failed` and the error message is stored. Other entries in the same cycle continue processing. Failed entries are not retried automatically. Retry is the responsibility of your job scheduler. Schedule the job to run periodically and retries happen naturally on the next cycle.
+
+---
+
 ## Configuration
 
 ### Domain modules
 
-Domain modules are the bounded contexts of your application. Declare them once, at the top level — before infrastructure is configured:
+Domain modules are the bounded contexts of your application. Declare them once, at the top level, before infrastructure is configured:
 
 ```ruby
 # config/initializers/tcb.rb
@@ -388,11 +526,12 @@ Infrastructure is environment-specific. Configure it in each environment file so
 Rails.application.config.to_prepare do
   TCB.reset!
   TCB.configure do |c|
-    c.event_bus   = TCB::EventBus.new(
-      handle_signals: false,   # Rails manages process signals in development
+    c.event_bus          = TCB::EventBus.new(
+      handle_signals: false,
       shutdown_timeout: 10.0
     )
-    c.event_store = TCB::EventStore::ActiveRecord.new
+    c.event_store        = TCB::EventStore::ActiveRecord.new
+    c.outbox_store_class = TCB::OutboxStore::ActiveRecord  # required if any domain uses ensure_reaction
   end
 end
 ```
@@ -404,11 +543,12 @@ end
 Rails.application.config.to_prepare do
   TCB.reset!(graceful_shutdown_time: 10.0)
   TCB.configure do |c|
-    c.event_bus   = TCB::EventBus.new(
+    c.event_bus          = TCB::EventBus.new(
       handle_signals: true,
       shutdown_timeout: 30.0
     )
-    c.event_store = TCB::EventStore::ActiveRecord.new
+    c.event_store        = TCB::EventStore::ActiveRecord.new
+    c.outbox_store_class = TCB::OutboxStore::ActiveRecord
   end
 end
 ```
@@ -419,13 +559,14 @@ end
 # config/environments/test.rb
 Rails.application.config.after_initialize do
   TCB.configure do |c|
-    c.event_bus   = TCB::EventBus.new(sync: true)
-    c.event_store = TCB::EventStore::InMemory.new
+    c.event_bus          = TCB::EventBus.new(sync: true)
+    c.event_store        = TCB::EventStore::InMemory.new
+    c.outbox_store_class = TCB::OutboxStore::InMemory  # in-memory, no migration needed
   end
 end
 ```
 
-`sync: true` executes handlers in the caller thread — no background thread, no polling. `after_initialize` runs once at boot. Between tests, call `TCB.reset!` to get a fresh bus and store.
+`sync: true` executes handlers in the caller thread. No background thread, no polling. `after_initialize` runs once at boot. Between tests, call `TCB.reset!` to get a fresh bus and store.
 
 Each domain module gets its own database table. Domains stay isolated at the persistence level:
 
@@ -437,6 +578,25 @@ Each domain module gets its own database table. Domains stay isolated at the per
 
 ---
 
+### Serialization
+
+TCB serializes events to YAML. `Symbol`, `Time`, `Date`, `BigDecimal`, and your `Data` events are permitted by default during deserialization.
+
+If your events carry attributes of other types — such as `ActiveSupport::TimeWithZone` when using `Time.zone.now` — declare them explicitly:
+
+```ruby
+TCB.configure do |c|
+  c.extra_serialization_classes = [
+    ActiveSupport::TimeWithZone,
+    ActiveSupport::TimeZone,
+  ]
+end
+```
+
+This is optional. Omit it if your event attributes use only plain Ruby types.
+
+---
+
 ## Reading Events
 
 Events are stored per aggregate stream. Query them by domain module and aggregate id. The result is always ordered by version. For large streams, `in_batches` uses keyset pagination and keeps memory usage flat.
@@ -483,7 +643,7 @@ envelope.causation_id   # UUID string, event_id of the triggering event; nil for
 
 ## Correlation and causation tracking
 
-Every `TCB.dispatch` generates a `correlation_id` and returns it to the caller. All events produced within that dispatch chain share the same `correlation_id`, regardless of how deep the reactive chain goes. `causation_id` identifies the direct cause — the `event_id` of the envelope that triggered the handler.
+Every `TCB.dispatch` generates a `correlation_id` and returns it to the caller. All events produced within that dispatch chain share the same `correlation_id`, regardless of how deep the reactive chain goes. `causation_id` identifies the direct cause, the `event_id` of the envelope that triggered the handler.
 
 ```
 Sales.place!(order_id: 42, customer: "Alice")
@@ -529,7 +689,23 @@ TCB.read_correlation("req-abc").between(1.hour.ago, Time.now).to_a
 
 Results are ordered by `occurred_at` across all domains. Each result is a `TCB::Envelope` with `correlation_id` and `causation_id` populated.
 
-`across:` defaults to all configured domain modules that have persistence registrations. Domains without persistence — like `Notifications` in the example above — are excluded automatically.
+`across:` defaults to all configured domain modules that have persistence registrations. Domains without persistence, like `Notifications` in the example above, are excluded automatically.
+
+---
+
+## Inspecting Reactions
+
+To see which handlers are registered for an event class across all domain modules:
+
+```ruby
+TCB.reactions_for(Sales::OrderPlaced)
+# => [Warehouse::ReserveStock]
+
+TCB.reactions_for(Warehouse::StockReserved)
+# => [Notifications::NotifyCustomer]
+```
+
+Returns an empty array if no reactions are registered. Useful for verifying topology at a glance or asserting reaction wiring in tests.
 
 ---
 
@@ -598,17 +774,21 @@ Generates:
 | `--skip-migration` | Skip migration (event_store only) |
 | `--no-comments` | Generate without inline guidance comments |
 
-After generating, add your module to config/initializers/tcb.rb. Domain modules don't change between environments — infrastructure does. Keeping them separate means your bounded contexts are declared once, while the bus and store are configured per environment:
+After generating, add your module to config/initializers/tcb.rb. Domain modules don't change between environments. Infrastructure does. Keeping them separate means your bounded contexts are declared once, while the bus and store are configured per environment:
 
 ```ruby
 # config/initializers/tcb.rb
-TCB.domain_modules = [
-  Sales,
-  Warehouse,
-  Notifications
-]
+Rails.application.config.to_prepare do
+  TCB.domain_modules = [
+    Sales,
+    Warehouse,
+    Notifications
+  ]
+end
 ```
 
+`to_prepare` runs after Zeitwerk loads all application constants. Use it instead of a bare initializer. Domain modules typically reference Rails classes (ApplicationJob, ApplicationRecord, etc.) that are not yet available at initializer time.
+
 ---
 
 ## Error Handling
@@ -645,7 +825,7 @@ bus.force_shutdown
 
 Configure TCB once at boot in `config/environments/test.rb` (see Configuration above). Between tests, call `TCB.reset!` to get a fresh event bus and a clean event store.
 
-`TCB.reset!` shuts down the current bus, clears the event store, and clears all subscriptions. The next test starts with a clean slate. Domain modules do not need to be re-declared — they are set once at the top level and persist across resets.
+`TCB.reset!` shuts down the current bus, clears the event store, and clears all subscriptions. The next test starts with a clean slate. Domain modules do not need to be re-declared. They are set once at the top level and persist across resets.
 
 ### Synchronous mode
 
@@ -661,12 +841,20 @@ Rails.application.config.after_initialize do
 end
 ```
 
+`after_initialize` runs once at boot. Tests do not reload Rails, so `to_prepare` is unnecessary. Between tests, TCB.reset! shuts down the current bus and clears the store, but also wipes the configuration. Restore it in your test teardown so every test starts with a clean, fully configured bus.
+
 ### Minitest
 
 ```ruby
 class OrdersTest < Minitest::Test
   include TCB::MinitestHelpers
-  def teardown = TCB.reset!
+  def teardown
+    TCB.reset!
+    TCB.configure do |c|
+      c.event_bus   = TCB::EventBus.new(sync: true)
+      c.event_store = TCB::EventStore::InMemory.new
+    end
+  end
 
   def test_placing_order_publishes_event
     assert_published(Orders::OrderPlaced) do
@@ -687,7 +875,7 @@ assert_published(Orders::OrderPlaced, within: 0.5) { Orders.place!(...) }
 
 #### poll_assert
 
-Only needed when using an async bus. With `TCB::EventBus.new(sync: true)`, handlers execute in the caller thread and results are available immediately — no polling required.
+Only needed when using an async bus. With `TCB::EventBus.new(sync: true)`, handlers execute in the caller thread and results are available immediately. No polling required.
 
 ```ruby
 poll_assert("reserve inventory called") { CALLED.include?(:reserve_inventory) }
@@ -699,7 +887,13 @@ poll_assert("payment processed", within: 2.0) { Payment.completed? }
 ```ruby
 # spec/support/tcb.rb
 RSpec.configure do |config|
-  config.after(:each) { TCB.reset! }
+  config.after(:each) do
+    TCB.reset!
+    TCB.configure do |c|
+      c.event_bus   = TCB::EventBus.new(sync: true)
+      c.event_store = TCB::EventStore::InMemory.new
+    end
+  end
 end
 ```
 

data/lib/generators/tcb/install/templates/tcb.rb.tt

@@ -2,19 +2,27 @@
 # Add your domain modules here after generating them:
 #   rails generate tcb:event_store orders place_order:order_id,customer
 #   rails generate tcb:domain notifications send_welcome_email:user_id,email
-TCB.domain_modules = [
-  # Orders,
-  # Notifications,
-]
-
-# Infrastructure — how events are transported and stored
-# Runs on every Rails reload in development
+#
+# to_prepare runs after Zeitwerk loads all application constants.
+# Domain modules typically reference Rails classes (ApplicationJob, ApplicationRecord, etc.)
+# that are not yet available at initializer time.
 Rails.application.config.to_prepare do
-  TCB.configure do |c|
-    c.event_bus   = TCB::EventBus.new(
-      handle_signals: true,
-      shutdown_timeout: 10.0
-    )
-    c.event_store = TCB::EventStore::ActiveRecord.new
-  end
+  TCB.domain_modules = [
+    # Orders,
+    # Notifications,
+  ]
 end
+
+# Infrastructure — how events are transported and stored
+# Configure per environment in config/environments/*.rb so differences are explicit.
+# Example for development:
+#
+#   Rails.application.config.to_prepare do
+#     TCB.reset!
+#     TCB.configure do |c|
+#       c.event_bus   = TCB::EventBus.new(handle_signals: false, shutdown_timeout: 10.0)
+#       c.event_store = TCB::EventStore::ActiveRecord.new
+#     end
+#   end
+#
+# See README for production and test examples.

data/lib/generators/tcb/outbox/outbox_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module TCB
+  module Generators
+    class OutboxGenerator < Rails::Generators::Base
+      namespace "tcb:outbox"
+      source_root File.expand_path("templates", __dir__)
+
+      argument :module_name, type: :string
+
+      def create_migration
+        timestamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+        template "migration.rb.tt", "db/migrate/#{timestamp}_create_#{table_name}.rb"
+      end
+
+      def create_job
+        template "job.rb.tt", "app/jobs/#{job_file_name}.rb"
+      end
+
+      private
+
+      def table_name
+        "#{module_name.underscore}_outbox"
+      end
+
+      def migration_class_name
+        "Create#{module_name.camelize}Outbox"
+      end
+
+      def module_class_name
+        module_name.camelize
+      end
+
+      def job_class_name
+        "#{module_name.camelize}OutboxJob"
+      end
+
+      def job_file_name
+        "#{module_name.underscore}_outbox_job"
+      end
+    end
+  end
+end

data/lib/generators/tcb/outbox/templates/job.rb.tt

@@ -0,0 +1,11 @@
+class <%= job_class_name %> < ApplicationJob
+  queue_as :default
+
+  def perform
+    TCB::OutboxRelay.new(
+      outbox_store: <%= module_class_name %>::OutboxRecord,
+      event_store:  TCB.config.event_store,
+      lock_timeout: 300
+    ).run
+  end
+end

data/lib/generators/tcb/outbox/templates/migration.rb.tt

@@ -0,0 +1,20 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[8.1]
+  def change
+    create_table :<%= table_name %>, id: false, primary_key: :id do |t|
+  t.string :id, null: false
+      t.string   :event_id,      null: false
+      t.string   :stream_id,     null: false
+      t.integer  :version,       null: false
+      t.string   :handler_class, null: false
+      t.string   :status,        null: false, default: "pending"
+      t.datetime :locked_at
+      t.datetime :delivered_at
+      t.text     :error
+      t.datetime :created_at,    null: false
+    end
+
+    add_index :<%= table_name %>, :status
+    add_index :<%= table_name %>, [:status, :locked_at]
+    add_index :<%= table_name %>, [:stream_id, :version]
+  end
+end

data/lib/tcb/configuration.rb

@@ -30,11 +30,24 @@ module TCB
       @event_store
     end
 
+    def outbox_store_class=(store)
+      @outbox_store_class = store
+    end
+
+    def outbox_store_class
+      @outbox_store_class
+    end
+
+    def outbox_registrations
+      @outbox_registrations ||= []
+    end
+
     def domain_modules=(modules)
       @domain_modules = modules
       flush_domain_modules
       flush_command_handlers
       flush_persist_registrations
+      flush_outbox_registrations
     end
 
     def domain_modules
@@ -108,8 +121,63 @@ module TCB
         domain_module.persist_registrations.each do |registration|
           @persist_registrations << registration.with(context: context)
         end
-        define_event_record_for(domain_module)
+        define_event_record_for(domain_module) if active_record_store?
+      end
+    end
+
+    def active_record_store?
+      defined?(::ActiveRecord) && @event_store.is_a?(TCB::EventStore::ActiveRecord)
+    end
+
+    def flush_outbox_registrations
+      @outbox_registrations = []
+      @domain_modules.each do |domain_module|
+        next unless domain_module.respond_to?(:outbox_registrations)
+        next unless domain_module.outbox_registrations.any?
+
+        validate_outbox_registrations!(domain_module)
+        store = build_outbox_store(domain_module)
+
+        domain_module.outbox_registrations.each do |r|
+          @outbox_registrations << r.with(outbox_store: store)
+        end
+      end
+    end
+
+
+    def validate_outbox_registrations!(domain_module)
+      persisted_event_classes = domain_module.persist_registrations.flat_map(&:event_classes)
+
+      domain_module.outbox_registrations.map(&:event_class).uniq.each do |event_class|
+        unless persisted_event_classes.include?(event_class)
+          raise ConfigurationError,
+            "#{event_class} has ensure_reaction in #{domain_module} but is not persisted."
+        end
+      end
+
+      unless @outbox_store_class
+        raise ConfigurationError,
+          "#{domain_module} has outbox registrations but no outbox_store_class is configured."
+      end
+    end
+
+    def build_outbox_store(domain_module)
+      if active_record_store?
+        define_outbox_record_for(domain_module)
+        @outbox_store_class.new(domain_module.const_get(:OutboxRecord))
+      else
+        @outbox_store_class.new(nil)
+      end
+    end
+
+    def define_outbox_record_for(domain_module)
+      return if domain_module.const_defined?(:OutboxRecord, false)
+
+      klass = Class.new(::ActiveRecord::Base) do
+        self.table_name  = DomainContext.from_module(domain_module).outbox_table_name
+        self.primary_key = "id"
       end
+      domain_module.const_set(:OutboxRecord, klass)
     end
 
     def define_event_record_for(domain_module)
@@ -121,4 +189,4 @@ module TCB
       domain_module.const_set(:EventRecord, klass)
     end
   end
-end
+end

data/lib/tcb/domain_context.rb

@@ -5,6 +5,8 @@ module TCB
     NAMESPACE_SEPARATOR = "/"
     TABLE_SEPARATOR     = "__"
     TABLE_SUFFIX        = "_events"
+    OUTBOX_SUFFIX       = "_outbox"
+
 
     def self.from_module(domain_module)
       value = domain_module.name
@@ -25,5 +27,11 @@ module TCB
         .gsub(NAMESPACE_SEPARATOR, TABLE_SEPARATOR)
         .concat(TABLE_SUFFIX)
     end
+
+    def outbox_table_name
+      value
+        .gsub(NAMESPACE_SEPARATOR, TABLE_SEPARATOR)
+        .concat(OUTBOX_SUFFIX)
+    end
   end
 end

data/lib/tcb/event_store/in_memory.rb

@@ -37,6 +37,15 @@ module TCB
           .then { |e| limit          ? e.first(limit)                                      : e }
       end
 
+      def read_by_event_ids(event_ids)
+        @mutex.synchronize do
+          @streams.values
+            .flatten
+            .select { |envelope| event_ids.include?(envelope.event_id) }
+            .each_with_object({}) { |envelope, hash| hash[envelope.event_id] = envelope }
+        end
+      end
+
       def read_by_correlation(correlation_id, context:, occurred_after: nil, occurred_before: nil)
         @mutex.synchronize { @streams.values.flatten.dup }
           .select { |e| e.stream_id.start_with?(context) }

data/lib/tcb/handles_events.rb

@@ -4,20 +4,33 @@ module TCB
   module HandlesEvents
     EventHandlerRegistration = Data.define(:event_class, :handlers)
     PersistRegistration = Data.define(:event_classes, :stream_id_from_event, :context)
+    OutboxRegistration = Data.define(:event_class, :handler, :outbox_store)
 
     def self.included(base)
       base.extend(ClassMethods)
       base.instance_variable_set(:@event_handler_registrations, [])
       base.instance_variable_set(:@persist_registrations, [])
+      base.instance_variable_set(:@outbox_registrations, [])
     end
 
     module ClassMethods
+      def on(event_class, registration)
+        case registration
+        in EventHandlerRegistration => r
+          @event_handler_registrations << r.with(event_class: event_class)
+        in [OutboxRegistration, *] => registrations
+          registrations.each do |r|
+            @outbox_registrations << r.with(event_class: event_class)
+          end
+        end
+      end
+
       def react_with(*handlers)
         EventHandlerRegistration.new(event_class: :undefined, handlers: handlers)
       end
 
-      def on(event_class, registration)
-        @event_handler_registrations << registration.with(event_class: event_class)
+      def ensure_reaction(*handlers)
+        handlers.map { |handler| OutboxRegistration.new(event_class: :undefined, handler: handler, outbox_store: nil) }
       end
 
       def persist(registration)
@@ -39,6 +52,10 @@ module TCB
       def persist_registrations
         @persist_registrations
       end
+
+      def outbox_registrations
+        @outbox_registrations
+      end
     end
   end
-end
+end

data/lib/tcb/outbox_entry.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+TCB::OutboxEntry = Data.define(
+  :id,
+  :event_id,
+  :stream_id,
+  :version,
+  :handler_class,
+  :status,
+  :locked_at,
+  :delivered_at,
+  :error,
+  :created_at
+)

data/lib/tcb/outbox_relay.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module TCB
+  class OutboxRelay
+    def initialize(outbox_store:, event_store:, lock_timeout:)
+      @outbox_store = outbox_store
+      @event_store  = event_store
+      @lock_timeout = lock_timeout
+    end
+
+    def run
+      recover_stale_locks
+      entries    = lock_pending
+      envelopes  = fetch_envelopes(entries)
+      entries.each { |entry| process(entry, envelopes[entry.event_id]) }
+    end
+
+    private
+
+    def recover_stale_locks
+      @outbox_store.recover_stale_locks(older_than: Time.now - @lock_timeout)
+    end
+
+    def lock_pending
+      @outbox_store
+        .pending
+        .map { |e| @outbox_store.lock(e) }
+    end
+
+    def fetch_envelopes(entries)
+      @event_store.read_by_event_ids(entries.map(&:event_id))
+    end
+
+    def process(entry, envelope)
+      Object.const_get(entry.handler_class).new.call(envelope.event)
+      @outbox_store.mark_delivered(entry)
+    rescue => error
+      @outbox_store.mark_failed(entry, error: error)
+    end
+  end
+end

data/lib/tcb/outbox_store/active_record.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module TCB
+  module OutboxStore
+    class ActiveRecord
+      def initialize(model)
+        @model = model
+      end
+
+      def insert(event_id:, stream_id:, version:, handler_class:)
+        id = SecureRandom.uuid
+        now = Time.now
+
+        @model.create!(
+          id:            id,
+          event_id:      event_id,
+          stream_id:     stream_id,
+          version:       version,
+          handler_class: handler_class.name,
+          status:        "pending",
+          locked_at:     nil,
+          delivered_at:  nil,
+          error:         nil,
+          created_at:    now
+        )
+
+        OutboxEntry.new(
+          id:            id,
+          event_id:      event_id,
+          stream_id:     stream_id,
+          version:       version,
+          handler_class: handler_class.name,
+          status:        :pending,
+          locked_at:     nil,
+          delivered_at:  nil,
+          error:         nil,
+          created_at:    now
+        )
+      end
+
+      def all
+        @model.all.map { |r| to_entry(r) }
+      end
+
+      def pending
+        @model.where(status: "pending").order(:stream_id, :version).map { |r| to_entry(r) }
+      end
+
+      def lock(entry, locked_at: Time.now)
+        @model.where(id: entry.id).update_all(status: "locked", locked_at: locked_at)
+        entry.with(status: :locked, locked_at: locked_at)
+      end
+
+      def mark_delivered(entry, delivered_at: Time.now)
+        @model.where(id: entry.id).update_all(status: "delivered", delivered_at: delivered_at)
+        entry.with(status: :delivered, delivered_at: delivered_at)
+      end
+
+      def mark_failed(entry, error:)
+        @model.where(id: entry.id).update_all(status: "failed", error: error.message)
+        entry.with(status: :failed, error: error.message)
+      end
+
+      def recover_stale_locks(older_than:)
+        stale = @model.where(status: "locked").where("locked_at < ?", older_than)
+        stale.map do |record|
+          @model.where(id: record.id).update_all(status: "pending", locked_at: nil)
+          to_entry(record).with(status: :pending, locked_at: nil)
+        end
+      end
+
+      private
+
+      def to_entry(record)
+        OutboxEntry.new(
+          id:            record.id,
+          event_id:      record.event_id,
+          stream_id:     record.stream_id,
+          version:       record.version,
+          handler_class: record.handler_class,
+          status:        record.status.to_sym,
+          locked_at:     record.locked_at,
+          delivered_at:  record.delivered_at,
+          error:         record.error,
+          created_at:    record.created_at
+        )
+      end
+    end
+  end
+end

data/lib/tcb/outbox_store/in_memory.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module TCB
+  module OutboxStore
+    class InMemory
+      def initialize(_model = nil)
+        @entries = {}
+        @mutex = Mutex.new
+      end
+
+      def insert(event_id:, stream_id:, version:, handler_class:)
+        entry = OutboxEntry.new(
+          id:            SecureRandom.uuid,
+          event_id:      event_id,
+          stream_id:     stream_id,
+          version:       version,
+          handler_class: handler_class.name,
+          status:        :pending,
+          locked_at:     nil,
+          delivered_at:  nil,
+          error:         nil,
+          created_at:    Time.now
+        )
+        @mutex.synchronize { @entries[entry.id] = entry }
+        entry
+      end
+
+      def all
+        @mutex.synchronize { @entries.values.dup }
+      end
+
+      def pending
+        @mutex
+          .synchronize { @entries.values.select { |e| e.status == :pending }
+          .sort_by { |e| [e.stream_id, e.version] } }
+      end
+
+      def lock(entry, locked_at: Time.now)
+        updated = entry.with(status: :locked, locked_at: locked_at)
+        @mutex.synchronize { @entries[entry.id] = updated }
+        updated
+      end
+
+      def mark_delivered(entry, delivered_at: Time.now)
+        updated = entry.with(status: :delivered, delivered_at: delivered_at)
+        @mutex.synchronize { @entries[entry.id] = updated }
+        updated
+      end
+
+      def mark_failed(entry, error:)
+        updated = entry.with(status: :failed, error: error.message)
+        @mutex.synchronize { @entries[entry.id] = updated }
+        updated
+      end
+
+      def recover_stale_locks(older_than:)
+        stale = @mutex.synchronize do
+          @entries.values.select { |e| e.status == :locked && e.locked_at < older_than }
+        end
+
+        stale.map do |entry|
+          updated = entry.with(status: :pending, locked_at: nil)
+          @mutex.synchronize { @entries[entry.id] = updated }
+          updated
+        end
+      end
+    end
+  end
+end

data/lib/tcb/record.rb

@@ -2,26 +2,33 @@
 
 module TCB
   class Record
-    def self.call(events_from:, events:, within:, store:, registrations:, &block)
+    def self.call(
+      events_from:, events:, within:, store:, registrations:, outbox_registrations: [], &block
+    )
       raise ArgumentError, "events_from: or events: must be provided" if events_from.empty? && events.empty?
 
       new(
-        events_from:    events_from,
-        events:         events,
-        store:          store,
-        registrations:  registrations,
-        correlation_id: Thread.current[:tcb_correlation_id],
-        causation_id:   Thread.current[:tcb_causation_id]
+        events_from:          events_from,
+        events:               events,
+        store:                store,
+        registrations:        registrations,
+        outbox_registrations: outbox_registrations,
+        correlation_id:       Thread.current[:tcb_correlation_id],
+        causation_id:         Thread.current[:tcb_causation_id]
       ).call(within: within, &block)
     end
 
-    def initialize(events_from:, events:, store:, registrations:, correlation_id: nil, causation_id: nil)
-      @events_from    = events_from
-      @events         = events
-      @store          = store
-      @registrations  = registrations
-      @correlation_id = correlation_id
-      @causation_id = causation_id
+    def initialize(
+      events_from:, events:, store:, registrations:, outbox_registrations: [],
+      correlation_id: nil, causation_id: nil
+    )
+      @events_from          = events_from
+      @events               = events
+      @store                = store
+      @registrations        = registrations
+      @outbox_registrations = outbox_registrations
+      @correlation_id       = correlation_id
+      @causation_id         = causation_id
     end
 
     def call(within:, &block)
@@ -38,7 +45,9 @@ module TCB
       block.call if block
       events  = @events_from.flat_map(&:pull_recorded_events)
       events += @events
-      persist(events)
+      envelopes = persist(events)
+      insert_outbox_entries(envelopes)
+      envelopes
     rescue
       @events_from.each(&:pull_recorded_events)
       raise
@@ -53,6 +62,19 @@ module TCB
       order_by_original(events, persisted, remaining)
     end
 
+    def insert_outbox_entries(envelopes)
+      envelopes.each do |envelope|
+        @outbox_registrations
+          .select { |r| r.event_class == envelope.event.class }
+          .each   { |r| r.outbox_store.insert(
+            event_id:      envelope.event_id,
+            stream_id:     envelope.stream_id,
+            version:       envelope.version,
+            handler_class: r.handler
+          )}
+      end
+    end
+
     def persist_to_store(events)
       grouped = Hash.new { |h, k| h[k] = [] }
 

data/lib/tcb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TCB
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

data/lib/tcb.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 require_relative "tcb/envelope"
+require_relative "tcb/outbox_entry"
 require_relative "tcb/minitest_helpers"
 require_relative "tcb/domain_context"
 require_relative "tcb/correlation_query"
 require_relative "tcb/event_query"
 require_relative "tcb/event_store/active_record"
 require_relative "tcb/event_store/in_memory"
+require_relative "tcb/outbox_store/in_memory"
+require_relative "tcb/outbox_store/active_record"
+require_relative "tcb/outbox_relay"
 require_relative "tcb/stream_id"
 require_relative "tcb/handles_events"
 require_relative "tcb/handles_commands"
@@ -43,11 +47,12 @@ module TCB
 
   def self.record(events_from: [], events: [], within: nil, &block)
     Record.call(
-      events_from: events_from,
-      events: events,
-      within: within,
-      store: config.event_store,
-      registrations: config.persist_registrations,
+      events_from:          events_from,
+      events:               events,
+      within:               within,
+      store:                config.event_store,
+      registrations:        config.persist_registrations,
+      outbox_registrations: config.outbox_registrations,
       &block
     )
   end
@@ -59,6 +64,16 @@ module TCB
     )
   end
 
+  def self.reactions_for(event_class)
+    domain_modules.flat_map do |mod|
+      next [] unless mod.respond_to?(:event_handler_registrations)
+
+      mod.event_handler_registrations
+        .select { |r| r.event_class == event_class }
+        .flat_map(&:handlers)
+    end
+  end
+
   def self.read_correlation(correlation_id, across: nil)
     domains = across || config.domain_modules.select do |m|
       m.respond_to?(:persist_registrations) && m.persist_registrations.any?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tcb
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Ljubomir Marković
@@ -141,6 +141,9 @@ files:
 - lib/generators/tcb/event_store/templates/migration.rb.tt
 - lib/generators/tcb/install/install_generator.rb
 - lib/generators/tcb/install/templates/tcb.rb.tt
+- lib/generators/tcb/outbox/outbox_generator.rb
+- lib/generators/tcb/outbox/templates/job.rb.tt
+- lib/generators/tcb/outbox/templates/migration.rb.tt
 - lib/generators/tcb/shared/command_argument.rb
 - lib/tcb.rb
 - lib/tcb/command_bus.rb
@@ -163,6 +166,10 @@ files:
 - lib/tcb/handles_commands.rb
 - lib/tcb/handles_events.rb
 - lib/tcb/minitest_helpers.rb
+- lib/tcb/outbox_entry.rb
+- lib/tcb/outbox_relay.rb
+- lib/tcb/outbox_store/active_record.rb
+- lib/tcb/outbox_store/in_memory.rb
 - lib/tcb/publish.rb
 - lib/tcb/record.rb
 - lib/tcb/records_events.rb
@@ -192,7 +199,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.11
 specification_version: 4
 summary: Lightweight DDD runtime for Rails — events, commands, and aggregates
 test_files: []