Hi, we're Arkency

RailsEventStore 2.19: Starting Gun for 3.0

2026-05-19T12:56:25Z

RailsEventStore 2.19: Starting Gun for 3.0

RailsEventStore 2.19.1 is out — grab that one, not 2.19.0 (more on why below).

This release is the starting gun for 3.0. We’ve added deprecation warnings for everything we’re removing in the next major version. Run your test suite — every warning you see is a hard error in 3.0.

Deprecations

We’re deprecating a batch of APIs in 2.19 that will be removed in 3.0.

RubyEventStore

`in_batches_of`

Renamed to in_batches for consistency with the rest of the API.

# deprecated
event_store.read.in_batches_of(100).each { |batch| ... }

# use instead
event_store.read.in_batches(100).each { |batch| ... }

`of_types`

Renamed to of_type. Singular, consistent with other query methods.

# deprecated
event_store.read.of_types([OrderPlaced, OrderShipped])

# use instead
event_store.read.of_type([OrderPlaced, OrderShipped])

Projection API

The old API coupled projection definition to the data source upfront — you had to specify the stream when building the projection. The new API separates these concerns: define the projection once, call it with any scope from event_store.read.

# deprecated
Projection
  .from_stream("Order$1")
  .init(-> { 0 })
  .when(OrderPlaced, ->(state, event) { state + 1 })
  .run(event_store)

# use instead
Projection
  .init(-> { 0 })
  .on(OrderPlaced, ->(state, event) { state + 1 })
  .call(event_store.read.stream("Order$1"))

Also deprecated: calling Projection#call with multiple scopes — pass a single scope. Use Projection.init instead of Projection.new.

Class-based subscribers

Passing a class as a subscriber hides the lifecycle — RES had to decide when and how to instantiate it, with no control from the caller. An instance or lambda is explicit about what gets called and when.

# deprecated
event_store.subscribe(SendOrderConfirmation, to: [OrderPlaced])

# use instead
event_store.subscribe(SendOrderConfirmation.new, to: [OrderPlaced])

`EventClassRemapper` / `events_class_remapping:`

Upcasting has been available since RES 2.1.0 and is the proper way to handle renamed or evolved event classes. It’s composable, co-located with the transformation logic, and doesn’t require configuring the mapper globally. EventClassRemapper is being removed.

`NullMapper`

Mappers::Default.new without arguments does exactly what NullMapper did, with a name that doesn’t imply it does nothing.

# deprecated
mapper: RubyEventStore::Mappers::NullMapper.new

# use instead
mapper: RubyEventStore::Mappers::Default.new

RailsEventStore

`RailsEventStore::*` constant aliases

The rails_event_store gem is an integration layer — it wires RES into Rails. The domain objects (events, client, projections) live in ruby_event_store. Aliasing them under the RailsEventStore namespace implied they were Rails-specific, which caused confusion about what’s portable and what isn’t. In 3.0 those aliases are gone — use the source namespace directly.

# deprecated
RailsEventStore::Event
RailsEventStore::JSONClient

# use instead
RubyEventStore::Event
RubyEventStore::JSONClient

`*.rails_event_store` instrumentation events

Same reason as above — the implementation is in ruby_event_store, so the instrumentation namespace should be too. During the 2.19 transition period both *.rails_event_store and *.ruby_event_store are dual-fired. After 3.0 only *.ruby_event_store remains — update your ActiveSupport::Notifications subscriptions.

Dispatcher naming

The Async in ImmediateAsyncDispatcher and AfterCommitAsyncDispatcher described the handler (a background job), not the dispatcher itself. The new names drop the misleading qualifier. Dispatcher becomes SyncScheduler — a more accurate description of what it actually does.

Deprecated	Use instead
`ImmediateAsyncDispatcher`	`ImmediateDispatcher`
`AfterCommitAsyncDispatcher`	`AfterCommitDispatcher`
`Dispatcher`	`SyncScheduler`

AggregateRoot

`apply_*` method convention

