acta 0.2.0 → 0.4.0.alpha.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01a8eb1c4e0fb04d54ed2c8302c45f0d38064f07839d3b030a771ce70d03d27c
-  data.tar.gz: b34f32a1dc253ae7402d6c7a67f17c2a650d369b9e2d6036979f94da2e4b8820
+  metadata.gz: 0af752d227a9c1f376f4e1201bd2ba2b60faf5d178a1db06975d8bdaec0c66ef
+  data.tar.gz: 417ec6f02d8348355bccf44d0682a534d8e3dc5f7a9d6364b5a3d31326e04e76
 SHA512:
-  metadata.gz: bf7c4fb886f607687bc5a274627f4c0580dc097b4096f5fb5d36f34d91dd6f05a0a2ea69e49a132b13b896ce8b61f0f6729792577543d0132d00565beacd0528
-  data.tar.gz: 157f9f789ad5d6387a6a71ee0c97754ec69f73a09b638cb7c20f6b68c6836637359af024b1765ffd05236c9908d0f83df6ac450b475827fdc7da7eaed0beef1f
+  metadata.gz: 112a12b4dac2b676183237c2d73df829d9d0f6e3e4519be94fb25844d1dce7cd890a8de8a758d0e469b6eaf5b2454cf5c033e139a22785e82ae0b158396148fb
+  data.tar.gz: 4ca8da1823ee930a0a3ebdc3b70d47b108d53e7e05c2328ce58976fc09fa65d9eb256520fdf376cd5da03099f70bd9b02858e7ccd32e429b62ca62939d802aa5

data/CHANGELOG.md

@@ -10,6 +10,122 @@ 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
+
+- Reactor `queue_as` macro and `Acta.reactor_queue` global default for
+  pinning the ActiveJob queue async reactors land on. Per-class
+  declarations beat the global default; with neither set, ActiveJob's
+  `:default` queue is used. `sync!` reactors are unaffected. Closes #38.
+
+- `Acta::Testing.projection_writes_helper!(config)` adds a
+  `with_projection_writes` block helper to every RSpec example. Forwards
+  to `Acta::Projection.applying!` so blocks under it pass the
+  `acta_managed!` write guard — useful for fixtures, factories, and
+  one-off setup. Closes #33.
+
+- README now covers per-emit atomicity, what `applying!` actually does
+  (write-path safety net, *not* transaction control), and `rebuild!`
+  partial-failure behavior. Closes #34.
+
+### Changed
+
+- Custom AM type classes consolidated under `Acta::Types::*`.
+  `Acta::ModelType` → `Acta::Types::Model`,
+  `Acta::ArrayType` → `Acta::Types::Array`. The `:encrypted_string`
+  type was already there as `Acta::Types::EncryptedString`. The
+  user-facing API (`attribute :foo, Class`, `attribute :foo,
+  array_of: ...`, `attribute :foo, :encrypted_string`) is unchanged
+  — these classes are internal and never appeared in user code,
+  README, or specs. Breaking only for someone constructing them
+  directly via `Acta::ModelType.new(...)`.
+
+- Lowered Ruby/Rails compat floor: `ruby >= 3.2`, `rails >= 7.2`
+  (was 3.4 / 8.1). CI now exercises Ruby 3.2/3.3/3.4 × Rails
+  7.2/8.0/8.1. The prior floor reflected "latest at the time" rather
+  than actual API requirements; full spec suite passes against all
+  three Rails versions. Closes #37.
+
+### Fixed
+
+- Install generator now honors `--database=foo` and writes the migration
+  to the target database's `migrations_paths` (typically
+  `db/foo_migrate/`) instead of the default `db/migrate/`. Matches AR's
+  built-in migration generator behavior. Closes #29.
+
 ## [0.2.0] — 2026-04-27
 
 ### Added

data/README.md

@@ -21,20 +21,21 @@ 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.
 
 ## Installation
 
-Not published to RubyGems. Install from git:
-
 ```ruby
 # Gemfile
-gem "acta", git: "https://github.com/whoojemaflip/acta.git"
+gem "acta"
 ```
 
-Requires Rails 8.1+ and Ruby 3.4+.
+Tested against Ruby 3.2, 3.3, 3.4 and Rails 7.2, 8.0, 8.1. Pre-1.0 —
+the API is still settling through real-world consumer integration.
+Pin a minor (`"~> 0.2"`) if you need stability across `bundle update`.
 
 Generate the events table migration:
 
