acta 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01a8eb1c4e0fb04d54ed2c8302c45f0d38064f07839d3b030a771ce70d03d27c
-  data.tar.gz: b34f32a1dc253ae7402d6c7a67f17c2a650d369b9e2d6036979f94da2e4b8820
+  metadata.gz: 9c2218e4d40ef364d3dba8452e489a06f3e6d0503726e4d95660f7637e00efdc
+  data.tar.gz: a3602d1b12e575f44f3f0bf4acdad256d5bd25a9ede5f43688f869015b96abe8
 SHA512:
-  metadata.gz: bf7c4fb886f607687bc5a274627f4c0580dc097b4096f5fb5d36f34d91dd6f05a0a2ea69e49a132b13b896ce8b61f0f6729792577543d0132d00565beacd0528
-  data.tar.gz: 157f9f789ad5d6387a6a71ee0c97754ec69f73a09b638cb7c20f6b68c6836637359af024b1765ffd05236c9908d0f83df6ac450b475827fdc7da7eaed0beef1f
+  metadata.gz: ac176442ad27e359358e7f59f585facf1ee2dc6c11902737e9da2e1f7b7b354d14ce40aed1bd80e9e4ad12a04f2f5f8d0b9d548c9077fdc58c0debf0f755ac66
+  data.tar.gz: 5de77801dd8088ae0f3699dae67388db5db0688f3de840c31938073ef5bd57f843f543b2c8584633a4a637cdf41a6f359bec65c9d59c5622228fc80783dba691

data/CHANGELOG.md

@@ -10,6 +10,50 @@ breaking changes as the API settles through real-world consumer integration.
 
 ## [Unreleased]
 
+## [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

@@ -27,14 +27,14 @@ 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 +43,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 +112,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 +246,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 +410,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 +473,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 +651,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,31 @@
+# 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`.
+
+## 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).
+- **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).