The old convention mapped event handlers by method name — apply_order_placed would handle OrderPlaced. The problem, which we even documented at the time: you can’t grep for usages of the event class. The on DSL references the event class explicitly.

# deprecated
class Order
  include AggregateRoot

  def apply_order_placed(event)
    @status = :placed
  end
end

# use instead
class Order
  include AggregateRoot

  on OrderPlaced do |event|
    @status = :placed
  end
end

`AggregateRoot::Configuration` / `default_event_store`

Global state with a hidden dependency on the event store. Makes testing harder, makes the dependency invisible at the call site. Pass the event store explicitly to Repository.new.

# deprecated
AggregateRoot::Configuration.new.tap do |c|
  c.default_event_store = Rails.configuration.event_store
end

# use instead
repository = AggregateRoot::Repository.new(Rails.configuration.event_store)

PostgreSQL `valid_at` index

If you use bi-temporal queries (as_of), add this index.

PostgreSQL can’t use a regular column index for an expression in ORDER BY — it needs a dedicated functional index. Without it, as_of queries fall back to a sequential scan. On a table with ~100k events that’s ~6 seconds. On tables with millions of events, even small result sets take 800ms–1600ms. The mechanics are covered in detail in How to add index to a big table of your Rails app.

New installations get a functional index on COALESCE(valid_at, created_at) automatically. Existing installations:

bin/rails generate rails_event_store_active_record:migration_for_valid_at_index
bin/rails db:migrate

The generator in 2.19.0 used a plain CREATE INDEX — which locks the table for the duration of the build. We caught it and shipped 2.19.1 the next day with algorithm: :concurrently and disable_ddl_transaction!.

PostgreSQL only — MySQL and SQLite use different syntax for expression indexes.

Under the hood

The CI matrix now covers Ruby 4.0, Rails 8.1, Redis 8, PostgreSQL 18, and MySQL 9.7. We’ve dropped EOL versions: Ruby 3.2 (EOL March 2026), old Rails and ActiveRecord versions, PostgreSQL 13, MySQL 8.0.

The test suite previously used multiple per-version dummy Rails apps. We’ve consolidated these into a single app driven by different Gemfiles across the CI matrix.

Mutation coverage gaps have been closed — some after the tag cut.

Upgrading

gem 'rails_event_store', '~> 2.19'

Full release notes: v2.19.0, v2.19.1

The Rails Way in 2026

2026-04-24T10:00:00Z

The Rails Way in 2026

We had an interesting discussion at the Arkency weekly call today. The topic was how to define “the Rails Way” in 2026. The discussion branched in many directions, but I want to capture the result here.

We get to see a lot of Rails repositories. There’s a pattern that shows up so consistently that I think it now deserves to be called “the Rails Way” of 2026:

A fat model with a callback. The callback triggers a service object. The service object is executed as a background job.

That’s the clue of this post. If you zoom out across the Rails applications written or maintained in 2026, that’s the shape.

The disclaimer

A word about where we’re coming from. Arkency is a company that often gets called in to fix existing large Rails applications. We help with performance, we help with improving the velocity, we also introduce domain-driven design and event-driven architecture where it makes sense. So our view is biased - we tend to see the apps that have grown past the point where the default Rails shape still fits.

That bias is also what makes the pattern above so visible to us. We see it again and again.

Processes and workflows inside Active Record

Part of the weekly discussion was specifically about how processes or workflows are implemented in Rails applications nowadays.

The conclusion: they are implemented as part of the existing Active Record.

Active Record is not only the state of an entity. It’s very often the state of a process. Sometimes it’s a shared state, because we’re talking about multiple entities collaborating together via has_many.

If you look at the columns of a typical Active Record table, you can see both kinds of state mixed together. Some columns describe the entity — often as enums:

class Order < ApplicationRecord
  enum status: { pending: 0, confirmed: 1, paid: 2, shipped: 3, delivered: 4, cancelled: 5 }
end

