acta 0.3.0 → 0.4.0.alpha.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c2218e4d40ef364d3dba8452e489a06f3e6d0503726e4d95660f7637e00efdc
-  data.tar.gz: a3602d1b12e575f44f3f0bf4acdad256d5bd25a9ede5f43688f869015b96abe8
+  metadata.gz: 0af752d227a9c1f376f4e1201bd2ba2b60faf5d178a1db06975d8bdaec0c66ef
+  data.tar.gz: 417ec6f02d8348355bccf44d0682a534d8e3dc5f7a9d6364b5a3d31326e04e76
 SHA512:
-  metadata.gz: ac176442ad27e359358e7f59f585facf1ee2dc6c11902737e9da2e1f7b7b354d14ce40aed1bd80e9e4ad12a04f2f5f8d0b9d548c9077fdc58c0debf0f755ac66
-  data.tar.gz: 5de77801dd8088ae0f3699dae67388db5db0688f3de840c31938073ef5bd57f843f543b2c8584633a4a637cdf41a6f359bec65c9d59c5622228fc80783dba691
+  metadata.gz: 112a12b4dac2b676183237c2d73df829d9d0f6e3e4519be94fb25844d1dce7cd890a8de8a758d0e469b6eaf5b2454cf5c033e139a22785e82ae0b158396148fb
+  data.tar.gz: 4ca8da1823ee930a0a3ebdc3b70d47b108d53e7e05c2328ce58976fc09fa65d9eb256520fdf376cd5da03099f70bd9b02858e7ccd32e429b62ca62939d802aa5

data/CHANGELOG.md

@@ -10,6 +10,78 @@ breaking changes as the API settles through real-world consumer integration.
 
 ## [Unreleased]
 
+## [0.4.0.alpha.1] — 2026-05-22
+
+Prerelease intended for Scaff dogfooding against real prod tenant
+data ahead of the Workspaces schema migration. Promote to `0.4.0`
+once integration is green.
+
+### Added
+
+- `Acta::Upcaster` — replay-time event transformation for apps whose
+  schemas evolve. Apps declare `upcasts(event_type, from:, to:) { ... }`
+  blocks on a module that `include Acta::Upcaster`, register it with
+  `Acta.register_upcaster(Klass)`, and bump the relevant
+  `Acta::Event.event_version`. On every read path
+  (`Acta.rebuild!`, `ReactorJob#perform`, the events admin, test
+  fixtures) the pipeline walks records pre-hydration through any
+  matching upcasters, so projections see the latest shape without
+  the stored rows ever being mutated.
+- Supported transform shapes: 1-to-1 chaining across N versions,
+  1-to-many fan-out (each branch chains independently),
+  drop-on-replay (`nil` / `[]`), explicit `context.fail_replay!`,
+  and `Acta::Upcaster::NO_OP` as a terminal pass-through. Stateful
+  transforms read/write a per-replay `Acta::Upcaster::Context`.
+- `Acta::EventsQuery#all` / `#each` now iterate the scope through
+  the upcaster pipeline with a single shared `Context` across the
+  full pass, matching `Acta.rebuild!` semantics. Single-record
+  lookups (`find_by_uuid`, `first`, `last`) deliberately use a
+  fresh context — there's no prior history to seed it with — and
+  may produce incomplete output for stateful upcasters. The web
+  admin shows raw stored rows, sidestepping the question.
+  `docs/upcasters.md` carries the read-surface table.
+- `Acta::ReplayHaltedByUpcaster`, `Acta::UpcasterRegistryError`,
+  `Acta::FutureSchemaVersion` for the corresponding failure modes.
+- Testing helpers `Acta::Testing::DSL#acta_seed_event` (insert a
+  row at an arbitrary `event_version`, bypassing `Acta.emit`) and
+  `#acta_replay(events:, upcasters:)` (seed + register + rebuild
+  in one call).
+- `docs/upcasters.md` cookbook entry covering renames, fan-outs,
+  drops, stateful context, the mid-deploy reactor edge case, and
+  test patterns.
+
+No schema migration: the existing `event_version` column carries
+upcaster fence semantics. Apps without upcasters see no behavior
+change — the pipeline is a one-method-call identity pass.
+
+## [0.3.2] — 2026-05-11
+
+### Added
+
+- `Acta.set_events_record_parent!(klass)` lets a host re-parent
+  `Acta::EventsRecord` (and therefore `Acta::Record`) onto a
+  custom abstract base. The use case is per-tenant SQLite
+  sharding: when the host's tenant-scoped abstract class and
+  `Acta::EventsRecord` are independent, Rails 8 multi-DB gives
+  them separate connection pools, which trips SQLite write
+  contention on cross-pool transactions to the same file. Sharing
+  the pool by sharing the parent class fixes this.
+  Backwards-compatible — apps that don't call the new method
+  see no change.
+
+## [0.3.1] — 2026-05-11
+
+### Added
+
+- `Acta::EventsRecord` abstract base. `Acta::Record` now inherits
+  from it so hosts can call `connects_to` (database/role or shards)
+  on `Acta::EventsRecord` to route the events table to a specific
+  connection. Calling `connects_to` directly on `Acta::Record` was
+  rejected by ActiveRecord because the class is concrete (has
+  `table_name = "events"` set); the abstract intermediate is the
+  idiomatic Rails seam. Backwards-compatible — existing apps that
+  don't reopen `EventsRecord` see no change.
+
 ## [0.3.0] — 2026-04-28
 
 ### Added

