acta 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 01a8eb1c4e0fb04d54ed2c8302c45f0d38064f07839d3b030a771ce70d03d27c
+  data.tar.gz: b34f32a1dc253ae7402d6c7a67f17c2a650d369b9e2d6036979f94da2e4b8820
+SHA512:
+  metadata.gz: bf7c4fb886f607687bc5a274627f4c0580dc097b4096f5fb5d36f34d91dd6f05a0a2ea69e49a132b13b896ce8b61f0f6729792577543d0132d00565beacd0528
+  data.tar.gz: 157f9f789ad5d6387a6a71ee0c97754ec69f73a09b638cb7c20f6b68c6836637359af024b1765ffd05236c9908d0f83df6ac450b475827fdc7da7eaed0beef1f

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.1

data/CHANGELOG.md

@@ -0,0 +1,210 @@
+# Changelog
+
+All notable changes to Acta are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Public API stability begins at v1.0.0. Versions prior to that may make
+breaking changes as the API settles through real-world consumer integration.
+
+## [Unreleased]
+
+## [0.2.0] — 2026-04-27
+
+### Added
+
+- `Acta::Projection.truncates(*ar_classes)` — class macro for declaring
+  the AR classes a projection owns. Used both as the default `truncate!`
+  target list (`delete_all` on each in declared order) and as input to
+  `Acta.rebuild!`'s cross-projection ordering: projections whose tables
+  are FK-referenced by another projection's tables now run first, so
+  children are deleted before their parents — independent of registration
+  order. Cycles raise `Acta::TruncateOrderError`. Projections without
+  `truncates` declarations keep their existing registration-order
+  behavior. The truncate phase runs inside `Projection.applying!`, so
+  `acta_managed!` models truncate cleanly. Closes #3.
+
+- `acta_managed!` AR class macro — opt-in safety net for projection-owned
+  models. Once an AR model becomes a projection, writes from anywhere
+  other than the projection bypass the event log and break
+  `Acta.rebuild!` determinism. `acta_managed!` gates every AR write path
+  (save / update / destroy / update_columns / update_all / delete_all /
+  insert_all / upsert_all) on `Acta::Projection.applying?` and raises
+  `Acta::ProjectionWriteError` (or warns, with `on_violation: :warn`)
+  when violated. `Acta::Projection.applying! { … }` is the public escape
+  hatch for fixtures, migrations, and intentional backfills. Closes #6.
+
+- `Acta::Testing.default_actor!(config, **attrs)` — RSpec configuration
+  helper that sets `Acta::Current.actor` before every example and resets
+  it after, eliminating the per-spec boilerplate and the easy-to-forget
+  `Acta::MissingActor` errors that come with it. Defaults to a
+  `system / rspec / test` actor; override any attribute. Closes #8.
+- `Acta::Testing::DSL#with_actor(**attrs) { … }` — block-scoped actor
+  override for individual examples that need to attribute emissions to
+  a specific user. Restores the previous actor when the block returns
+  (or raises).
+
+- `Acta::Railtie` — auto-loads projection / handler / reactor classes at boot
+  so they self-register before the first emit, even in Rails dev mode where
+  Zeitwerk would otherwise lazy-load them on first reference. Without this,
+  a projection that nothing has touched yet stays unsubscribed: the emit
+  succeeds, the event row is written, and the projection silently never runs.
+  Configurable via `config.acta.{projection,handler,reactor}_paths`; defaults
+  to `app/projections`, `app/handlers`, `app/reactors`. Set a path list to
+  `[]` to opt out. Closes #7.
+
+### Changed
+
+- **Breaking: command DSL collapses around streams, concurrency, and
+  emit declarations.**
+  - Removed `Acta::Command.stream` macro. Commands no longer declare or
+    inherit stream identity — events are the only thing that carries
+    stream config.
+  - Removed `Acta::Command.on_concurrent_write` macro and the
+    capture-at-instantiation / assert-at-emit machinery on Command
+    instances.
+  - Removed `Acta::Command.emits` macro and `emitted_event_class(es)`.
+    The framework no longer asks commands to declare what they emit;
+    `def call` is the only source of truth. The "primary event" concept
+    that came with single-arg `emits` was a fiction once commands could
+    legitimately emit zero, one, or many events.
+  - `Acta::Command.call` now returns the command instance (was: the
+    return value of the user's `#call` method). Read events back via
+    `cmd.emitted_events` — an array of every event emitted during the
+    invocation, in order. Idempotent commands return an instance with
+    an empty array.
+  - Renamed `Acta.emit(event, expected_sequence: N)` keyword to
+    `if_version: N`.
+  - Renamed `Acta::ConcurrencyConflict` → `Acta::VersionConflict`. Its
+    `expected_sequence` / `actual_sequence` readers are now
+    `expected_version` / `actual_version`.
+
+  `Acta::Command` now has four moving parts: `param`, `validates`,
+  `call`, `emit`. Apps that need optimistic locking write it explicitly
+  using the new public primitive:
+  ```ruby
+  version = Acta.version_of(stream_type: :order, stream_key: order_id)
+  emit OrderRenamed.new(...), if_version: version
+  ```
+  Two lines, fully visible, no macro magic. Most commands need none of
+  this and lose nothing.
+
+- `Acta.register_projection` is now idempotent — registering the same
+  projection class twice is a no-op instead of double-dispatching events.
+
+### Added
+
+- `Acta.version_of(stream_type:, stream_key:)` — public class method
+  returning the current high-water mark for a stream (0 for fresh
+  streams). Pair with `Acta.emit(..., if_version:)` for optimistic
+  locking.
+
+- Per-attribute payload encryption via `attribute :token, :encrypted_string`.
+  Backed by `ActiveRecord::Encryption` — same primary/deterministic/derivation
+  keys as Rails AR-encrypted columns, same key-rotation model (append a new
+  primary, keep old keys for decryption). In-memory event values stay
+  plaintext (`event.token` returns the secret); only the serialized payload
+  written to `events.payload` is ciphertext. Resolves the issue where events
+  carrying OAuth tokens / API keys would defeat AR encryption on the
+  projection's columns by leaving cleartext copies in the audit log. Closes #1.
+- `Acta::Event.from_acta_record(envelope:, payload:)` — internal hydration
+  hook that routes payload values through `type.deserialize` before
+  construction. Used by `EventsQuery` to decrypt `:encrypted_string`
+  attributes on read; existing types are unaffected.
+- Acta::Web masks encrypted payload leaves as `********` in both the
+  row preview and the pretty-JSON detail block. Detection is
+  envelope-based (`ActiveRecord::Encryption.encryptor.encrypted?`), so
+  any AR-encrypted ciphertext in the payload is masked regardless of
+  whether the event class declares `:encrypted_string` — including
+  historical events written before the attribute was opted in.
+
+## [0.1.1]
+
+### Added
+
+- `Acta::Command` — new `emits EventClass` class-method DSL. The command
+  inherits `stream_type` and `stream_key_attribute` from the declared
+  event class, eliminating the duplicate `stream :order, key: :order_id`
+  declaration in the common case where a command emits a single event
+  for its aggregate. Explicit `stream` on the command still works and
+  takes precedence when both are given (useful when the command operates
+  on a different aggregate than its emitted event, or doesn't emit an
+  Acta event at all).
+
+## [0.1.0]
+
+Feature-complete per the initial implementation plan (M0–M10). Next step
+is real-world consumer integration to validate the API before cutting
+v1.0.0.
+
+### Core primitives
+
+- `Acta::Event` — ActiveModel-backed event classes with typed payloads,
+  validate-on-init, uuid / occurred_at / recorded_at / actor envelope.
+- `Acta::Handler` — base primitive with the `on EventClass` DSL and
+  auto-registration via Rails eager loading.
+- `Acta::Projection < Acta::Handler` — sync + transactional + replayable.
+  Raises `ProjectionError` on failure, rolling back the emit. Tracks
+  subclasses for `Acta.rebuild!`.
+- `Acta::Reactor < Acta::Handler` — after-commit + async via ActiveJob
+  (default) or `sync!` opt-in. Skipped during replay.
+- `Acta::Command < Acta::Model` — param validation, `stream` declaration,
+  `on_concurrent_write :raise` / `:ignore` optimistic-concurrency DSL.
+  Raises `InvalidCommand` on param validation failure.
+- `Acta::Actor` value object — type, id, source, metadata.
+- `Acta::Current` — `ActiveSupport::CurrentAttributes` with an `actor`
+  attribute, propagates through ActiveJob.
+
+### Payload shape
+
+- `Acta::Model` base class — `ActiveModel::Attributes` + `ActiveModel::Model`
+  + JSON round-trip with schema-drift tolerance.
+- Class-typed attributes: `attribute :location, GeoPoint` wraps the class
+  in `Acta::ModelType` automatically.
+- Array attributes: `attribute :tags, array_of: Tag` wraps the element
+  type in `Acta::ArrayType`.
+- `Acta::Serializable` concern — opt-in for AR classes to participate as
+  payload types with `acta_serialize only:` / `except:` control.
+- Nested models and AR classes compose; arrays of either work.
+
+### Storage
+
+- Single events table with identity, stream, payload (JSON/jsonb), actor,
+  source, metadata, and dual time columns (`occurred_at` + `recorded_at`).
+- Indexes: uuid unique, stream-identity partial unique, event_type,
+  actor, source, occurred_at.
+- `rails g acta:install` generator for the migration.
+- Adapter seam: `Acta::Adapters::SQLite` (default) and
+  `Acta::Adapters::Postgres`.
+- SQLite: single-writer sequencing with unique-constraint backstop.
+- Postgres: `pg_advisory_xact_lock(hashtext(...))` per stream; `uuid` and
+  `jsonb` native column types.
+
+### Testing
+
+- `Acta::Testing.test_mode { }` — inline reactors for the block.
+- RSpec matchers: `emit(EventClass).with(attrs)`, `emit_events([...])`,
+  `emit_any_events`.
+- `Acta::Testing::DSL` — given_events / when_command / when_event /
+  then_emitted / then_emitted_nothing_else.
+- `ensure_replay_deterministic { snapshot }` — catches Time.current,
+  rand, and other non-deterministic projection patterns.
+
+### Observability
+
+- ActiveSupport::Notifications:
+  - `acta.event_emitted` — `{ event, event_type }`
+  - `acta.projection_applied` — `{ event, projection_class }`
+  - `acta.reactor_invoked` — `{ event, reactor_class, sync: true }`
+  - `acta.reactor_enqueued` — `{ event, reactor_class }`
+
+### Errors
+
+- `Acta::Error` (StandardError)
+  - `InvalidEvent` (carries event)
+  - `InvalidCommand < CommandError` (carries command)
+  - `ConcurrencyConflict` (stream identity, expected/actual sequence)
+  - `ProjectionError` (event, projection_class, original)
+  - `MissingActor`, `ConfigurationError`, `AdapterError`
+  - `UnknownEventType`, `ReplayError`

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Gladhill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/PLAN.md

@@ -0,0 +1,158 @@
+# Acta Implementation Plan
+
+Companion to the design doc (private, at `~/Sites/Journal/ideas/event_source_rails.md`).
+This file is version-controlled alongside the code and tracks the milestone
+breakdown for reaching v1.0.
+
+## Conventions
+
+- **Ruby hash shorthand** (Ruby 3.1+): `{ name:, age: }` when variables in
+  scope match keys. Applied everywhere.
+- **RSpec** exclusively for v1. Minitest matcher support considered post-v1.
+- **TDD**: every milestone is a sequence of small red → green → refactor
+  cycles. One behaviour per commit where practical.
+- **Rubocop**: `rubocop-rails-omakase` style. Clean before each commit.
+- **Commits**: atomic, imperative mood, one logical change each.
+- **Semver** from v0.1. Public API stability begins at v1.0.
+
+## Environment
+
+- Ruby: 3.4+
+- Rails floor: 8.1+
+- Local: `~/Sites/acta`
+- Remote: `git@github.com:whoojemaflip/acta.git`
+
+## Milestone breakdown
+
+Each milestone is independently shippable.
+
+### M0 — Scaffolding ✅
+
+Gem skeleton, RSpec, rubocop-rails-omakase, CI, README, LICENSE, CHANGELOG,
+`PLAN.md` in repo. Baseline green build.
+
+### M1 — First emit (the round-trip milestone) ✅
+
+**Goal:** `Acta.emit(event)` persists a row; `Acta.events.last` reads it back.
+
+1. Adapter seam — spec `Acta::Adapters::Base` interface; SQLite adapter stub.
+2. Migration generator — `rails g acta:install` creates the events table.
+3. `Acta::Model` — AM::Attributes + AM::Model + `to_acta_hash` / `from_acta_hash`
+   + `validate!` in initialize raising `Acta::InvalidEvent`.
+4. `Acta::Event < Acta::Model` — adds `uuid`, `event_type`, `event_version`,
+   `occurred_at`, `recorded_at`, `actor`.
+5. `Acta::Actor` value object — `type`, `id`, `source`, `metadata`.
+6. `Acta::Current` — CurrentAttributes with `actor`.
+7. `Acta.configure` — connection + single-store `:default` registration
+   (latent store concept).
+8. `Acta.emit(event)` — strict on missing actor (`Acta::MissingActor`);
+   persists via adapter; returns the persisted event.
+9. `Acta.events` — query API returning `Acta::Event` instances from the log.
+10. Error leaves so far: `Error`, `InvalidEvent`, `MissingActor`,
+    `ConfigurationError`, `AdapterError`.
+
+**Checkpoint:** end-to-end spec that configures, emits, queries, asserts.
+
+### M2 — Streams & concurrency ✅
+
+1. Stream DSL — `stream :order, key: :order_id` on event classes.
+2. Sequence calculation in SQLite adapter (BEGIN IMMEDIATE + SELECT MAX).
+3. `ConcurrencyConflict` on unique-index violation.
+4. Stream-scoped query — `Acta.events.for_stream(type:, key:)`.
+5. `on_concurrent_write :raise` machinery (wires into M6 commands).
+
+### M3 — Handlers & dispatch ✅
+
+1. `Acta::Handler` base class + `on EventClass do |event| ... end` DSL.
+2. Auto-registration via inheritance + Rails `eager_load_paths`.
+3. Dispatch on emit (sync base handlers).
+4. Registry isolation for specs — `Acta.reset_handlers!`.
+
+### M4 — Projections ✅
+
+1. `Acta::Projection < Acta::Handler` with sync+transactional contract.
+2. Projections run inside emit transaction.
+3. `ProjectionError` wraps underlying exception + projection class.
+4. `Acta.rebuild!` — truncate projections, replay log, re-run projections.
+5. Replay skips reactors (prep for M5).
+
+### M5 — Reactors ✅
+
+1. `Acta::Reactor < Acta::Handler` with after-commit + ActiveJob default.
+2. `Acta::ReactorJob` — loads event by uuid, dispatches to reactor class.
+3. `sync true` opt-in.
+4. Skip on replay.
+5. Actor propagation via `Acta::Current` serialized into ActiveJob.
+
+### M6 — Commands ✅
+
+1. `Acta::Command < Acta::Model` — param validation via AM::Attributes.
+2. `stream :order, key: :order_id` on command — declares aggregate identity.
+3. `on_concurrent_write :raise` — captures stream sequence at instantiation.
+4. `.call(**params)` entry; `emit event` as instance method;
+   `InvalidCommand` on validation failure.
+5. Auto-loading from `app/commands/`.
+
+### M7 — Testing DSL (`Acta::Testing`) ✅
+
+1. RSpec matchers: `emit(EventClass).with(...)`, `emit_events([...])`,
+   `not_to emit_any_events`.
+2. `given_events { ... }` — seeds the log directly without running reactors.
+3. `when_command(cmd)` — runs command, captures emitted events.
+4. `then_emitted(EventClass, **attrs)` / `then_emitted_nothing_else`.
+5. `Acta.test_mode { ... }` — inline reactors for the block.
+6. Replay determinism helper —
+   `expect_projections_deterministic { ... }`.
+
+### M8 — `Acta::Serializable` (AR piggyback) ✅
+
+1. Concern adding `to_acta_hash` / `self.from_acta_hash(hash)` on AR classes.
+2. `acta_serialize only: / except:` configuration.
+3. Type dispatch for AR classes in event attributes.
+4. Arrays of AR (`array_of:`) support.
+5. Nested AR-in-AR round-trip.
+6. STI support via `type` column capture.
+7. Schema-drift tolerance — filter unknown keys on deserialize.
+
+### M9 — Postgres adapter ✅
+
+1. `Acta::Adapters::Postgres` implementation.
+2. Advisory locks (`pg_advisory_xact_lock(hashtext(...))`) per stream.
+3. `jsonb` column type + `uuid` column type + `gen_random_uuid()`.
+4. Shared behaviour specs — `it_behaves_like "an Acta adapter"`.
+5. CI matrix with both SQLite and Postgres.
+6. Concurrency-specific specs exercising genuine concurrent writers.
+
+### M10 — v1.0 polish ✅
+
+1. Observability via `ActiveSupport::Notifications` —
+   `acta.event_emitted`, `acta.projection_applied`, `acta.reactor_enqueued`.
+2. Remaining error leaves — `UnknownEventType`, `ReplayError`, gaps.
+3. README rewrite with full worked examples.
+4. Tag v1.0.0.
+
+## Milestone dependencies
+
+```
+M0 → M1 → M2 → M3 → M4 ─┐
+                   └──→ M5 ─┐
+                   M6 ──────┴─→ M7 → M8 → M9 → M10
+```
+
+M4 and M5 are independent after M3. M6 can start after M2. M8 benefits from
+M7. M9 can start anytime after M1 but is most valuable after M8.
+
+## Out of scope for v1
+
+- Upcasters (column reserved)
+- Multi-store (latent concept, not exposed)
+- MySQL adapter
+- `Acta::Saga` / process managers
+- LISTEN/NOTIFY or other pub/sub transport
+- Snapshots
+
+## Quality gates per commit
+
+- `bundle exec rspec` green
+- `bundle exec rubocop` clean
+- Change has a spec unless it's pure refactoring