That looks like entity state. But sit with it for a moment - pending → confirmed → paid → shipped → delivered is not really the state of a thing. It’s the state of a process the thing is going through.

And next to these enum columns, you’ll almost always find columns that are openly about the process:

# columns on the same orders table
t.datetime :last_reminder_email_sent_at
t.datetime :payment_retry_scheduled_at
t.integer  :failed_payment_attempts, default: 0
t.datetime :confirmation_email_sent_at

last_reminder_email_sent_at is not a property of the order. It’s a checkpoint in a workflow, “the dunning process has progressed this far.” The same goes for retry counters, “sent_at” timestamps, and “scheduled_at” fields. They’re persisted process state, living on the entity table because there’s nowhere else for them to live.

So the Active Record row ends up being a blend: enum columns that look like entity state but actually track a workflow, plus auxiliary columns that openly admit they’re tracking a process.

A single Active Record class ends up carrying:

the data of the entity (the original purpose),
the current step of a workflow the entity is going through,
callbacks that advance that workflow,
service objects triggered from those callbacks,
background jobs scheduled from those service objects,
and associations to other records that are part of the same process.

The process is not an object. The workflow is not an object. They live as emergent behavior across a model, its callbacks, its associations, and the jobs they enqueue.

This isn’t a new observation. Robert wrote about the same accumulation pattern years ago in Why classes eventually reach 50 columns and hundreds of methods — framed there through bounded contexts. What’s different in 2026 is that the accumulated responsibilities are now explicitly process responsibilities.

One more piece: concerns

There’s one more part of the Rails Way that deserves a mention — concerns.

We don’t see them as often as we see the fat-model-plus-callback-plus-background-job pattern in the codebases we get called into. But concerns are definitely a significant part of the Rails Way too. Maybe they are more of the official Rails Way than the Rails Way we see in the wild.

A good example is the Fizzy codebase from 37signals. We recorded a walkthrough of it on our YouTube channel: Arkency reviews Fizzy, part 1. Fizzy leans on concerns to structure behavior across models. It’s worth watching to see the pattern applied intentionally rather than as accidental accumulation.

So the full picture of the Rails Way in 2026 is probably: fat model, callback, service object, background job, process state living on Active Record and, where teams lean closer to the official Rails style, concerns as the way to organize all of that.

Why this matters

I’m not using this post to argue against the pattern. I’m using it to name it. If we can’t describe what the Rails Way looks like today, we can’t have an honest conversation about when it serves us and when it doesn’t.

So: fat model, callback, service object, background job and processes that live inside Active Record rather than beside it.

That’s the shape of Rails in 2026.

Rails apps have layers but no modules

2026-03-31T11:00:00Z

Rails apps have layers but no modules

You can have 200 models and zero modules. That’s the problem with typical Rails conventions. Rails supports layers - models, views, controllers. But layers are not modules. Within one layer - especially models - usually all is mixed together. There are no boundaries.

Order.first.user.invoices.last.line_items

Such code is not so uncommon. It crosses 4 business boundaries. In just 1 line of code. All thanks to associations.

The problem with associations

One of the first thing we teach in Rails is associations.

class Order < ApplicationRecord
  belongs_to :user
end

It’s very readable, feels right. Allows us to call it like this:

Order.first.user

Then we have the User class:

class User < ApplicationRecord
  has_many :orders
  has_many :invoices
end

and the Invoice class:

class Invoice < ApplicationRecord
  belongs_to :order
  has_many   :line_items
end

and this is how we allow the original code:

Order.first.user.invoices.last.line_items

This is how we boil the frog. One step at a time. One column at a time. One association at a time. The result? A User class with 100 columns in the database.

DRY and god models

There is a misconception about DRY - Don’t Repeat Yourself. We have an existing User class. It feels right to just add things there. No one was ever fired for adding a new column to the users table. It feels like the User class is the right abstraction for DRY. Yet, it always ends as the god model.

Service Objects don’t help with modularisation