data/README.md

@@ -21,6 +21,7 @@ What the library ships:
 | `Acta::Projection` | Sync + transactional + replayable (for ES aggregates) |
 | `Acta::Reactor` | After-commit + async via ActiveJob (for side effects) |
 | `Acta::Command` | Recommended write path with param validation & optimistic concurrency |
+| `Acta::Upcaster` | Replay-time transforms for events whose shape changed between schema versions |
 | `Acta::Testing` | RSpec matchers, given-when-then DSL, replay-determinism assertions |
 
 Adapters: SQLite and Postgres, both first-class.

data/docs/README.md

@@ -12,6 +12,11 @@ end-to-end code and the trade-offs that come with each choice.
   subscribers, no event sourcing. AR records remain the source of
   truth; the events table is a free audit log. Compares against AR
   callbacks and `ActiveSupport::Notifications`.
+- [**Schema evolution with upcasters**](upcasters.md) — transform
+  old-shape events into the current shape at replay time so
+  `Acta.rebuild!` stays faithful across migrations. Covers renames,
+  fan-outs, drops, stateful context, and the mid-deploy reactor
+  edge case.
 
 ## Patterns coming later
 
@@ -25,7 +30,3 @@ Recipes will land here when these are written or implemented:
 - **Process managers (saga)** — coordinating multi-step workflows
   where one event triggers a wait-then-act sequence. Primitive
   tracked in [#27](https://github.com/whoojemaflip/acta/issues/27).
-- **Schema evolution with upcasters** — adding, renaming, or
-  retiring event attributes without leaving stale rows
-  un-deserializable. Primitive tracked in
-  [#25](https://github.com/whoojemaflip/acta/issues/25).

data/docs/upcasters.md

@@ -0,0 +1,303 @@
+# Schema evolution with upcasters
+
+Acta records are immutable: once an event lands in the events table,
+nothing edits it. That's the property the audit log relies on. But
+app schemas evolve — a new attribute appears, a semantic shifts, an
+event type gets renamed. The straightforward options are unappealing:
+
+- **Mutate history** — rewrite the events table. Breaks immutability
+  and any external consumer of the log.
+- **Snapshot the boundary** — preserve projections at the cut and
+  declare replay-from-zero unsupported. Loses event sourcing's core
+  promise.
+- **Accept that replay-from-zero is broken** — keep emitting new
+  shapes but admit `Acta.rebuild!` can't produce the current
+  projection from scratch. Corrosive over time.
+
+**Upcasters** are the standard event-sourcing answer: at replay
+time, transform old-shape records into new-shape records in memory,
+before projections see them. The stored rows are never touched. The
+transformation logic lives in code, where it's tested and audited.
+
+## When to reach for an upcaster
+
+- You renamed an event type (`ItemCreated` → `WorkspaceCreated`) and
+  want old records to apply to the new projection.
+- You added a required field to an event class and old records lack
+  it; you can derive a default at replay time.
+- You're dropping an obsolete event type and want pre-deprecation
+  records to be skipped on replay.
+- You're splitting one logical event into several finer-grained ones
+  (a 1-to-many fan-out at replay).
+
+If your schema change is purely additive *and* every site that reads
+the field tolerates `nil`, you can probably skip upcasters: bump the
+event class to add the attribute, leave `event_version` alone, and
+projections cope with missing-field cases inline. Reach for an
+upcaster when "tolerate missing field" turns into more conditional
+logic than the transform would be.
+
+## The shape of an upcaster
+
+```ruby
+# app/upcasters/workspace_migration_upcasters.rb
+module WorkspaceMigrationUpcasters
+  include Acta::Upcaster
+
+  upcasts "ItemCreated", from: 1, to: 2 do |event, context|
+    payload = event.payload
+
+    if payload["item_type"] == "goal"
+      # A v1 goal becomes a v2 workspace. Record the mapping so
+      # descendant items can resolve their workspace_id below.
+      context[:goal_to_workspace][payload["item_id"]] = payload["item_id"]
+
+      event.upcast_to(
+        type: "WorkspaceCreated",
+        payload: {
+          "workspace_id" => payload["item_id"],
+          "title"        => payload["title"]
+        },
+        schema_version: 2
+      )
+    else
+      workspace_id =
+        context[:goal_to_workspace][payload["parent_id"]] ||
+        context[:item_to_workspace][payload["parent_id"]]
+
+      if workspace_id.nil?
+        context.fail_replay!(
+          "Unmappable item #{payload['item_id']}: no goal ancestor"
+        )
+      end
+
+      context[:item_to_workspace][payload["item_id"]] = workspace_id
+
+      event.upcast_to(
+        payload: payload.merge("workspace_id" => workspace_id),
+        schema_version: 2
+      )
+    end
+  end
+end
+```
+
+Register it once at boot:
+
+```ruby
+# config/initializers/acta_upcasters.rb
+Acta.register_upcaster(WorkspaceMigrationUpcasters)
+```
+
+Then bump the new emit path so freshly emitted events carry
+`event_version: 2`:
+
+```ruby
+class ItemCreated < Acta::Event
+  def self.event_version = 2
+  attribute :item_id,      :string
+  attribute :workspace_id, :string
+  # ...
+end
+```
+
+That's the whole feature surface. New writes are at v2; old reads
+get upcasted to v2 before they hit projections.
+
+## What blocks can return
+
+Inside an `upcasts` block, the return value controls what the
+pipeline does next:
+
+| Return value                          | Effect                                           |
+| ------------------------------------- | ------------------------------------------------ |
+| `event.upcast_to(...)`                | Continue chaining at the new (type, version)     |
+| Array of `event.upcast_to(...)`       | Fan-out: each branch chains independently        |
+| `nil` or `[]`                         | Drop the record from this replay                 |
+| `context.fail_replay!("reason")`      | Halt with `Acta::ReplayHaltedByUpcaster`         |
+
+If you need to leave a record alone at the current version — e.g. a
+boundary-marker event that's already in its final shape — use the
+NO_OP sentinel:
+
+```ruby
+upcasts "GoalPromotedToWorkspace", from: 2, to: 2, &Acta::Upcaster::NO_OP
+```
+
+## Stateless vs stateful upcasters
+
+Upcasters come in two flavors and the distinction matters for which
+read surfaces will produce correct output.
+
+**Stateless** — the transform depends only on the record itself.
+Adding a default for a new field, renaming a key in the payload,
+or unconditionally bumping the event type all qualify. The
+`context` argument is ignored.
+
+```ruby
+upcasts "ItemCreated", from: 1, to: 2 do |event, _ctx|
+  event.upcast_to(
+    payload: event.payload.merge("workspace_id" => "default"),
+    schema_version: 2
+  )
+end
+```
+
+**Stateful** — the transform depends on context populated by an
+earlier event in the same replay. Resolving a descendant's
+`workspace_id` from a goal seen earlier in the stream is the
+canonical example.
+
+```ruby
+upcasts "ItemCreated", from: 1, to: 2 do |event, ctx|
+  payload = event.payload
+  if payload["item_type"] == "goal"
+    ctx[:goal_to_workspace][payload["item_id"]] = payload["item_id"]
+    event.upcast_to(type: "WorkspaceCreated", ...)
+  else
+    workspace_id = ctx[:goal_to_workspace][payload["parent_id"]]
+    event.upcast_to(payload: payload.merge("workspace_id" => workspace_id), schema_version: 2)
+  end
+end
+```
+
+Stateful upcasters require **global insertion order**, which is
+exactly what `Acta.rebuild!` (and `Acta.events.all` / `#each`)
+provides. They will silently produce incomplete output on read
+surfaces that can't supply that order — see the next section.
+
+## Context semantics across read surfaces
+
+Different read paths give upcasters different views of the world.
+Stateless upcasters are unaffected by any of this; stateful
+upcasters need to know.
+
+| Read surface                          | Context lifetime                 | Safe for stateful upcasters? |
+| ------------------------------------- | -------------------------------- | ---------------------------- |
+| `Acta.rebuild!`                       | One shared, full insertion order | Yes                          |
+| `Acta.events.all` / `#each`           | One shared, full insertion order | Yes                          |
+| `Acta.events.find_by_uuid(uuid)`      | Fresh per call                   | No — incomplete resolution   |
+| `Acta.events.first` / `.last`         | Fresh per call                   | No — incomplete resolution   |
+| `Acta.events.for_stream(...)#all`     | Shared, but stream-ordered       | Usually no — wrong order     |
+| `Acta::ReactorJob#perform`            | Fresh, single record             | No — incomplete resolution   |
+| Web admin (`Acta::Web::EventsController`) | N/A — shows raw stored rows  | N/A                          |
+
+The pattern: any time you hand the pipeline a full ordered stream,
+stateful upcasters work. Any time you hand it one record (or a
+stream-reordered subset), they can't reconstruct the state they
+need.
+
+### Implication for stateful migrations
+
+A stateful migration is fundamentally a `rebuild!`-shaped operation.
+The cutover playbook is:
+
+1. Deploy code that emits at the new `event_version` and includes
+   the upcasters.
+2. Drain the reactor queue. Jobs enqueued before the deploy will
+   re-hydrate their events through the upcaster pipeline with a
+   fresh context — fine for stateless upcasters, possibly
+   incomplete for stateful ones.
+3. Run `Acta.rebuild!` to regenerate projections from the full
+   ordered log under the new schema.
+4. Flip reads.
+
+Apps that need stateful read-time resolution outside `rebuild!`
+should consider whether the resolved field belongs in the
+projection rather than in the upcaster — projections are the
+durable, queryable view, and once `rebuild!` has run, projections
+hold the post-upcast state without needing the pipeline at read
+time.
+
+## Chaining across N versions
+
+Upcasters can be declared on a single event type across many
+versions; the pipeline walks them in order:
+
+```ruby
+module SuccessiveBumps
+  include Acta::Upcaster
+
+  upcasts "ItemCreated", from: 1, to: 2 do |e, _|
+    e.upcast_to(payload: e.payload.merge("workspace_id" => "?"), schema_version: 2)
+  end
+
+  upcasts "ItemCreated", from: 2, to: 3 do |e, _|
+    e.upcast_to(payload: e.payload.except("legacy_kind"), schema_version: 3)
+  end
+end
+```
+
+A v1 record passes through both transforms in sequence. A v2 record
+(emitted between the two migrations) picks up the second transform
+only. Events emitted by current v3 code pass through identity.
+
+## Testing upcasters
+
+Two helpers live in `Acta::Testing::DSL`:
+
+- `acta_seed_event(type:, payload:, event_version: 1, ...)` —
+  inserts an event row directly, bypassing `Acta.emit` (which always
+  stamps the *current* code's `event_version`).
+- `acta_replay(events:, upcasters: [])` — registers the supplied
+  upcasters, seeds events, and runs `Acta.rebuild!`.
+
+```ruby
+RSpec.describe "Workspaces migration" do
+  include Acta::Testing::DSL
+
+  it "promotes goals to workspaces and rewires descendants" do
+    acta_replay(
+      upcasters: [ WorkspaceMigrationUpcasters ],
+      events: [
+        { type: "ItemCreated", event_version: 1,
+          payload: { "item_id" => "g_1", "item_type" => "goal", "title" => "Q3" } },
+        { type: "ItemCreated", event_version: 1,
+          payload: { "item_id" => "i_2", "parent_id" => "g_1", "title" => "Plan" } }
+      ]
+    )
+
+    expect(Workspace.pluck(:id)).to eq([ "g_1" ])
+    expect(Item.find("i_2").workspace_id).to eq("g_1")
+  end
+end
+```
+
+The existing `ensure_replay_deterministic` matcher implicitly
+exercises the upcaster pipeline twice — impure upcasters (state
+leaking outside the per-replay context) surface as a snapshot diff
+on the second pass.
+
+## What upcasters intentionally do *not* do
+
+- **They don't rewrite the event store.** Stored rows are immutable;
+  transforms exist only in memory during a replay pass.
+- **They don't run on the live emit path.** `Acta.emit` stamps the
+  current code's `event_version` and dispatches the in-memory event
+  directly — no read round-trip, no upcaster pass. Live writes are
+  always at the latest version.
+- **They're not a migration framework.** The decision to bump
+  `event_version` and write an upcaster is the schema migration. The
+  upcaster's job is just replay correctness.
+- **They're not cross-tenant.** Each tenant's events table replays
+  independently; upcaster context is per-replay-pass, per-tenant.
+
+## Edge cases worth knowing about
+
+- **Future-version records.** If a replay sees an event whose stored
+  `event_version` exceeds the highest `to` any registered upcaster
+  knows how to reach for that type, the pipeline raises
+  `Acta::FutureSchemaVersion`. Typically: an older deployment is
+  replaying events emitted by a newer one. Halting is the safe call.
+- **Type renames remove the need to keep old classes around.**
+  Upcasters operate on raw records pre-hydration, so the original
+  `ItemCreated` constant can be deleted from the codebase the moment
+  its upcaster renames the type. Hydration only ever happens for
+  classes the upcaster pipeline produces.
+- **1-to-many composes with chaining.** Each record an upcaster
+  fans out into walks the version ladder independently — including
+  through more 1-to-many transforms if you have them.
+- **Conflicting registrations raise at boot.** Two upcaster classes
+  that claim the same `(event_type, from)` pair surface as
+  `Acta::UpcasterRegistryError` the moment the second one registers.
+  Pick an owner.

data/lib/acta/errors.rb

@@ -99,4 +99,42 @@ module Acta
       )
     end
   end
+
+  # Raised by `context.fail_replay!(reason)` inside an upcaster block. Halts
+  # replay so the operator can investigate rather than land a partial,
+  # possibly-corrupt projection.
+  class ReplayHaltedByUpcaster < Error
+    attr_reader :record, :reason
+
+    def initialize(record:, reason:)
+      @record = record
+      @reason = reason
+      super(
+        "Upcaster halted replay on event id=#{record.id} uuid=#{record.uuid} " \
+        "(#{record.event_type} v#{record.event_version}): #{reason}"
+      )
+    end
+  end
+
+  # Raised at registration time when an upcaster set is malformed — e.g.
+  # `from` >= `to`, or two upcasters claim the same (event_type, from).
+  class UpcasterRegistryError < Error; end
+
+  # Raised when a record's stored event_version exceeds anything the
+  # currently-loaded upcaster registry knows how to reach. Typically means
+  # an older deployment is replaying events emitted by a newer one.
+  class FutureSchemaVersion < Error
+    attr_reader :record, :latest_known_version
+
+    def initialize(record:, latest_known_version:)
+      @record = record
+      @latest_known_version = latest_known_version
+      super(
+        "Event id=#{record.id} uuid=#{record.uuid} (#{record.event_type}) is at " \
+        "event_version #{record.event_version}, but the loaded upcaster registry " \
+        "only knows up to v#{latest_known_version}. Likely an older deployment " \
+        "replaying events emitted by a newer one."
+      )
+    end
+  end
 end

data/lib/acta/events_query.rb

@@ -7,19 +7,27 @@ module Acta
     end
 
     def last
-      hydrate(@scope.last)
+      upcast_and_hydrate_one(@scope.last)
     end
 
     def first
-      hydrate(@scope.first)
+      upcast_and_hydrate_one(@scope.first)
     end
 
     def find_by_uuid(uuid)
-      hydrate(@scope.find_by(uuid:))
+      upcast_and_hydrate_one(@scope.find_by(uuid:))
     end
 
+    # Iterates the full scope through the upcaster pipeline with a SINGLE
+    # shared context across every record, matching `Acta.rebuild!` semantics.
+    # Stateful upcasters (those that resolve later events from state seeded
+    # by earlier ones) depend on this. Single-record lookups
+    # (`find_by_uuid`, `first`, `last`) deliberately use a fresh context —
+    # there is no prior history to seed it with — and may produce
+    # incomplete output for stateful upcasters. See `docs/upcasters.md`.
     def all
-      @scope.map { |record| hydrate(record) }
+      context = Upcaster::Context.new
+      @scope.flat_map { |record| upcast_and_hydrate(record, context) }
     end
 
     def count
@@ -39,8 +47,47 @@ module Acta
       self.class.new(filtered)
     end
 
+    # Run a single record through the upcaster pipeline and hydrate every
+    # output into a typed Acta::Event. Returns an Array (length 0..N) —
+    # callers that expect one event (the historic shape) should use the
+    # find_by_uuid/first/last helpers above, which apply a fresh context
+    # per call and unwrap to a single event (raising if upcasters drop or
+    # fan out, since those shapes aren't meaningful for one-record reads).
+    #
+    # Acta.rebuild! supplies a single shared context for the full pass.
+    def upcast_and_hydrate(record, context)
+      Upcaster.upcast(record, context).map { |view| hydrate(view) }
+    end
+
     private
 
+    # Single-record helper used by the public lookup methods. Drop and
+    # fan-out are rejected here — `find_by_uuid(x)` returning either nil
+    # (when an upcaster dropped) or an array (when it fanned out) would
+    # silently break every existing caller. Live emit and tests reach for
+    # this surface assuming one record → one event.
+    def upcast_and_hydrate_one(record)
+      return nil unless record
+
+      results = upcast_and_hydrate(record, fresh_context)
+
+      case results.length
+      when 0
+        nil
+      when 1
+        results.first
+      else
+        raise UpcasterRegistryError,
+              "Upcaster fan-out (#{results.length} events) is not supported on " \
+              "single-record reads of #{record.event_type} uuid=#{record.uuid}; " \
+              "use Acta.rebuild! or EventsQuery#each, which iterate the pipeline."
+      end
+    end
+
+    def fresh_context
+      Upcaster::Context.new
+    end
+
     def hydrate(record)
       return nil unless record
 

data/lib/acta/record.rb

@@ -3,8 +3,56 @@
 require "active_record"
 
 module Acta
-  class Record < ActiveRecord::Base
+  # Abstract intermediate. The actual events table lives on `Acta::Record`
+  # below; this class exists so hosts can call `connects_to` (which
+  # ActiveRecord rejects on concrete classes that have `table_name` set).
+  #
+  # Default behaviour: inherits from ActiveRecord::Base, no shard or
+  # connection routing — Acta::Record uses whatever the host's default
+  # connection is.
+  #
+  # Hosts that need the events table to *share a connection pool* with
+  # their own tenant-scoped abstract base (so writes inside a single
+  # transaction don't fight across pools on the same SQLite file)
+  # re-parent EventsRecord via `Acta.set_events_record_parent!`:
+  #
+  #     # config/initializers/_acta_record_parent.rb
+  #     class TenantRecord < ActiveRecord::Base
+  #       self.abstract_class = true
+  #     end
+  #     Acta.set_events_record_parent!(TenantRecord)
+  #     # then call connects_to on TenantRecord — Acta::Record rides along
+  #
+  # Acta::Record inherits from EventsRecord so any routing applied to
+  # EventsRecord (or to a re-parented ancestor) automatically applies.
+  class EventsRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+
+  class Record < EventsRecord
     self.table_name = "events"
     self.inheritance_column = nil
   end
+
+  # Re-parent EventsRecord (and therefore Record) onto a host-supplied
+  # abstract class. Must run BEFORE any query against Acta::Record
+  # executes — call from a host initializer after the parent class is
+  # defined. Re-defines the two constants so existing references to
+  # `Acta::Record` resolve to the new class.
+  #
+  # Use case: per-tenant SQLite sharding where the host wants events
+  # and its own tenant-scoped rows in the same connection pool to
+  # avoid SQLite write contention on cross-pool transactions.
+  def self.set_events_record_parent!(parent)
+    raise ArgumentError, "parent must be an abstract ActiveRecord class" unless parent.is_a?(Class) && parent < ::ActiveRecord::Base && parent.abstract_class?
+
+    Acta.send(:remove_const, :Record)        if Acta.const_defined?(:Record, false)
+    Acta.send(:remove_const, :EventsRecord)  if Acta.const_defined?(:EventsRecord, false)
+
+    Acta.const_set(:EventsRecord, Class.new(parent) { self.abstract_class = true })
+    Acta.const_set(:Record, Class.new(Acta::EventsRecord) do
+      self.table_name = "events"
+      self.inheritance_column = nil
+    end)
+  end
 end

data/lib/acta/testing/dsl.rb

@@ -72,6 +72,10 @@ module Acta
       # Assert that running Acta.rebuild! twice produces the same projected
       # state. The block returns a snapshot of the relevant state (whatever
       # the app considers authoritative for this projection).
+      #
+      # Implicitly exercises any registered upcasters — both passes go
+      # through the same pipeline, so impure upcasters (state leaking
+      # outside the per-replay context) surface as a diff.
       def ensure_replay_deterministic(&snapshot)
         Acta.rebuild!
         first = snapshot.call
@@ -85,6 +89,55 @@ module Acta
           "second pass: #{second.inspect}"
         )
       end
+
+      # Insert an event row directly into the store, bypassing `Acta.emit`.
+      # Used by upcaster specs to seed events at arbitrary `event_version`
+      # values — `Acta.emit` always stamps the current code's version, so
+      # it can't simulate a pre-migration row.
+      #
+      #   acta_seed_event(type: "ItemAdded", event_version: 1,
+      #                   payload: { "item_id" => "g_1", "item_type" => "goal" })
+      def acta_seed_event(type:, payload:, event_version: 1, actor: nil,
+                          stream_type: nil, stream_key: nil, occurred_at: nil, uuid: nil)
+        actor ||= Acta::Current.actor || Acta::Actor.new(
+          type: "system", id: "rspec", source: "test"
+        )
+
+        Acta::Record.create!(
+          uuid: uuid || SecureRandom.uuid,
+          event_type: type.to_s,
+          event_version: event_version,
+          payload: payload,
+          actor_type: actor.type,
+          actor_id: actor.id,
+          source: actor.source,
+          metadata: actor.metadata.empty? ? nil : actor.metadata,
+          stream_type: stream_type&.to_s,
+          stream_key: stream_key,
+          occurred_at: occurred_at || Time.current,
+          recorded_at: Time.current
+        )
+      end
+
+      # End-to-end upcaster fixture: register upcasters, seed events at the
+      # given versions, run `Acta.rebuild!`. The caller asserts on whatever
+      # projection state matters for the migration under test.
+      #
+      #   acta_replay(
+      #     upcasters: [Scaff::WorkspaceMigrationUpcasters],
+      #     events: [
+      #       { type: "Scaff::ItemCreated", event_version: 1,
+      #         payload: { "item_id" => "g_1", "item_type" => "goal", "title" => "Foo" } },
+      #       { type: "Scaff::ItemCreated", event_version: 1,
+      #         payload: { "item_id" => "i_2", "parent_id" => "g_1", "title" => "Bar" } }
+      #     ]
+      #   )
+      #   expect(Workspace.pluck(:id)).to eq(%w[g_1])
+      def acta_replay(events:, upcasters: [])
+        upcasters.each { |u| Acta.register_upcaster(u) }
+        events.each { |attrs| acta_seed_event(**attrs) }
+        Acta.rebuild!
+      end
     end
   end
 end

data/lib/acta/upcaster.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module Acta
+  # Replay-time event transformation. Apps declare upcasters when an event
+  # type's shape changes between schema versions; the pipeline transforms
+  # stored records on read so projections see them at the latest shape.
+  # See `docs/upcasters.md` for the end-to-end recipe.
+  #
+  #   module Scaff
+  #     class WorkspaceMigrationUpcasters
+  #       include Acta::Upcaster
+  #
+  #       upcasts "Scaff::ItemCreated", from: 1, to: 2 do |event, context|
+  #         payload = event.payload
+  #         if payload["item_type"] == "goal"
+  #           context[:goal_to_workspace][payload["item_id"]] = payload["item_id"]
+  #           event.upcast_to(
+  #             type: "Scaff::WorkspaceCreated",
+  #             payload: { "workspace_id" => payload["item_id"], "title" => payload["title"] },
+  #             schema_version: 2
+  #           )
+  #         else
+  #           event.upcast_to(payload: payload.merge("workspace_id" => "..."), schema_version: 2)
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  #   Acta.register_upcaster(Scaff::WorkspaceMigrationUpcasters)
+  #
+  # Upcasters run pre-hydration during every read (`Acta.rebuild!`,
+  # `ReactorJob#perform`, the events admin, test fixtures) — apps can
+  # safely delete an old event class once a rename upcaster is in place.
+  # The live emit path is exempt: emitted events carry the current code's
+  # `event_version` and are dispatched in-memory before any read happens.
+  module Upcaster
+    # Identity sentinel — `upcasts "Foo", from: N, to: N, &Acta::Upcaster::NO_OP`
+    # declares the post-migration record at version N as a no-op pass-through
+    # (e.g. a `GoalPromotedToWorkspace` event whose effect is already produced
+    # by upcasting earlier events).
+    NO_OP = lambda { |event, _context| event }.freeze
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Declare a transform. `from` and `to` are integer schema versions on
+      # the same event type; `to` must be >= `from`. The block receives an
+      # upcast-shaped record and the per-replay context, and must return
+      # either a single upcasted record, an array (1-to-many — each branch
+      # continues chaining independently), `nil`/`[]` (drop on replay), or
+      # call `context.fail_replay!(reason)`.
+      def upcasts(event_type, from:, to:, &block)
+        raise UpcasterRegistryError, "from must be an Integer" unless from.is_a?(Integer)
+        raise UpcasterRegistryError, "to must be an Integer" unless to.is_a?(Integer)
+        raise UpcasterRegistryError, "to (#{to}) must be >= from (#{from})" if to < from
+        raise UpcasterRegistryError, "block required for upcasts(#{event_type.inspect}, from: #{from}, to: #{to})" unless block
+
+        upcaster_registrations << { event_type: event_type.to_s, from:, to:, block: }
+      end
+
+      def upcaster_registrations
+        @upcaster_registrations ||= []
+      end
+    end
+
+    # Per-replay state carrier passed to every upcaster block. Hash-shaped
+    # by default — `context[:goal_to_workspace] ||= {}`. Lives the length
+    # of one replay; never persisted across runs.
+    class Context
+      class FailReplay < StandardError; end
+
+      def initialize
+        @store = {}
+      end
+
+      def [](key)
+        @store[key] ||= {}
+      end
+
+      def []=(key, value)
+        @store[key] = value
+      end
+
+      def key?(key)
+        @store.key?(key)
+      end
+
+      # Halt the replay with a clear reason. Wrapped by the pipeline into
+      # `Acta::ReplayHaltedByUpcaster`, which carries the offending record.
+      def fail_replay!(reason)
+        raise FailReplay, reason
+      end
+    end
+
+    # In-memory record shape passed to upcaster blocks. Wraps a backing
+    # `Acta::Record` (the row as stored) with optional overlays for
+    # `event_type`, `event_version`, and `payload` — upcasters mutate
+    # *only* the overlays, never the stored row.
+    class View
+      ENVELOPE_FIELDS = %i[id uuid occurred_at recorded_at actor_type actor_id source metadata stream_type stream_key stream_sequence].freeze
+
+      attr_reader :base, :event_type, :event_version, :payload
+
+      def initialize(base, event_type: nil, event_version: nil, payload: nil)
+        @base = base
+        @event_type = event_type || base.event_type
+        @event_version = event_version || base.event_version
+        @payload = payload || (base.payload || {})
+      end
+
+      ENVELOPE_FIELDS.each do |field|
+        define_method(field) { base.public_send(field) }
+      end
+
+      # Produce a new View with the supplied attributes overlaid. `type`
+      # defaults to the current event_type; `payload` defaults to the
+      # current payload; `schema_version` is required and replaces
+      # `event_version`. The original (and the underlying Record) are
+      # untouched.
+      def upcast_to(type: nil, payload: nil, schema_version:)
+        raise ArgumentError, "schema_version required" if schema_version.nil?
+
+        View.new(
+          base,
+          event_type: type || @event_type,
+          event_version: schema_version,
+          payload: payload || @payload
+        )
+      end
+    end
+
+    # Holds the merged set of `(event_type, from) → block` entries from
+    # every registered upcaster class. Also tracks the max `to` per event
+    # type so the pipeline can flag future-version records cleanly.
+    class Registry
+      def initialize
+        @by_key = {}
+        @latest_to = Hash.new(0)
+        @registered_classes = []
+      end
+
+      def register(upcaster_class)
+        return if @registered_classes.include?(upcaster_class)
+
+        upcaster_class.upcaster_registrations.each do |reg|
+          key = [ reg[:event_type], reg[:from] ]
+          if @by_key.key?(key)
+            existing = @by_key[key]
+            raise UpcasterRegistryError,
+                  "Conflicting upcasters for #{reg[:event_type].inspect} v#{reg[:from]}: " \
+                  "#{existing[:owner].name} already registered the (event_type, from) pair; " \
+                  "#{upcaster_class.name} tried to register it again."
+          end
+
+          @by_key[key] = reg.merge(owner: upcaster_class)
+          @latest_to[reg[:event_type]] = [ @latest_to[reg[:event_type]], reg[:to] ].max
+        end
+
+        @registered_classes << upcaster_class
+      end
+
+      def find(event_type, from)
+        @by_key[[ event_type, from ]]
+      end
+
+      def latest_for(event_type)
+        @latest_to[event_type]
+      end
+
+      def empty?
+        @by_key.empty?
+      end
+
+      def clear!
+        @by_key.clear
+        @latest_to.clear
+        @registered_classes.clear
+      end
+    end
+
+    # Walk a record through every matching upcaster, returning 0..N
+    # upcasted records. Identity when no upcaster matches. Handles:
+    #   - chain:        block returns a single record → loop continues at new (event_type, event_version)
+    #   - 1-to-many:    block returns an array       → each branch recurses (so chaining + fan-out compose)
+    #   - drop:         block returns nil or []      → record produces no projection input
+    #   - fail:         block calls `context.fail_replay!` → halts with `ReplayHaltedByUpcaster`
+    #   - future ver:   stored event_version exceeds anything we can reach → `FutureSchemaVersion`
+    def self.upcast(record, context, registry: Acta.upcaster_registry)
+      origin = record.respond_to?(:base) ? record.base : record
+      current = record.is_a?(View) ? record : View.new(record)
+      return [ current ] if registry.empty?
+
+      loop do
+        reg = registry.find(current.event_type, current.event_version)
+
+        unless reg
+          known_max = registry.latest_for(current.event_type)
+          if known_max.positive? && current.event_version > known_max
+            raise FutureSchemaVersion.new(record: origin, latest_known_version: known_max)
+          end
+
+          break
+        end
+
+        result = begin
+          reg[:block].call(current, context)
+        rescue Context::FailReplay => e
+          raise ReplayHaltedByUpcaster.new(record: origin, reason: e.message)
+        end
+
+        return [] if result.nil? || (result.is_a?(Array) && result.empty?)
+
+        if result.is_a?(Array)
+          return result.flat_map { |branch| upcast(branch, context, registry: registry) }
+        end
+
+        unless result.is_a?(View)
+          raise UpcasterRegistryError,
+                "Upcaster #{reg[:owner].name} for #{current.event_type} v#{current.event_version} " \
+                "returned #{result.class} — expected an Acta::Upcaster::View " \
+                "(use `event.upcast_to(...)` to produce one)."
+        end
+
+        if result.event_version == current.event_version && result.event_type == current.event_type
+          # Identity at the current version (e.g. NO_OP). Stop the loop —
+          # otherwise we'd recurse forever on the same (type, version) key.
+          current = result
+          break
+        end
+
+        current = result
+      end
+
+      [ current ]
+    end
+  end
+end

data/lib/acta/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Acta
-  VERSION = "0.3.0"
+  VERSION = "0.4.0.alpha.1"
 end

data/lib/acta.rb

@@ -17,6 +17,7 @@ require_relative "acta/projection"
 require_relative "acta/reactor"
 require_relative "acta/reactor_job"
 require_relative "acta/command"
+require_relative "acta/upcaster"
 require_relative "acta/projection_managed"
 require_relative "acta/railtie" if defined?(::Rails::Railtie)
 
@@ -155,12 +156,29 @@ module Acta
     projection_classes << klass unless projection_classes.include?(klass)
   end
 
+  # Register a set of upcasters (a module/class that `include Acta::Upcaster`
+  # and declares `upcasts(...)` blocks). Idempotent — re-registering the
+  # same class is a no-op. See `Acta::Upcaster`.
+  def self.register_upcaster(klass)
+    upcaster_registry.register(klass)
+  end
+
+  def self.upcaster_registry
+    @upcaster_registry ||= Upcaster::Registry.new
+  end
+
+  def self.reset_upcasters!
+    upcaster_registry.clear!
+  end
+
   def self.rebuild!
     Projection.applying! { truncate_projections! }
+    context = Upcaster::Context.new
     Record.order(:id).find_each do |record|
-      event = events.find_by_uuid(record.uuid)
-      dispatch(event, kind: :projection)
-    rescue ProjectionError
+      events.upcast_and_hydrate(record, context).each do |event|
+        dispatch(event, kind: :projection)
+      end
+    rescue ProjectionError, ReplayHaltedByUpcaster, FutureSchemaVersion
       raise
     rescue StandardError => e
       raise ReplayError.new(record:, original: e)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: acta
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0.alpha.1
 platform: ruby
 authors:
 - Tom Gladhill
 bindir: bin
 cert_chain: []
-date: 2026-04-28 00:00:00.000000000 Z
+date: 2026-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -92,6 +92,7 @@ files:
 - config/routes.rb
 - docs/README.md
 - docs/event_driven_pub_sub.md
+- docs/upcasters.md
 - gemfiles/rails_7_2.gemfile
 - gemfiles/rails_8_0.gemfile
 - gemfiles/rails_8_1.gemfile
@@ -122,6 +123,7 @@ files:
 - lib/acta/types/array.rb
 - lib/acta/types/encrypted_string.rb
 - lib/acta/types/model.rb
+- lib/acta/upcaster.rb
 - lib/acta/version.rb
 - lib/acta/web.rb
 - lib/acta/web/engine.rb