tcb 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d004e21f0c4555988f0a5b84e40a4ae4710933b3e862ab964a6a4bc07cd02cf
-  data.tar.gz: 684c9a07870739ebec829c872f6c4c71d455b0919d369d0f9badd000fceb28d3
+  metadata.gz: e9fdc75ccfefebb2cb421260d89276f946b42f3d0f9e7ed90438b1d2cce1da8c
+  data.tar.gz: d48eee8151fc7ea5b2339f8949fc68bd6f04b61062007aff2f335e2f2f1b367d
 SHA512:
-  metadata.gz: 71b0fe98490c7a0c1d995b7eaf7612976690306c55c1ccc904f4038089f11c3f6389e03afd9474fd1a058c28de4905fdfca811cb4e88fcf77119a361cde3ff3f
-  data.tar.gz: a433451a28f9fe1bd295db4fe40e4760069d4d4915ec8807f8f35f2791df6821dd86f1e24b7c57bbb470dc9b4d618f540e26862a61461e71af9c839bc881a661
+  metadata.gz: 5b8d0a0de064464890a11e71649dbb587fa032cccfd6d57ebaebfe350303ad725519cf7c8b66e8ec48d9b6092d8082e8167daa9d81d3d1cdc632cb3c50f67107
+  data.tar.gz: cccbab25a067c195d236f8e83796099d4eae236061021d3fe9a7547016a79b5a4f1bb22d525d9ce8cd506d5eb14be865c31e0417dbb1cc5ef9c8eb2ed52384d3

data/CHANGELOG.md

@@ -5,6 +5,24 @@ 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

data/README.md

@@ -32,6 +32,29 @@ Clean domain code pays compound interest. It's easier to reason about, easier to
 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)
+
+---
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -163,7 +186,7 @@ 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,
@@ -255,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
 ```
 
@@ -392,6 +407,103 @@ 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
@@ -414,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
 ```
@@ -430,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
 ```
@@ -445,8 +559,9 @@ 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
 ```
@@ -463,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.
@@ -559,6 +693,22 @@ Results are ordered by `occurred_at` across all domains. Each result is a `TCB::
 
 ---
 
+## 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.
+
+---
+
 ## Event Store Adapters
 
 ### In-Memory (for tests)

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.2"
+  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.2
+  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: 4.0.6
+rubygems_version: 4.0.11
 specification_version: 4
 summary: Lightweight DDD runtime for Rails — events, commands, and aggregates
 test_files: []