@@ -43,8 +44,22 @@ bin/rails generate acta:install
 bin/rails db:migrate
 ```
 
+For multi-database apps, target a specific database with `--database`:
+
+```bash
+bin/rails generate acta:install --database=events
+bin/rails db:migrate:events
+```
+
+The migration is written to that database's `migrations_paths`
+(typically `db/<database>_migrate/`).
+
 ## Usage
 
+The five sections below introduce the primitives in isolation. For
+end-to-end walkthroughs of specific scenarios, see the
+[cookbook](docs/README.md).
+
 ### 1. Define an event
 
 ```ruby
@@ -98,6 +113,28 @@ end
 Reactors run after-commit and default to async via ActiveJob. Use `sync!`
 to run in the caller's thread (mostly useful for tests).
 
+Pin a specific ActiveJob queue per class with `queue_as`:
+
+```ruby
+class ConfirmationEmailReactor < Acta::Reactor
+  queue_as :fast
+  on OrderPlaced do |event|
+    OrderMailer.confirmation(event.order_id).deliver_later
+  end
+end
+```
+
+Or set a global default for every reactor that doesn't declare its own:
+
+```ruby
+# config/initializers/acta.rb
+Acta.reactor_queue = :fast
+```
+
+Per-class declarations beat the global default; with neither set,
+ActiveJob's `:default` queue is used. `sync!` reactors bypass ActiveJob
+entirely, so the queue setting is ignored for them.
+
 ### 4. Project state (event-sourced)
 
 For aggregates where the event log is the source of truth and AR tables
@@ -210,41 +247,142 @@ Test fixtures, data migrations, and one-off backfills can wrap
 intentional out-of-band writes in `Acta::Projection.applying! { ... }`
 to bypass the safety net explicitly.
 
+#### Atomicity and replay
+
+Three related semantics that are easy to conflate:
+
+**Per-emit atomicity.** `Acta.emit` opens a `requires_new: true`
+transaction that wraps both the event row insert and every projection's
+`on EventClass` block. If any projection raises, the entire emit rolls
+back: the event row isn't persisted, other projections' writes don't
+commit, and async reactors never fan out (they're enqueued only on
+successful commit). Sync reactors also run inside this transaction —
+but their side effects (mailers sent, HTTP calls made) can't be undone
+by a rollback if they've already happened, which is why `sync!` should
+be reserved for follow-up DB writes or cases where "fired but rolled
+back" is acceptable.
+
+**`Acta::Projection.applying!` is not the transaction.** It's a separate
+concept: a thread-local flag that gates `acta_managed!` writes,
+distinguishing "projection code is running" from "someone called
+`Order.create!` from a controller." Acta sets the flag automatically
+inside projection blocks and during the truncate phase of `rebuild!`.
+Apps set it explicitly with `Acta::Projection.applying! { ... }` to
+bypass the `acta_managed!` guard for fixtures, migrations, and one-off
+backfills. Toggling the flag does *not* open or join a transaction —
+the per-emit transaction does that work, and `rebuild!` uses one
+implicit transaction per `delete_all` plus one per replayed event.
+
+**`Acta.rebuild!` partial failure.** Rebuild truncates every projected
+table first (inside one `applying!` block, in FK-safe order), then
+replays the log event-by-event through projections. If an event raises
+mid-replay, the truncate has already happened and the rebuild halts at
+that event — projected tables are in a *partially-rebuilt* state, not
+the pre-rebuild state and not the fully-replayed state. Treat any
+rebuild failure as needing investigation; once the underlying
+projection bug is fixed, re-running `rebuild!` re-truncates and starts
+over from the beginning of the log. There is no resume-from-event-N
+mode.
+
 ### 5. Commands for validated writes
 
 ```ruby
 # app/commands/place_order.rb
 class PlaceOrder < Acta::Command
+  param :order_id, :string
   param :customer_id, :string
   param :total_cents, :integer
 
-  validates :customer_id, :total_cents, presence: true
+  validates :order_id, :customer_id, :total_cents, presence: true
   validates :total_cents, numericality: { greater_than: 0 }
 
   def call
-    order_id = "order_#{SecureRandom.uuid}"
     emit OrderPlaced.new(order_id:, customer_id:, total_cents:)
   end
 end
 
+order_id = "order_#{SecureRandom.uuid_v7}"
+PlaceOrder.call(order_id:, customer_id: "c_1", total_cents: 4200)
+# `order_id` is in scope — use it for the redirect, response, etc.
+```
+
+The default pattern is **caller generates the ID, command takes it as a
+param**. Simplest possible thing — the ID is in scope at the call site,
+the command is a thin validate-and-emit shell, and there's no question
+about what `.call` returns.
+
+#### What `Command.call` returns
+
+`Acta::Command.call` returns the **command instance**. The instance
+carries the params, an `emitted_events` array (every event emitted
+during `#call`, in order), and any state the command exposed via
+`attr_reader`. **The return value of `#call` is discarded** — see the
+pitfall below.
+
+Most callers ignore the return value:
+
+```ruby
+PlaceOrder.call(order_id:, customer_id: "c_1", total_cents: 4200)
+```
+
+#### When the command should generate the ID
+
+If the ID prefix or shape is a domain concern that belongs with the
+command (and the caller would always do the same thing if you forced
+it to generate), expose the generated ID via `attr_reader`:
+
+```ruby
+class PlaceOrder < Acta::Command
+  attr_reader :order_id
+
+  param :customer_id, :string
+  param :total_cents, :integer
+
+  def call
+    @order_id = "order_#{SecureRandom.uuid_v7}"
+    emit OrderPlaced.new(order_id: @order_id, customer_id:, total_cents:)
+  end
+end
+
 cmd = PlaceOrder.call(customer_id: "c_1", total_cents: 4200)
-cmd.emitted_events.first.order_id   # => "order_…"
+cmd.order_id   # => "order_018f2…"
 ```
 