Many Rails teams believe that Service Objects are the solution. They are, but to a different problem.

Service objects help us when our controllers become too big. They are called from the controllers and they are the ones orchestrating ActiveRecord models. Often they handle transactions too.

What is good about them? They are creating a boundary between the HTTP layer (controllers) and the domain layer. They also are a good solution to the transaction boundary.

Service objects are a new layer. We could now call it MVCS. Model View Controller Service. It’s not bad. It does help with unit testing - it’s easier to unit test a service object than a controller action.

Service objects do nothing about modularisation. They don’t create new boundaries. They don’t help with composing modules. Service objects are just another horizontal slice.

Microservices

It’s usually around this phase in the architecture - MVCS - when a decision is made. We will go microservices.

Sometimes it comes from the team itself - what can be a stronger boundary than a network? The team hopes it will enforce a better design. Microservices bring the hope of starting fresh — new language, new design, better boundaries. But the boundaries still aren’t modules.

Are microservices helping with the modularisation? Nope. They are just yet another horizontal layer. This time we add a layer behind a network call. We no longer have transactions, it’s harder to run tests, the build takes longer. All for the benefit of having 3 new Go microservices and adding new layers of serialisation/deserialisation. More layers, less performance, but still no modules.

A bitter conclusion

Rails makes it easy to add code. It doesn’t make it easy to isolate it. 200 models. Five layers. Zero modules. That’s the default.

In 1972, Parnas wrote that a module hides a design decision from the rest of the system. Fifty years later, Rails apps hide nothing. What does your User class hide?

Getting nondeterministic agent into deterministic guardrails

2026-02-20T11:20:24Z

Getting nondeterministic agent into deterministic guardrails

AI agents don’t reliably follow your instructions. Here’s how I made it hurt less.

My context:

I currently work on a 12-year-old Rails legacy code base
The code base is undergoing modernization. Some of the large Active Record classes have been split into smaller ones, each into its own bounded context. Events are becoming a first-class citizens in the code. We also pay close attention to keep direction of dependencies as designed by context maps.
The client has a GitHub Copilot subscription. I mostly use Sonnet and Opus models.

The basic setup

Initially I started with the basics. I was curious where it would get us. There’s an AGENTS.md file with general rules to follow. Besides the AGENTS.md file I’ve added a few skills. The goal of the skills is to tell the agent about how it should write code. I am a big fan of Szymon’s way of using RSpec. So I put that into a skill. I also developed a few skills that tell the agent how I want it to deal with event sourcing, ddd technical patterns, hotwire, backfilling data (especially events) and mutation testing. The mutation skill is quite essential because without it the agent goes bananas and tries to achieve 100% of mutation coverage with hacking.

An example of hacking is calling send(:method).

I don’t want to have such tests. Trying to achieve mutation coverage in such a way indicates that perhaps the code should be removed because it’s just unnecessary noise.

So now the question is, is that enough?

It’s pretty good but can be better – tackling non-determinism

More than once (a day) I’ve experienced my agent to go off-rails and ignore my instructions. It doesn’t respect what I’ve specified in AGENTS.md and/or skills.

It often happens when I am asking it to introduce a very similar-yet-a-little-bit-different command and handler for a specific business use case.

Changes to the production code are going very well. This is especially true if the goal is to replicate well-structured code. However, once it gets to the “write the tests” part, it switches to commodity mode and most likely uses RSpec in the most popular way, which I don’t like. This is a large part of the existing codebase. If it doesn’t fail on writing tests the way I want it, it usually doesn’t run mutation testing, even though I expect the coverage not to drop below a certain point and the mutants to be eliminated. They should be killed properly. Using the send method is no bueno.

Dealing with non-determinism

So we’re not able to change whether the agent will respect AGENTS.md and skills all the time. At least not yet. Maybe never. So we have to deal with it differently.

What I am currently testing is to have guardrails aka dev workflows. The idea is to run tools that:

Will make me focus less on code structure, incorrect formatting, etc
Make sure tests for changed files are run
Make sure mutation tests are run
And, last but not least, make sure that the boundaries within bounded contexts are not violated. I noticed that the agent, just like humans, loves to take shortcuts to achieve a goal. The difference is that I never tell the agent we’re under a strict deadline. So I’m not sure where this choice is coming from.

The workflow is Ruby code that is wired to a /verify custom command. The command runs bash with ruby -r ./lib/dev_workflow.rb.

The dev_workflow.rb orchestrates the full pipeline. Looking at its requires tells you everything about what it runs:

require_relative 'dev_workflow/step_result'
require_relative 'dev_workflow/result'
require_relative 'dev_workflow/changed_files'
require_relative 'dev_workflow/steps/base'
require_relative 'dev_workflow/steps/rubocop_step'
require_relative 'dev_workflow/steps/rspec_step'
require_relative 'dev_workflow/steps/mutant_step'
require_relative 'dev_workflow/steps/eslint_step'
require_relative 'dev_workflow/steps/jest_step'
require_relative 'dev_workflow/verify_build'

Each step follows the same pattern: check if relevant files changed, run the tool, return a structured result. Here’s the mutation testing step as an example — the one that matters most given the problems I described earlier:

class MutantStep < Base
  ALLOWED_NAMESPACES = %w[CRM Ordering Billing].freeze

  def call
    unless changed_files.any_ruby?
      return StepResult.skipped(name: name, skip_reason: 'no ruby files changed')
    end

    subjects = mutation_subjects
    if subjects.empty?
      return StepResult.skipped(name: name, skip_reason: 'no mutant-eligible files changed')
    end

    result, duration = measure_duration do
      run_mutant(subjects)
    end

    output, success = result

    if success
      StepResult.success(name: name, duration_seconds: duration, files_checked: subjects.size)
    else
      errors = parse_mutant_output(output)
      StepResult.failure(name: name, duration_seconds: duration, files_checked: subjects.size, errors: errors)
    end
  end

  private

  def run_mutant(subjects)
    subject_args = subjects.map { |s| "'#{s}'" }.join(' ')
    run_command("bundle exec mutant run --since HEAD #{subject_args}")
  end

  def mutation_subjects
    changed_files.ruby_files
      .reject { |f| f.start_with?('spec/') }
      .filter_map { |f| file_to_subject(f) }
      .select { |subject| eligible_namespace?(subject) }
      .uniq
  end
end

The key detail is StepResult. Each step returns either .skipped, .success, or .failure with structured data. This is what the agent reads to understand what went wrong and what to fix.

Last but not least, to make sure that the non-deterministic agent won’t ignore my desire to run this command by itself, I attached it to a git pre-commit hook:

#!/usr/bin/env ruby

require_relative "../lib/dev_workflow"

result = DevWorkflow::VerifyBuild.call(staged_only: true)

puts result.to_json

exit(result.success? ? 0 : 1)

And at this point, at least calling the verify method is deterministic. So the agent gets feedback, fixes whatever is reported by the tool, reruns the verification and then it’s able to commit the changes.

Reviewing changes

Besides AGENTS.md, SKILLS.md and the workflow I described above, I still review the code. I focus on tests, architecture and security parts. I do take full ownership of the code that I ship. I don’t trust the AI enough to cut the leash. And my conclusion from working with it in a legacy codebase is currently that it will not change that fast (for me).

The timezone bug that hid in plain sight for months

2026-02-05T12:02:35Z

The timezone bug that hid in plain sight for months

We recently fixed a bug in a financial platform’s data sync that had been silently causing inconsistencies for months. The bug was elegant in its simplicity: checking DST status for “now” when converting historical dates.

The broken code

I found this while debugging a different sync issue — the real bug turned out to be hiding in a helper method I wasn’t even looking at.

def self.date_to_utc(value, timezone_key)
  offset = Time.now.in_time_zone(TIMEZONE_MAP.fetch(timezone_key)).formatted_offset
  Time.new(*value.to_s.split('-').map(&:to_i), 0, 0, 0, offset).utc
