Hi, we're Arkency

Ingress is not the owner of the invariant

2026-06-16T13:21:30Z

Ingress is not the owner of the invariant

A polemic with Callbacks Are Not Invariants by Brandon Weaver.

A disclaimer: I’m a RailsEventStore maintainer and this article ends up on the Arkency blog — so cards are on the table. Despite this, I’m keeping the core of my argument in pure ActiveRecord: no step of the reasoning requires RES. I only show the RES version at the end, separately, as “and this is what it looks like when you’re not typing it in manually”. If you’re convinced by the bare-metal AR reasoning, not the library, that’s what matters.

We agree about the disease

I enjoy reading Brandon’s Rails: The Sharp Parts series and sending it to the team — it’s one of the better pieces on the sharp edges of Rails that’s come out lately. The one about callbacks is no exception and the diagnosis is spot on. Census _save_callbacks, which shows eleven entries with two association lines and zero callbacks of its own. A mismatch between what fires before and after COMMIT. The best sentence in the entire text: “a callback is an invariant with a published bypass list” — update_all, insert_all, update_column are holes in something that was supposed to always happen.

I’m not here to defend the callbacks. I hate them myself, for the same reasons. The dispute is about the cure.

And I have one reservation for the cure Brandon proposes — and it doesn’t concern what he built, but how he named it. Because the name will travel beyond a single file, to anyone who copies the template.

A name that promises more than it delivers

What the author calls Command is Fowler’s Transaction Script. One public call, a private execute, a procedure orchestrating ActiveRecord calls. And that’s a good pattern — it’s forty years old and still going strong. The thing is, he calls it a command (suggesting CQRS, which itself announces next time) and calls ActiveSupport::Notifications events.

A name isn’t cosmetic. A name is a mental contract. When 500 engineers work in a monolith — and that’s the scale Weaver explicitly writes for — names are the only documentation anyone reads. If you tell them they’re building commands and events, in a year, half the company will think they’re building an event-driven architecture with procedures in their hands. That’s worse than no name, because it installs a mental model that doesn’t match the code.

And this isn’t about arguing with its values but about appealing to them. Brandon writes about himself that his goal is to make the invisible visible — and that the next person reading the code shouldn’t have to wonder what the author meant. I agree with that with both hands. And that’s precisely why calling a procedure a command and a notification an event plays against what he wants: it forces the reader to assume a contract — a serializable intent with a separate handler, a persistent domain fact — that doesn’t exist in the code. Correcting the names isn’t a quarrel with Weaver; it’s the completion of his own goal.

Core: ingress doesn’t own the invariant

Single-ingress is correct — one write path per operation, one entry point that owns the state change. But look where the “space cannot be reserved twice” invariant lives after the refactor:

def reserve
  seat = Seat.find(seat_id)
  seat.with_lock do
    raise AlreadyReserved, "seat #{seat_id} is already reserved" if seat.reserved?
    seat.update!(reserved: true, reserved_by: by)
    Ledger::RecordReservation.call(seat: seat, by: by)
  end
  seat
end

The rule is spread across three layers:

a check in runtime (if seat.reserved?)
a row lock (with_lock)
a constraint in the database — as Brandon rightly writes elsewhere.

This isn’t a domain model. It’s a Seat.find + update! wrapped in a procedure. Infrastructure-first, just repurposed from a callback to a service object. The question “who owns the reservation rule” still doesn’t have a single answer.

The coupling is now deliberate and visible — but it’s still there. One trade-off and one naming issue:

Side effects inline in execute. Weaver is explicit about this: announce belongs to the command body by design, not by accident — subscribers are reserved for observability only and cannot veto a write or introduce ordering dependencies. That’s a defensible trade-off: visible coupling beats hidden coupling every time. My claim is narrower: announce fires after with_lock commits, so the timing is fine — but if the process dies between commit and deliver_later, the effect is gone forever. There is nothing to replay from, because the fact was never persisted.

event_name from the namespace system. The event name extracted from module_parent_name ties the event taxonomy — that is, the contract — to the directory structure in the code. Move a module, and the names of events that someone might already be subscribed to change. This is exactly the kind of invisible coupling he’s been fighting against throughout this article — only this time it moves a layer higher.

What it looks like when an invariant has an owner

I’ll show the difference in code, because otherwise, it’s just adjectives. Pure ActiveRecord, without RailsEventStore.

First, the aggregate. It — and only it — decides whether the reservation is allowed and produces the fact. No IO, no mailer, no webhook:

class Seat < ApplicationRecord
  class AlreadyReserved < StandardError; end

  # Invariant lives here. In one place. The method always returns an event,
  # and doesn't fire side effects.
  def reserve(by:)
    raise AlreadyReserved, "seat #{id} is already reserved" if reserved?

    self.reserved    = true
    self.reserved_by = by
    self.reserved_at = Time.current

    SeatReserved.new(seat_id: id, reserved_by: by, reserved_at: reserved_at)
  end
end

An event is a fact. Past tense. Payload is a result, not a request:

SeatReserved = Data.define(:seat_id, :reserved_by, :reserved_at) do
  def event_name = "seat_reserved"
end

The handler is a simple PORO — one application use-case, one entrance for write. We’re keeping Brandon’s single-entry discipline because it’s good; we’re not inheriting his ApplicationCommand base — its only job was announce, and that role is now taken by the explicit SeatReserved with persistent log write and subscribers. There’s no constructor, no ivars, and no self.call to new.call relay — the handler is so thin that there’s nothing to decompose. And that’s the point: the rule has been moved to the aggregate, so orchestration remains trivial, and everything happens on the correct side of the commit.

module Seats
  class ReserveSeat
    def self.call(seat_id:, by:)
      Seat.transaction do
        seat  = Seat.lock.find(seat_id)
        event = seat.reserve(by:)   # aggregate guards the invariant 
        seat.save!
        Events.publish(event)       # fact in the same transaction
        event
      end
    end
  end
end

Events.publish does two things, both in the caller’s transaction: it writes the event to a persistent log and synchronously calls subscribers. First, the log: append-only, the source of truth, from which you replay:

# Persistent event log — source of truth. 
# As long as the event lives here, it can be replayed.

class StoredEvent < ApplicationRecord
  def self.append(event)
    create!(name: event.event_name, payload: event.to_h, occurred_at: Time.current)
  end
end

And the dispatcher. No magic at all: publish stores the fact, and then calls handlers subscribed to the event name — in the same thread, and in the same transaction:

# publish: persistent fact + sync subscribers, atomically with the state change.
module Events
  HANDLERS = Hash.new { |h, k| h[k] = [] }

  def self.publish(event)
    StoredEvent.append(event)
    HANDLERS[event.event_name].each { |handler| handler.call(event) }
  end

  def self.subscribe(event_name, &handler)
    HANDLERS[event_name] << handler
  end
end

Here’s all the persistence I need: StoredEvent.append runs in the same transaction as seat.save! — because publish doesn’t open its own transaction, the INSERT inherits the active one from the caller. The fact commits with the state change or not at all. Since the fact remains, any reaction can be recreated — handler retry, log replay. This is the invariant, and you have it without any additional machinery.

One fair boundary. The subscribers above execute synchronously, in a transaction — which is exactly what you want for reactions intended to be atomic with the fact. But a subscriber doing heavy or external IO (mail, webhook) shouldn’t block the transaction; it schedules the work asynchronously, via deliver_later. And here comes the only gap Weaver worries about: the very scheduling of this asynchronous work isn’t atomic by default with the fact’s save. This narrow gap — and nothing else — is patched by the transactional outbox. It doesn’t patch the persistence of the fact, because that’s already taken care of.

And the mailer and the webhook? They react to the fact. They’re not steps in the write path — they’re subscribers. You can add, remove, or replace one without touching the ReserveSeat:

Events.subscribe("seat_reserved") do |event|
  ReservationMailer.confirmed(event.seat_id).deliver_later
end

Events.subscribe("seat_reserved") do |event|
  Webhooks::Emit.call(event: :seat_reserved, payload: event.to_h)
end

Let’s compare both approaches:

	Weaver	Here
Invariant	runtime check + `with_lock` + constraint	`Seat#reserve`, single place
Event	`reserve_seat.seats` from namespace, payload = input	`seat_reserved`, explicit, payload = result
Side-effects	inline in `announce` (deliberate — observability subscribers can’t veto writes)	subscribers react to the persisted fact
Delivery	fire-and-forget after commit, can be lost	event in a transaction, always replayable

And here’s the point I care about most — because it affects the domain I’m currently working on: persisting the fact isn’t an add-on — it’s a day-one invariant. Weaver himself is clear: “If you need durable event delivery (guaranteed at-least-once), that’s a transactional outbox or CDC, not a subscriber.” So we agree on the destination. Where I part ways is the framing: he presents it as something you reach for at scale. When SeatReserved is saved in the same transaction as the state change, no effect can be lost forever: since the fact remains, the reaction can always be recreated — retry the handler, replay from the log. Outbox doesn’t create this persistence — it only uses it, automating the delivery with an at-least-once guarantee — which means subscribers must be idempotent. You don’t persist the fact because you scaled; you persist it from the first INSERT and harden delivery when the async scheduling gap becomes relevant.

And if you don’t want to write it by hand

The above is on bare AR intentionally, so the argument can stand up without any library. But you get the same structure off the shelf. Aggregate with AggregateRoot:

class Seat
  include AggregateRoot

  AlreadyReserved = Class.new(StandardError)

  def reserve(by:)
    raise AlreadyReserved if @reserved
    apply SeatReserved.new(data: { seat_id: @id, reserved_by: by })
  end

  on SeatReserved do |event|
    @reserved    = true
    @reserved_by = event.data.fetch(:reserved_by)
  end
end