-`Acta::Command.call` returns the command instance. The instance carries
-the params, the `emitted_events` array (every event emitted during
-`#call`, in order), and any state the command exposed via
-`attr_reader`. Callers that don't care about the events ignore the
-return value:
+This reads naturally at the call site — `cmd.order_id`, not
+`cmd.emitted_events.first.order_id` — and gives the value a stable,
+semantic name regardless of how many events the command emits or in
+what order.
+
+#### Inspecting the events
+
+When you genuinely need the event objects (for further dispatch,
+logging, or because the command emits multiple events with no single
+"primary" one), read `emitted_events`:
 
 ```ruby
-PlaceOrder.call(customer_id: "c_1", total_cents: 4200)
+cmd = PlaceOrder.call(...)
+cmd.emitted_events           # => [#<OrderPlaced ...>]
+cmd.emitted_events.first     # the only event in this case
 ```
 
 Commands can emit zero, one, or many events. The framework does not
-invent a "primary" event — when a command emits more than one, the
-caller (who knows the domain) picks what matters from
-`cmd.emitted_events`.
+invent a "primary" event — when there are several, the caller (who
+knows the domain) picks what matters from `emitted_events`.
+
+#### Pitfall: don't `return` from `#call`
+
+```ruby
+def call
+  order_id = "order_#{SecureRandom.uuid_v7}"
+  emit OrderPlaced.new(order_id:, …)
+  order_id   # ← this is silently discarded by Acta::Command.call
+end
+```
+
+A trailing expression in `#call` looks like the obvious way to surface
+the generated ID, but `Command.call` always returns the command
+instance — the body's return value is dropped. Use `attr_reader` (or
+let the caller pass the ID in) instead.
 
 ### Optimistic locking (high-water mark)
 
@@ -273,24 +411,55 @@ fresh state or surface the collision instead of silently clobbering it.
 don't need this; reach for it when concurrent writes to the same
 aggregate are realistic and lost-update would be a bug.
 
-## Identity: generate IDs in commands, never in projections
+## Identity: IDs originate at the write boundary, never in projections
 
 For event-sourced aggregates, aggregate IDs (typically UUIDs) must be
