acta 0.2.0 → 0.4.0.alpha.1

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/model.rb

@@ -2,8 +2,8 @@
 
 require "active_model"
 require "active_model/attributes"
-require_relative "model_type"
-require_relative "array_type"
+require_relative "types/model"
+require_relative "types/array"
 
 module Acta
   class Model
@@ -11,15 +11,15 @@ module Acta
     include ActiveModel::Attributes
 
     # Accept:
-    # - a class as a type (Acta::Model / Acta::Serializable) — wrapped in ModelType
-    # - array_of: Class or array_of: :symbol — wrapped in ArrayType
+    # - a class as a type (Acta::Model / Acta::Serializable) — wrapped in Acta::Types::Model
+    # - array_of: Class or array_of: :symbol — wrapped in Acta::Types::Array
     # - standard symbol types (:string, :integer, ...) — forwarded to AM
     def self.attribute(name, type = nil, array_of: nil, **options)
       if array_of
         element = element_type_for(array_of)
-        type = Acta::ArrayType.new(element)
+        type = Acta::Types::Array.new(element)
       elsif type.is_a?(Class)
-        type = Acta::ModelType.new(type)
+        type = Acta::Types::Model.new(type)
       end
 
       if type.nil?
@@ -31,7 +31,7 @@ module Acta
 
     def self.element_type_for(target)
       case target
-      when Class then Acta::ModelType.new(target)
+      when Class then Acta::Types::Model.new(target)
       when Symbol then ActiveModel::Type.lookup(target)
       else target
       end

data/lib/acta/reactor.rb

@@ -10,6 +10,28 @@ module Acta
       def sync?
         @sync == true
       end
+
+      # Declares the ActiveJob queue name to enqueue this reactor's job on.
+      # Read by Acta's dispatcher when the reactor is async (the default);
+      # ignored for `sync!` reactors. With no per-class declaration, the
+      # global `Acta.reactor_queue` setting applies; if that's also unset,
+      # ActiveJob's `:default` queue is used.
+      #
+      #   class WelcomeEmailReactor < Acta::Reactor
+      #     queue_as :fast
+      #     on UserSignedUp do |event|
+      #       UserMailer.welcome(event.user_id).deliver_later
+      #     end
+      #   end
+      def queue_as(name)
+        @queue_name = name
+      end
+
+      def queue_name
+        return @queue_name if defined?(@queue_name)
+
+        Acta.reactor_queue
+      end
     end
   end
 end

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/testing.rb

@@ -6,6 +6,26 @@ module Acta
   module Testing
     DEFAULT_ACTOR_ATTRIBUTES = { type: "system", id: "rspec", source: "test" }.freeze
 
+    # Wraps writes to `acta_managed!` AR models so the projection-write guard
+    # accepts them. Useful for fixtures, factories, and ad-hoc setup that
+    # needs to bypass the command + event + projection chain.
+    #
+    #   # spec/rails_helper.rb
+    #   require "acta/testing"
+    #   RSpec.configure do |config|
+    #     Acta::Testing.projection_writes_helper!(config)
+    #   end
+    #
+    #   # in any spec:
+    #   with_projection_writes do
+    #     Trail.create!(name: "Crank It Up", zone: zone)
+    #   end
+    module ProjectionWritesHelpers
+      def with_projection_writes(&block)
+        Acta::Projection.applying!(&block)
+      end
+    end
+
     module_function
 
     # Runs the given block with ActiveJob's :inline adapter, so async
@@ -46,5 +66,18 @@ module Acta
         Acta::Current.reset
       end
     end
+
+    # Includes `with_projection_writes` into every RSpec example. The helper
+    # forwards to `Acta::Projection.applying!`, so blocks under it pass the
+    # `acta_managed!` write guard. See ProjectionWritesHelpers.
+    #
+    #   # spec/rails_helper.rb
+    #   require "acta/testing"
+    #   RSpec.configure do |config|
+    #     Acta::Testing.projection_writes_helper!(config)
+    #   end
+    def projection_writes_helper!(config)
+      config.include(ProjectionWritesHelpers)
+    end
   end
 end

data/lib/acta/types/array.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "active_model/type"
+
+module Acta
+  module Types
+    # Wraps any other Acta type as a list-of-element type. Used internally
+    # by `attribute :foo, array_of: Class` (or `array_of: :symbol`); not
+    # constructed directly by consumers.
+    class Array < ActiveModel::Type::Value
+      def initialize(element_type)
+        super()
+        @element_type = element_type
+      end
+
+      def cast(value)
+        return nil if value.nil?
+
+        Kernel.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
+end

data/lib/acta/types/model.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "active_model/type"
+
+module Acta
+  module Types
+    # Wraps an Acta::Model subclass (or any class with `to_acta_hash` /
+    # `from_acta_hash`, e.g. AR classes that include Acta::Serializable)
+    # so it can be used as an `attribute` type on another Acta::Model.
+    # The wrapping is automatic — `attribute :location, GeoPoint` invokes
+    # this internally; consumers don't construct it directly.
+    class Model < 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
+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.2.0"
+  VERSION = "0.4.0.alpha.1"
 end