end

Looks reasonable, right? Get the timezone offset, create a Time object, convert to UTC.

The problem: Time.now.in_time_zone().formatted_offset gets the offset for right now, then applies it to any date being converted.

Why this breaks

Run this in December (EST, UTC-5):

date_to_utc(Date.new(2023, 6, 20), :eastern)
# Gets -05:00 offset, but June 20 should be EDT (-04:00)
# Result: off by one hour

Run the same code in June (EDT, UTC-4):

date_to_utc(Date.new(2023, 6, 20), :eastern)
# Gets -04:00 offset, correct for June
# Result: works fine

Same input, different output depending on when you run it. Your tests pass in summer, fail in winter. Data syncs would occasionally miss records or pull wrong date ranges, depending on DST periods.

The fix

def self.date_to_utc(value, timezone_key)
  tz = ActiveSupport::TimeZone[TIMEZONE_MAP.fetch(timezone_key)]
  tz.local(value.year, value.month, value.day, 0, 0, 0).utc
end

ActiveSupport::TimeZone#local handles DST correctly for the specific date being converted. June dates always get EDT, January dates always get EST, regardless of when the code runs.

The test that exposed it

Before touching the implementation, I wrote a test to confirm my suspicion — and it failed immediately.

it 'produces consistent results regardless of system timezone' do
  date = Date.new(2023, 6, 20)
  expected = Time.new(2023, 6, 20, 4, 0, 0, 'UTC')

  %w[UTC Asia/Tokyo America/Los_Angeles].each do |tz|
    Time.use_zone(tz) do
      expect(described_class.date_to_utc(date, :eastern)).to eq(expected)
    end
  end
end

This test runs the same conversion in UTC, Tokyo, and LA timezones. The old implementation would produce different results depending on system timezone and time of year.

Impact

We caught this before it caused visible production issues, but the potential impact for a financial data integration was significant: off-by-one-hour shifts during DST transitions could cause missed records in date-range queries and validation mismatches between systems.

Lessons

Never use Time.now for calculations on other dates. If you need timezone info for a specific date, use that date.
Test with explicit timezone manipulation. Don’t rely on your system’s timezone matching production.
DST transitions are sneaky. A bug that manifests only during certain months can survive code review and testing.
Know your tools: ActiveSupport::TimeZone

Hi, we're Arkency

RailsEventStore 2.19: Starting Gun for 3.0

RailsEventStore 2.19: Starting Gun for 3.0

Deprecations

RubyEventStore

in_batches_of

of_types

Projection API

Class-based subscribers

EventClassRemapper / events_class_remapping:

NullMapper

RailsEventStore

RailsEventStore::* constant aliases

*.rails_event_store instrumentation events

Dispatcher naming

AggregateRoot

apply_* method convention

AggregateRoot::Configuration / default_event_store

PostgreSQL valid_at index

Under the hood

Upgrading

The Rails Way in 2026

The Rails Way in 2026

The disclaimer

Processes and workflows inside Active Record

One more piece: concerns

Why this matters

Rails apps have layers but no modules

Rails apps have layers but no modules

The problem with associations

DRY and god models

Service Objects don’t help with modularisation

Microservices

A bitter conclusion

Getting nondeterministic agent into deterministic guardrails

Getting nondeterministic agent into deterministic guardrails

The basic setup

It’s pretty good but can be better – tackling non-determinism

Dealing with non-determinism

Reviewing changes

The timezone bug that hid in plain sight for months

The timezone bug that hid in plain sight for months

The broken code

Why this breaks

The fix

The test that exposed it

Impact

Lessons

`in_batches_of`

`of_types`

`EventClassRemapper` / `events_class_remapping:`

`NullMapper`

`RailsEventStore::*` constant aliases

`*.rails_event_store` instrumentation events

`apply_*` method convention

`AggregateRoot::Configuration` / `default_event_store`

PostgreSQL `valid_at` index