-stable across `Acta.rebuild!` and must not drift if the projected tables
-are truncated. The rule: **the command generates the ID once, the event
-carries it in its payload, and the projection reads it back out**.
+stable across `Acta.rebuild!` and must not drift if the projected
+tables are truncated. The rule: **the ID is generated once at the
+write boundary, the event carries it in its payload, and the
+projection reads it back out**.
+
+"Write boundary" means either the caller of the command, or the
+command itself — whichever owns the ID's shape. Both are correct;
+pick by where the prefix/format convention lives.
 
 ```ruby
+# Pattern A — caller generates (default; what you'll usually want):
 class CreateOrder < Acta::Command
+  param :order_id, :string
   param :customer_id, :string
   param :total_cents, :integer
 
   def call
-    order_id = "order_#{SecureRandom.uuid}"    # generated here, once, forever
     emit OrderCreated.new(order_id:, customer_id:, total_cents:)
   end
 end
 
+order_id = "order_#{SecureRandom.uuid_v7}"
+CreateOrder.call(order_id:, customer_id: "c_1", total_cents: 4200)
+
+# Pattern B — command generates (when the prefix/shape is a domain
+# concern of the command itself):
+class CreateOrder < Acta::Command
+  attr_reader :order_id
+
+  param :customer_id, :string
+  param :total_cents, :integer
+
+  def call
+    @order_id = "order_#{SecureRandom.uuid_v7}"
+    emit OrderCreated.new(order_id: @order_id, customer_id:, total_cents:)
+  end
+end
+
+cmd = CreateOrder.call(customer_id: "c_1", total_cents: 4200)
+cmd.order_id   # => "order_018f2…"
+```
+
+Either way, the event carries `order_id` in its payload, and the
+projection reads it back:
+
+```ruby
 class OrderCreated < Acta::Event
   stream :order, key: :order_id
   attribute :order_id, :string
@@ -305,25 +474,27 @@ class OrderProjection < Acta::Projection
 end
 ```
 
-When `Acta.rebuild!` runs, it calls `OrderProjection.truncate!` (wiping
-the `orders` table) and replays every event. The projection reads
-`event.order_id` — which was written at the original command call — and
-re-inserts the row with the same ID. **Rebuild never regenerates IDs.**
+When `Acta.rebuild!` runs, it calls `OrderProjection.truncate!`
+(wiping the `orders` table) and replays every event. The projection
+reads `event.order_id` — which was written at the original write —
+and re-inserts the row with the same ID. **Rebuild never regenerates
+IDs.**
 
 ### What to avoid
 
 - **Generating IDs in projection code.** Non-deterministic — every
   rebuild produces new IDs, orphaning any foreign references.
-  `SecureRandom` / `Time.current` / anything stateful has no place in a
-  projection.
+  `SecureRandom` / `Time.current` / anything stateful has no place in
+  a projection.
 - **Generating IDs in the event class's `initialize`.** Same problem:
-  if the event assigns a default ID when reconstructed from a row, old
-  events would decode with fresh IDs. Events should take an explicit
-  `order_id:` attribute and require it in the payload.
+  if the event assigns a default ID when reconstructed from a row,
+  old events would decode with fresh IDs. Events should take an
+  explicit `order_id:` attribute and require it in the payload.
 - **Dropping the events table.** The event log is the primary source
-  of IDs. Purging it regenerates all IDs on next write. Back it up and
-  treat it as production-critical — even more so if other systems (a
-  separate user DB, external services) reference your aggregates' IDs.
+  of IDs. Purging it regenerates all IDs on next write. Back it up
+  and treat it as production-critical — even more so if other
+  systems (a separate user DB, external services) reference your
+  aggregates' IDs.
 
 ### Why this matters
 
@@ -481,6 +652,31 @@ end
 `with_actor` restores the surrounding actor when the block returns or
 raises.
 