An invariant in reserve, a fact in SeatReserved, a state mutation in on — and this is an event that actually lands in the event store, with versioning and replay, not a notification whose name is derived from a namespace. You attach handlers (mailer, webhook) as subscribers exactly as above.

And delivery? RES publish is exactly Events.publish: atomic write to the event store plus synchronous dispatch, inside the caller’s transaction. ruby_event_store-outbox patches the one gap I named above — transactional scheduling of async handlers — maintained, safe under concurrent workers, covered with mutation tests.

A complete walkthrough of RES — aggregates, subscriptions, outbox, strangler on an existing monolith — is a topic for a separate, much longer text. Let me preface this point, as Brandon rightly dislikes rewrites; this path isn’t rewriting. It’s strangler — precisely the incremental movement it describes, callback by callback, flag by flag. The punchline here is enough: the structure he’s approaching is available as a ready-made library, not an exotic one.

Where Weaver is right — and what I’m not saying

I’m not advocating “always event sourcing”. That would be precisely the dogmatic approach I combat in people who sell event sourcing as a religion.

His Transaction Script is sufficient for most applications. One team, one write path, reasonable discipline — and a procedure with a single input carries water for years. The Strangler fig + Flipper migrations he describes are really good. Normalizes for pure transformations — agree. Constraints as truth in the database — agree, and strongly so. His CommandSingleEntrant RuboCop cop makes the single-entry rule structural rather than disciplinary — and he’s honest about its reach: “Both catch the common mistakes”, with class << self patterns as a known blind spot.

My point isn’t “your pattern is too weak”. It’s: don’t call it a command and event when it isn’t. Because the difference between a procedure and a command, and between notification and a domain event, isn’t pedantry — it’s the difference between “an invariant has an owner” and “an invariant is smeared, but nicely named”.

I anticipate three counterarguments:

“It’s a dispute about names.” Yes — and names are a contract that will reach 500 people. A bad mental model scales worse than bad code, because code gets refactored, but beliefs don’t.

“ES is overkill.” Agreed, for most people. But a persistent record of a fact isn’t event sourcing — it’s a single INSERT in the same transaction as a state change, turning “effect can be lost” into “effect always recoverable”. You don’t skip this because you’re not doing event sourcing; it’s record path hygiene, not architecture.

Steelman 37signals — whom Weaver honestly quotes — says that disciplined callbacks scale further than they’re given credit for. In a single, cohesive team: they’re not wrong. But the same caveat applies to his solution: Transaction Script without an invariant owner also relies on discipline, which is generally absent with 500 people. The aggregate approach doesn’t ask for discipline — the structure enforces the rule.

Landing

Single-ingress is correct. But an ingress that doesn’t own the invariant isn’t a fix — it’s moving the same rule spread from a callback to a procedure. And calling that procedure a command and the notification an event installs a mental model for 500 engineers that doesn’t fit the code they have in their hands.

The strongest version of his own argument isn’t the one he wrote — it’s the one he’s getting closer to: an aggregate that monitors the invariant, a true domain event, and a fact persisted in the same transaction as the state change. Weaver ends with a CQRS announcement “next time,” and it’s a good announcement, because single-ingress without an invariant owner is only halfway down the road he’s charted.

I look forward to the continuation of the series — honestly, without irony.

Let Your AI Assistant Explore the Event Store with res-mcp

2026-06-11T10:00:00Z

Let Your AI Assistant Explore the Event Store with `res-mcp`

When you’re debugging with an AI assistant, half the work is giving it enough context. You copy event payloads into the chat, paste stream contents, look up IDs, then repeat the process every time you need another piece of information.

ruby_event_store-mcp removes that step. It’s the companion to the res CLI. Instead of you querying the event store from the terminal, your AI assistant does it for you through MCP tools. You ask questions in plain English, it reads the events itself.

The difference from copying the events into the chat yourself is that the assistant can ask follow-up questions on its own. If it needs to inspect another stream, load an aggregate’s history, or trace a correlation, it simply calls another tool. You stay in the conversation instead of switching between your AI client and a terminal.

Setup

Add the gem and install:

gem "ruby_event_store-mcp"

bundle install

That installs the res-mcp binary — but it doesn’t register anything with your AI client yet. The binary speaks MCP over stdio, launched from your app’s root, where — exactly like the res CLI — it loads config/environment.rb and reads your app’s Rails.configuration.event_store. There’s no HTTP endpoint to mount and nothing to deploy. Telling your client about it is a separate, one-time step — and every MCP client takes the same server definition, only the file it goes in changes.

Claude Code — drop a .mcp.json in your project root:

{
  "mcpServers": {
    "res": {
      "command": "bundle",
      "args": ["exec", "res-mcp"]
    }
  }
}

(or run claude mcp add res -- bundle exec res-mcp). Launched from the project directory, Claude Code runs the server there, so no cwd is needed. On the next launch it asks you to trust the project’s MCP server — approve it, then run /mcp to see res connected with its nine tools.

Claude Desktop — the same block, but with an explicit cwd pointing at your app’s root, in claude_desktop_config.json:

{
  "mcpServers": {
    "res": {
      "command": "bundle",
      "args": ["exec", "res-mcp"],
      "cwd": "/path/to/your/rails/app"
    }
  }
}

(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json.)

Other MCP clients — Cursor, Windsurf, Cline and the rest take the same mcpServers block in their own config file; VS Code’s built-in MCP uses a servers key with "type": "stdio" instead. The bundle exec res-mcp command is the portable part.

That’s the whole setup. No routes, no mounts, no credentials.

Ask questions, not commands

Once it’s connected you just talk to the assistant — no slash command, no skill. You ask in plain English and it decides which tools to call (the first call asks your permission; allowlist the res server to stop being asked).

The server gives the assistant nine read-only tools over your event store. You never call them by name — you ask a question, and the assistant picks the tools it needs. They cover three kinds of questions:

Browse streams and events

stream_show — a stream’s event count, version, and first/last event
stream_events — the events in a stream, filterable by type, time, or position
event_show — one event in full, data and metadata
event_streams — every stream a given event belongs to

Search and summarize

recent — the most recent events across the whole store (“what just happened?”)
search — events anywhere, filtered by type, time range, or stream
stats — total counts and the unique event types present

Follow a process

aggregate_history — the full event history of one aggregate instance (e.g. a single Fulfillment::Order)
trace — the causation tree of everything sharing a correlation ID, so you can see where a multi-step flow stopped

Examples

For example, instead of browsing the streams yourself, you can simply ask:

“What just happened? Show the 20 most recent events.”

“Walk me through the history of Fulfillment::Order f47ac10b-58cc-4372-a567-0e02b2c3d479.”

“Are there any OrderPlaced events from the last hour without a matching OrderConfirmed?”

“Trace correlation 452fd6f0-e3a2-4716-bc8a-43bbcf2cae61 — where did the process stop?”

The assistant calls recent, aggregate_history, search, or trace behind the scenes, reads the results, and reasons over them — no copy-pasting event payloads into the chat, no switching to a Rails console mid-thought.

Why it’s safe to point at any app

Every tool uses the public event_store.* API — the same one your application uses through Rails.configuration.event_store. There’s no direct SQL access, no ActiveRecord internals, and no adapter-specific code.

The server is also intentionally read-only. Your AI assistant can inspect events, streams, and correlations, but it cannot append, link, or delete events. The worst it can do is answer your questions.

Inspect Your Event Store From the Terminal With the res CLI

2026-06-02T10:00:00Z

Inspect Your Event Store From the Terminal With the `res` CLI

Because not every debugging session needs rails c.

Most event store debugging starts the same way: you open a Rails console, try to remember the Event Store read API, and type something like:

event_store.read.stream("Order$123").to_a

It works, but it’s a lot of ceremony just to answer questions like:

What happened in this stream?
Was this event actually persisted?
What does the latest event look like?

The new contrib gem, ruby_event_store-cli, gives you a dedicated res command for inspecting your Event Store directly from the terminal. No Rails console. No SQL queries. No custom rake tasks. Just a fast, convenient way to browse streams and events while you’re developing or debugging.

Add it to your Gemfile:

gem "ruby_event_store-cli"

The CLI loads your Rails environment, so it connects to the same Rails.configuration.event_store your application uses. Once it’s running, you can inspect streams, read events, search across the store, trace correlations, or watch new events arrive — all without leaving your terminal. Here’s a quick taste:

bundle exec res stream show Order$<order_id>
bundle exec res stream events Order$<order_id> --limit 20
bundle exec res event show 59588873-00fa-423f-89d1-03d7c3b0ab35
bundle exec res search --type OrderPlaced --after 2026-03-01T00:00:00Z
bundle exec res stats

Say an order never gets confirmed. Instead of reaching for rails c, you can walk the whole story from the terminal:

bundle exec res stream show Order$<order_id>
bundle exec res stream events Order$<order_id>
bundle exec res trace <correlation_id>

In under a minute you’ve gone from “something’s wrong” to seeing exactly where the workflow stopped. The rest of this post walks through each command in detail.

Streams

`stream show` — a stream at a glance

Event count, current version, and the first and last event:

$ bundle exec res stream show 'Order$f47ac10b-58cc-4372-a567-0e02b2c3d479'
Stream:  Order$f47ac10b-58cc-4372-a567-0e02b2c3d479
Events:  2
Version: 1
First:   2026-03-24T17:45:03.891Z (OrderPlaced)
Last:    2026-03-24T17:46:12.004Z (OrderConfirmed)

`stream events` — read the events

By default it prints the stream as a table:

$ bundle exec res stream events Order$<order_id>
EVENT ID                              TYPE                                      TIMESTAMP
------------------------------------------------------------------------------------------
59588873-00fa-423f-89d1-03d7c3b0ab35  OrderPlaced                               2026-03-24T17:45:03.891Z
6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f  OrderConfirmed                            2026-03-24T17:46:12.004Z

2 event(s)

Narrow it down with filters — they combine freely:

# Filter by event type
bundle exec res stream events Order$<order_id> --type OrderPlaced

# Newer than a timestamp (ISO8601)
bundle exec res stream events Order$<order_id> --after 2026-03-01T00:00:00Z

# Older than a timestamp
bundle exec res stream events Order$<order_id> --before 2026-04-01T00:00:00Z

# Cap the number of events (default: 50)
bundle exec res stream events Order$<order_id> --limit 10

# Paginate — start after a known event ID
bundle exec res stream events Order$<order_id> --from 3fa85f64-5717-4562-b3fc-2c963f66afa6

Add --follow (or -f) to keep the command running and print new events in this stream as they arrive — a live tail of a single stream:

bundle exec res stream events Order$<order_id> --follow

Events

`event show` — everything about one event

Full detail for a single event ID, data and metadata included:

$ bundle exec res event show 59588873-00fa-423f-89d1-03d7c3b0ab35
Event ID:   59588873-00fa-423f-89d1-03d7c3b0ab35
Type:       OrderPlaced
Timestamp:  2026-03-24T17:45:03.891Z
Valid at:   2026-03-24T17:45:03.891Z
Data:       {
  "order_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "customer_id": "c-1024",
  "total": "149.00"
}
Metadata:   {
  "correlation_id": "452fd6f0-e3a2-4716-bc8a-43bbcf2cae61",
  "causation_id": "452fd6f0-e3a2-4716-bc8a-43bbcf2cae61"
}

`event streams` — where an event lives

An event is published to one stream and can be linked into many. This lists every stream it belongs to:

$ bundle exec res event streams 59588873-00fa-423f-89d1-03d7c3b0ab35
Order$f47ac10b-58cc-4372-a567-0e02b2c3d479
$by_type_OrderPlaced
$by_correlation_id_452fd6f0-e3a2-4716-bc8a-43bbcf2cae61

Search across the store

`search` — find events anywhere

stream events is scoped to one stream; search looks across the whole store. Same filters — --type, --after, --before, --limit — plus --stream to scope back down when you want to:

$ bundle exec res search --type OrderPlaced --after 2026-03-01T00:00:00Z
EVENT ID                              TYPE                                      TIMESTAMP
------------------------------------------------------------------------------------------
59588873-00fa-423f-89d1-03d7c3b0ab35  OrderPlaced                               2026-03-24T17:45:03.891Z
8b1f2c3d-1a2b-4c3d-9e8f-7a6b5c4d3e2f  OrderPlaced                               2026-03-22T09:13:55.620Z

2 event(s)

`stats` — counts and types

Total event count and the unique event types present — across the store, or for one stream with --stream:

$ bundle exec res stats
Events:  1432

Event types:
  OrderCancelled
  OrderConfirmed
  OrderPlaced
  PaymentAuthorized
  ShipmentScheduled

$ bundle exec res stats --stream Order$<order_id>
Stream:  Order$f47ac10b-58cc-4372-a567-0e02b2c3d479
Events:  2

Event types:
  OrderConfirmed
  OrderPlaced

JSON output

stream events and search can both emit JSON instead of a table with --format json. That makes them easy to combine with tools like jq or pipe into your own scripts:

# What data did our last OrderPlaced carry?
bundle exec res stream events Order$<order_id> \
  --type OrderPlaced \
  --limit 1 \
  --format json \
  | jq '.[0].data'

# Any events with missing customer_id?
bundle exec res search --type OrderPlaced --format json \
  | jq '.[] | select(.data.customer_id == null)'

# Unique event types in a stream
bundle exec res stream events Order$<order_id> --format json \
  | jq '[.[].event_type] | unique'

Each JSON event carries event_id, event_type, data, metadata, and timestamp — the keys the jq filters above reach into.

Trace correlated events

Give res trace a correlation ID and it gathers every event sharing it, then shapes them by causation — which event triggered which — into a tree:

$ bundle exec res trace 452fd6f0-e3a2-4716-bc8a-43bbcf2cae61
OrderPlaced [452fd6f0-e3a2-4716-bc8a-43bbcf2cae61]
├── PaymentAuthorized [7c9e6679-7425-40de-944b-e07fc1f90ae7]
│   └── OrderConfirmed [a1b2c3d4-5e6f-4a8b-9c0d-1e2f3a4b5c6d]
└── ShipmentScheduled [9f8e7d6c-5b4a-4938-8271-6f5e4d3c2b1a]

The tree makes it obvious where a workflow stopped. If a branch is missing, you immediately know which handler never published its follow-up event — without digging through logs.

trace relies on correlation linking. As related events are published, Rails Event Store links them into a $by_correlation_id_... stream while preserving correlation and causation IDs. The command simply reconstructs the tree from those links.

Watch events live

res watch gives you a live view of everything happening in the event store, grouped by bounded-context namespace (the part before :: in the event type). Handy during demos, load tests, or while reproducing a multi-step flow:

$ bundle exec res watch
Fulfillment (2 events)
  OrderPlaced                     17:45:03  452fd6f0-e3a2-4716-bc8a-43bbcf2cae61
  OrderConfirmed                  17:45:04  a1b2c3d4-5e6f-4a8b-9c0d-1e2f3a4b5c6d

Payments (1 events)
  PaymentAuthorized               17:45:03  7c9e6679-7425-40de-944b-e07fc1f90ae7

Watching since 17:45:00 — Press Ctrl+C to exit

The display updates in place instead of scrolling. A few flags control what it shows and how often:

--namespace Fulfillment,Payments — only show those namespaces
--since 2026-03-24T17:00:00Z — start from a timestamp instead of “now”
--limit 50 — max events shown per namespace (default: 50)
--interval 1 — refresh interval in seconds (default: 1)

Where stream events --follow tails one stream, watch gives you the whole store at a glance — two complementary live views.

The full command set

Eight commands in this first release, all reading through the public event_store API — no SQL, no adapter internals:

Command	What it does
`stream show`	Event count, version, and first/last event of a stream
`stream events`	Read a stream’s events, with filtering, pagination, and `--follow`
`event show`	Full detail of one event — data, metadata, timestamps
`event streams`	Every stream an event is published or linked to
`search`	Find events across all streams by type, time, or stream
`stats`	Total count and unique event types, store-wide or per stream
`trace`	Causation tree for everything sharing a correlation ID
`watch`	Live feed of new events, grouped by namespace

The CLI intentionally stays small. Every command goes through the public Rails Event Store API, so it works regardless of the storage adapter underneath. If you spend your day debugging event-driven applications, it’s often the quickest way to answer “what happened?” without opening rails c.

What's New in Rails Event Store 3.0

2026-06-02T10:00:00Z

What’s New in Rails Event Store 3.0

Rails Event Store 3.0 is primarily a cleanup release.

Throughout the 2.x series we introduced new features while gradually deprecating APIs we no longer wanted to maintain. In 3.0, those deprecated APIs are finally gone.

There are no major new concepts or APIs to learn. The public API is simply smaller, more consistent, and comes with a few stricter defaults.

If you’ve already addressed all deprecation warnings in 2.19, upgrading to 3.0 should be straightforward. This post summarizes what changed, while the 2.19 release announcement explains the motivation behind each deprecation in more detail.

Lean API: the deprecations are gone

The 2.x series was conservative — we kept old method names alive and just warned you about them. 3.0 removes the training wheels: every name kept around for compatibility is gone. Here’s the at-a-glance list of what’s removed and what replaces it (each row links to the reasoning in the 2.19 post):

Removed	Use instead
`read.in_batches_of(100)`	`read.in_batches(100)` details
`read.of_types([Type])`	`read.of_type(Type)` details
`RubyEventStore::ImmediateAsyncDispatcher`	`RubyEventStore::ImmediateDispatcher` details
`RailsEventStore::AfterCommitAsyncDispatcher`	`RailsEventStore::AfterCommitDispatcher` details
`RubyEventStore::Dispatcher`	`RubyEventStore::SyncScheduler` details
`subscribe(Handler, to: [Type])`	`subscribe(Handler.new, to: [Type])` details
`Mappers::NullMapper.new`	`Mappers::Default.new` details
`def apply_order_placed(event)`	`on(OrderPlaced) { ... }` details
`AggregateRoot::Configuration`	`AggregateRoot::Repository.new(event_store)` details
`read.repository.rails_event_store call.dispatcher.rails_event_store`	`read.repository.ruby_event_store call.dispatcher.ruby_event_store` details
`Projection .from_stream("Orders") .when(OrderPlaced, handler) .run(event_store)`	`Projection .init({ count: 0 }) .on(OrderPlaced, &handler) .call(event_store.read.stream("Orders"))` details
`RailsEventStore::Event RailsEventStore::Projection RailsEventStore::InMemoryRepository`	`RubyEventStore::Event RubyEventStore::Projection RubyEventStore::InMemoryRepository` details

Note — removing the aliases doesn’t touch the genuinely Rails-specific classes. RailsEventStore::Client and RailsEventStore::AfterCommitDispatcher aren’t re-exports of anything — they exist only because of Rails (ActiveRecord, transaction callbacks), so they stay. Only the constants that merely pointed at a RubyEventStore:: original are gone.

The one replacement that isn’t a rename is EventClassRemapper — its successor, upcasting, needs a real handler.

EventClassRemapper is gone — use upcasting

In event sourcing, events are immutable facts — once written, a record’s event_type stays as it was, a plain string you never go back and rewrite. By convention that string is the class name, and that’s exactly what a rename breaks: move OrderPlaced into an Ordering module and the events already stored as "OrderPlaced" no longer resolve to Ordering::OrderPlaced on read.

In 2.x you patched this on read with the events_class_remapping: option — a string-to-string lookup:

# 2.x — removed
RubyEventStore::Mappers::Default.new(
  events_class_remapping: { "OrderPlaced" => "Ordering::OrderPlaced" }
)

