acta 0.2.0 → 0.4.0.alpha.1

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)
 
@@ -26,6 +27,18 @@ ActiveSupport.on_load(:active_record) do
 end
 
 module Acta
+  # Global default for `Acta::Reactor` ActiveJob queue. Per-class
+  # `queue_as :foo` declarations on a Reactor override this. Apps with
+  # queue priority discipline typically set this to e.g. `:fast` in an
+  # initializer; left nil, ActiveJob's `:default` queue is used.
+  class << self
+    attr_writer :reactor_queue
+  end
+
+  def self.reactor_queue
+    @reactor_queue
+  end
+
   def self.adapter
     @adapter ||= Adapters.for(Record.connection)
   end
@@ -117,7 +130,10 @@ module Acta
         event:,
         reactor_class: registration[:handler_class]
       ) do
-        ReactorJob.perform_later(
+        job = ReactorJob
+        queue = registration[:handler_class].queue_name
+        job = job.set(queue: queue) if queue
+        job.perform_later(
           event_uuid: event.uuid,
           reactor_class: registration[:handler_class].name,
           event_class: event.class.name
@@ -140,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)

data/lib/generators/acta/install/install_generator.rb

@@ -1,22 +1,22 @@
 # frozen_string_literal: true
 
 require "rails/generators"
-require "rails/generators/migration"
 require "rails/generators/active_record"
+require "rails/generators/active_record/migration"
 
 module Acta
   module Generators
     class InstallGenerator < Rails::Generators::Base
-      include Rails::Generators::Migration
+      include ActiveRecord::Generators::Migration
 
       source_root File.expand_path("templates", __dir__)
 
-      def self.next_migration_number(path)
-        ActiveRecord::Generators::Base.next_migration_number(path)
-      end
+      class_option :database, type: :string, aliases: %i[--db],
+                   desc: "The database for the events migration. By default, the current environment's primary database is used."
 
       def create_migration_file
-        migration_template "create_acta_events.rb.tt", "db/migrate/create_acta_events.rb"
+        migration_template "create_acta_events.rb.tt",
+                           File.join(db_migrate_path, "create_acta_events.rb")
       end
     end
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: acta
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0.alpha.1
 platform: ruby
 authors:
 - Tom Gladhill
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -15,56 +15,56 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: activemodel
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.1'
+        version: '7.2'
 description: |-
   Acta ships a small, opinionated set of primitives for event-driven and
   event-sourced Rails applications: events, handlers, projections, reactors,
@@ -80,8 +80,8 @@ files:
 - ".tool-versions"
 - CHANGELOG.md
 - LICENSE
-- PLAN.md
 - README.md
+- RELEASING.md
 - Rakefile
 - app/controllers/acta/web/application_controller.rb
 - app/controllers/acta/web/events_controller.rb
@@ -90,13 +90,18 @@ files:
 - app/views/acta/web/events/show.html.erb
 - app/views/layouts/acta/web/application.html.erb
 - 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
 - lib/acta.rb
 - lib/acta/actor.rb
 - lib/acta/adapters.rb
 - lib/acta/adapters/base.rb
 - lib/acta/adapters/postgres.rb
 - lib/acta/adapters/sqlite.rb
-- lib/acta/array_type.rb
 - lib/acta/command.rb
 - lib/acta/current.rb
 - lib/acta/errors.rb
@@ -104,7 +109,6 @@ files:
 - lib/acta/events_query.rb
 - lib/acta/handler.rb
 - lib/acta/model.rb
-- lib/acta/model_type.rb
 - lib/acta/projection.rb
 - lib/acta/projection_managed.rb
 - lib/acta/railtie.rb
@@ -116,7 +120,10 @@ files:
 - lib/acta/testing.rb
 - lib/acta/testing/dsl.rb
 - lib/acta/testing/matchers.rb
+- 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
@@ -128,10 +135,10 @@ homepage: https://github.com/whoojemaflip/acta
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/whoojemaflip/acta
   source_code_uri: https://github.com/whoojemaflip/acta
   changelog_uri: https://github.com/whoojemaflip/acta/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/whoojemaflip/acta/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -139,14 +146,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Lightweight event-driven and event-sourced primitives for Rails.
 test_files: []

data/PLAN.md

@@ -1,158 +0,0 @@
-# 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

data/lib/acta/array_type.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-require "active_model/type"
-
-module Acta
-  class ArrayType < ActiveModel::Type::Value
-    def initialize(element_type)
-      super()
-      @element_type = element_type
-    end
-
-    def cast(value)
-      return nil if value.nil?
-
-      Array(value).map { |el| @element_type.cast(el) }
-    end
-
-    def serialize(value)
-      return nil if value.nil?
-
-      value.map { |el| @element_type.serialize(el) }
-    end
-
-    def deserialize(value)
-      return nil if value.nil?
-
-      value.map { |el| @element_type.deserialize(el) }
-    end
-  end
-end

data/lib/acta/model_type.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-require "active_model/type"
-
-module Acta
-  class ModelType < ActiveModel::Type::Value
-    def initialize(wrapped_class)
-      super()
-      @wrapped_class = wrapped_class
-    end
-
-    def cast(value)
-      case value
-      when nil then nil
-      when @wrapped_class then value
-      when Hash then @wrapped_class.from_acta_hash(value)
-      else
-        raise ArgumentError, "Cannot cast #{value.class} (#{value.inspect}) to #{@wrapped_class}"
-      end
-    end
-
-    def serialize(value)
-      return nil if value.nil?
-
-      value.to_acta_hash
-    end
-
-    def deserialize(value)
-      cast(value)
-    end
-  end
-end