+### Writing to acta_managed! models in setup
+
+Tests that need to seed `acta_managed!` AR models directly — without
+going through a command + event + projection chain — would otherwise
+trip `Acta::ProjectionWriteError`. Pull in the `with_projection_writes`
+helper:
+
+```ruby
+RSpec.configure do |config|
+  Acta::Testing.projection_writes_helper!(config)
+end
+
+# in any spec:
+with_projection_writes do
+  zone = Zone.create!(name: "Cheakamus")
+  Trail.create!(zone:, name: "Crank It Up")
+end
+```
+
+The helper forwards to `Acta::Projection.applying!`, which is the same
+flag projections use internally — so writes inside the block pass the
+guard. Outside the block, the guard is back in force. Use this for
+factories, fixtures, and one-off setup; for production code paths, emit
+events instead.
+
 ### RSpec matchers
 
 ```ruby

data/RELEASING.md

@@ -0,0 +1,107 @@
+# Releasing Acta
+
+Releases publish to [rubygems.org](https://rubygems.org/gems/acta) via
+GitHub Actions Trusted Publishing (OIDC) — no long-lived API key in
+CI, no `gem push` from a laptop. The pipeline is:
+
+```
+git tag vX.Y.Z → push tag → .github/workflows/release.yml
+                            ├── runs the test suite as a gate
+                            └── if green: rubygems mints an OIDC token
+                                          and publishes acta-X.Y.Z.gem
+```
+
+## Cutting a release
+
+1. **Update `CHANGELOG.md`.** Move entries under `[Unreleased]` to a
+   new `[X.Y.Z] — YYYY-MM-DD` section. Leave `[Unreleased]` empty above it.
+
+2. **Bump the version.** Edit `lib/acta/version.rb` to `VERSION = "X.Y.Z"`.
+
+3. **Run the suite locally.** `bundle exec rake` — tests + rubocop.
+   Don't tag a red main.
+
+4. **Commit, tag, push.**
+   ```bash
+   git commit -am "Release X.Y.Z"
+   git tag -a vX.Y.Z -m "Release X.Y.Z"
+   git push origin main vX.Y.Z
+   ```
+
+5. **Watch the workflow.** Actions tab → Release → in-flight run.
+   Takes ~2 min. If it goes red, fix forward: revert the version bump
+   commit, push that, then re-do steps 1-4 with the next patch number
+   (X.Y.Z+1) — tags are immutable once a release has used them, even
+   if the publish failed.
+
+6. **Verify.** Once green:
+   - https://rubygems.org/gems/acta should show the new version
+   - `gem info acta -r` from any machine should resolve it
+   - The Releases page on GitHub should have the tag entry (the workflow
+     creates it from `release-gem@v1`)
+
+## Choosing the version number
+
+Pre-1.0, breaking changes are allowed in minor bumps. The convention
+this project uses:
+
+- **Patch (0.2.0 → 0.2.1)** — bug fixes, doc updates, internal
+  refactors that don't change behavior
+- **Minor (0.2.x → 0.3.0)** — new features, deprecations, breaking
+  changes
+- **Major (0.x → 1.0)** — only when the API has settled enough to
+  promise stability
+
+Consumers are expected to pin `~> 0.2` (or whatever minor) until 1.0.
+
+## One-time setup (already done — kept for posterity)
+
+If this ever needs to be redone (e.g. moving to a new GitHub repo or
+rubygems account):
+
+1. **rubygems.org account** — `tom@gladhill.ca`, MFA enabled.
+
+2. **Trusted Publisher entry** — rubygems.org → Profile → Trusted
+   Publishers → Add a publisher:
+
+   | Field | Value |
+   |---|---|
+   | Repository | `whoojemaflip/acta` |
+   | Workflow filename | `release.yml` |
+   | Environment name | `rubygems` |
+
+3. **GitHub Actions environment** — Repo Settings → Environments →
+   `rubygems`. The workflow's `release` job is gated on it via
+   `environment: rubygems`.
+
+4. **Gemspec hardening** — `acta.gemspec` already sets
+   `rubygems_mfa_required = "true"`. This means any future manual
+   `gem push` (bypassing the workflow) requires an MFA-authenticated
+   API key. Trusted Publishing isn't affected — OIDC bypasses API
+   keys entirely.
+
+## Yanking a bad release
+
+If a published version turns out to be broken:
+
+```bash
+gem yank acta -v X.Y.Z
+```
+
+Yanking removes the version from the index — `gem install acta -v X.Y.Z`
+will fail, but anyone who already locked it in a Gemfile.lock can
+still resolve it. So yank is for "stop the bleeding," not a do-over.
+The fix-forward pattern is to ship X.Y.Z+1 with the correction.
+
+## Manual fallback (don't use unless the workflow is broken)
+
+The keys to do this are not configured by default. If you need to
+emergency-publish from a laptop:
+
+```bash
+gem signin                         # interactive — needs MFA
+gem build acta.gemspec
+gem push acta-X.Y.Z.gem
+```
+
+Document why the workflow couldn't be used in the commit message.

data/docs/README.md

@@ -0,0 +1,32 @@
+# Acta cookbook
+
+Concrete walkthroughs for the shapes Acta apps actually take. The
+main [README](../README.md) documents primitives in isolation; this
+folder shows how they compose for specific scenarios, with
+end-to-end code and the trade-offs that come with each choice.
+
+## Patterns
+
+- [**Event-driven pub/sub**](event_driven_pub_sub.md) — the simplest
+  useful Acta shape. One domain event, multiple independent
+  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
+
+Recipes will land here when these are written or implemented:
+
+- **Event-sourced aggregates** — projections as the AR view of the
+  log; `Acta.rebuild!` as the source-of-truth recovery path. The
+  primitive is already documented in the README, but a worked
+  example of a full aggregate (command + event + projection +
+  replay determinism spec) earns its own page.
+- **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).