3.0 replaces it with the upcasting transformation. A Record is immutable, so the upcast lambda receives the old record and returns a brand-new one — for a rename you change only event_type:

# 3.0
upcast = RubyEventStore::Mappers::Transformation::Upcast.new(
  "OrderPlaced" => ->(record) do
    RubyEventStore::Record.new(
      event_type: "Ordering::OrderPlaced",
      data:       record.data,
      event_id:   record.event_id,
      metadata:   record.metadata,
      timestamp:  record.timestamp,
      valid_at:   record.valid_at,
    )
  end
)

mapper = RubyEventStore::Mappers::Pipeline.new(
  upcast,
  RubyEventStore::Mappers::Transformation::SymbolizeMetadataKeys.new,
)

RailsEventStore::Client.new(mapper: mapper)

Starting from a full Record is the whole point: it lets you do far more than rename the type. You can reshape data between versions, split or merge fields, backfill a value that older events never carried — and chain entries so each record is upgraded step by step until it stops changing. That flexibility is what the few extra lines buy you over a one-line hash.

Other removals

A handful of smaller cleanups round out the release, grouped by where they’d reach you — chances are most won’t.

If you subscribe to instrumentation

serialize / deserialize mapper events removed.
They were renamed to event_to_record / record_to_event (payload key domain_event: → event:); update any ActiveSupport::Notifications subscriptions on the old names.
events: / messages: payload keys removed.
The append_to_stream and update_messages notifications now carry only records: — read that key instead.

If you customize mappers or aggregates

JSONMapper removed.
It was a thin Default subclass — Default already handles JSON, so use that instead.
with_default_apply_strategy / with_strategy removed.
The default strategy already comes with include AggregateRoot; for a custom one, use AggregateRoot.with(strategy: …).

Stricter by default

nil to publish / append / link is now rejected.
It used to warn and carry on — now it raises ArgumentError, so guard calls that might pass an empty result.
ensure_supported_any_usage removed.
InMemoryRepository now always rejects mixing expected_version: :any with specific positions — matching the SQL repositories, so in-memory tests catch what production would.

And one warning simply went away — the spurious rails_event_store_active_record rename warning is gone (backstory in the 2.19 post).

Upgrade guide

Start on 2.19 and clear every deprecation warning first — once your test suite is quiet, the table above is your checklist and the rest of the upgrade is mostly find-and-replace. Three changes need a real edit rather than a rename.

Projection API — define the projection once, then call it with any scope:

# before
Projection
  .from_stream("Orders")
  .when(OrderPlaced, handler)
  .run(event_store)

# after
Projection
  .init({ count: 0 })
  .on(OrderPlaced, &handler)
  .call(event_store.read.stream("Orders"))

AggregateRoot default_event_store — the global default is gone; wire the event store explicitly through AggregateRoot::Repository.new(event_store). Details in the 2.19 post.

EventClassRemapper — replace the events_class_remapping: hash with an upcasting transformation on your mapper, as shown in the upcasting section above.

Storing data as a sequence of events - RubyConfAt lightning talk supplement

2026-05-31T13:42:04Z

Storing data as a sequence of events - RubyConfAt lightning talk supplement

This post originated from the lightning talk and the discussions I had afterward at RubyConfAt.

It was a great conference. Especially the music part was amazing. Big kudos and applause to the organizers, once again!

The Lightning Talk

During my lightning talk I discussed an alternative way of storing data in Ruby applications. The alternative way is to store data as a sequence of events.

It all starts with admitting the fact that an update of data causes information loss. We do know what it is now - we see the current state in a database column. But we don’t know how we got there. Context is lost.

Event sourcing solves that problem by storing each change as an event in our database.

What is an event?

An event represents a fact, something that happened in our system. It’s immutable - once persisted, it cannot be changed.

An event consists of a name, event_id, data, and metadata.

An example of an event is ShipmentPacked. This event tells us, well, that a shipment has been packed. No surprise. And that’s also an important aspect. We want event names to be self-explanatory and follow the language that business speaks. Having an event named ShipmentUpdated is not a good event sourcing event name. It’s too vague. It doesn’t tell us what happened in the system.

Common misconception #1 - Immutable is problem

The first common misconception that has to be addressed is this: The fact that the event is immutable doesn’t mean you cannot change data!

Event sourcing draws from the accounting domain in that case. If you make a mistake with the data, you make a correction.

The cool part also comes when you analyze different kinds of mistakes and their consequences.

Consider the following: a developer made a mistake in the code. Ok, so then they write migration script to address it. …Unfortunately they make another mistake.

Oshit.jpg what now?

It’s up to you. You can either start from the beginning (before the first attempt) or continue from the second mistake. All the data is already in place. You do what’s easier. There are patterns to deal with that so you don’t need to reinvent the wheel.

Event Sourcing

I highlighted that during my lightning talk and I’ll do it again here. Better twice than sorry :)

Event sourcing is just another persistence technique.

Instead of storing current state, events are stored. Those events are used to rebuild the state when needed. A decision is made based on the state. Just like with the CRUD approach we’re used to. The difference is state rebuilding.

Common misconception #2 - rebuilding starts from the beginning of the universe

There’s a common misconception that I need to address, though. To rebuild the state you don’t need to load all events since the beginning of the universe. You just read the exact events that you need to make a decision. No more. And this is where streams kick in.

Streams

A stream is a logical representation of a business concept. It gathers all events belonging to that concept.

In the packing example, it’s all about packing a specific shipment, with id 1234. Then the ShipmentPacked event would belong to the Shipment$1234 stream.

Side note: the dollar sign is just stream naming convention. It’s not necessary.

You can think about a stream similarly to an entity represented by an ActiveRecord model. It’s just built differently using so-called projections.

Projections read all events from a specific stream to build the state of an object and make a specific decision.

Another case for streams

Representing a specific business concept is not the only use case for a stream.

In RailsEventStore an event can be linked to multiple streams. You can use this technique to answer interesting business questions.

Let’s look at a specific example.

Imagine you’re organizing a conference in Vienna. You could be interested in the number of tickets sold on a specific day. To achieve that you should link all TicketPurchased events to Tickets_sold_at_${Date.current} stream.

We can go even further. If we had other events representing speaker, talk, agenda, or fun activities announcement, you could link all those events together, build a timeline (or feed an agent), and figure out what has the biggest impact on sales.

Cool, isn’t it?

Common misconception #3 - it’s slow

It must be slow to display data, isn’t it?

No, it is not. And more often it will be even faster than a regular approach. That’s actually what Andrzej mentioned in his talk.

Use events to build read models.

The way we often do it is that we move the pressure from reads to writes. This means that instead of building data for view on the fly (usually causing long-running query for more complex views), we’ll prepare the read model that the user displays upfront, based on specific events.

Common misconception #4 - I need new infra

Luckily, you don’t. In one of previous paragraphs I mentioned RailsEventStore. It is a gem that you can use to implement event sourcing in your current Rails application.

Few facts:

It works with PostgreSQL, MySQL, SQLite
It comes with migrations – it’ll create both events and streams table for you
It comes with predefined template that you can use to plug it into your existing Rails application
It doesn’t require any additional bit of infrastructure

Summary

There are many more aspects of event sourcing that I’d love to discuss in more detail. However, this is a good start. In general, I am very happy that we are starting to talk more about events in the Ruby community and that we allow ourselves to think outside of the Rails Way. I hope that I’ll have a chance to discuss more interesting aspects like anti-patterns, case studies with happy endings that had some stress involved (aka fuckup stories) in upcoming conferences!

But before this happens, I must write one more thing. Event sourcing is a tool that you should have in your toolbox. But it’s not a silver bullet. In my experience, it makes the important parts of an application better in many different ways. However, I do not apply it everywhere, nor do I recommend doing that.

Benefits recap

To recap the benefits I’ve talked about during the lightning talk:

No information is lost. Moreover, the data is richer because there’s additional metadata describing it
It’s auditable
Debugging gets easier. You can see exactly how bits of your data changed, when they changed, by whom, and what caused each change. Super useful when you have business processes that involve multiple steps

Hi, we're Arkency

Ingress is not the owner of the invariant

Ingress is not the owner of the invariant

We agree about the disease

A name that promises more than it delivers

Core: ingress doesn’t own the invariant

What it looks like when an invariant has an owner

And if you don’t want to write it by hand

Where Weaver is right — and what I’m not saying

Landing

Let Your AI Assistant Explore the Event Store with res-mcp

Let Your AI Assistant Explore the Event Store with res-mcp

Setup

Ask questions, not commands

Examples

Why it’s safe to point at any app

Inspect Your Event Store From the Terminal With the res CLI

Inspect Your Event Store From the Terminal With the res CLI

Streams

stream show — a stream at a glance

stream events — read the events

Events

event show — everything about one event

event streams — where an event lives

Search across the store

search — find events anywhere

stats — counts and types

JSON output

Trace correlated events

Watch events live

The full command set

See also

What's New in Rails Event Store 3.0

What’s New in Rails Event Store 3.0

Lean API: the deprecations are gone

EventClassRemapper is gone — use upcasting

Other removals

Upgrade guide

Storing data as a sequence of events - RubyConfAt lightning talk supplement

Storing data as a sequence of events - RubyConfAt lightning talk supplement

The Lightning Talk

What is an event?

Common misconception #1 - Immutable is problem

Event Sourcing

Common misconception #2 - rebuilding starts from the beginning of the universe

Streams

Another case for streams

Common misconception #3 - it’s slow

Common misconception #4 - I need new infra

Summary

Benefits recap

Let Your AI Assistant Explore the Event Store with `res-mcp`

Inspect Your Event Store From the Terminal With the `res` CLI

`stream show` — a stream at a glance

`stream events` — read the events

`event show` — everything about one event

`event streams` — where an event lives

`search` — find events anywhere

`stats` — counts and types