standard_ledger 0.2.0 → 0.4.0

data/lib/standard_ledger/modes/async.rb

@@ -0,0 +1,141 @@
+module StandardLedger
+  module Modes
+    # `:async` mode: applies the projection in a background job enqueued
+    # from the entry's `after_create_commit` callback. The job runs after
+    # the outer transaction has committed, so the entry is durable before
+    # the projection runs — and a job failure does NOT roll back the entry.
+    #
+    # Used when the projection is too expensive or stateful for the entry's
+    # transaction (jsonb rebuild, multi-row aggregate). The canonical
+    # example is nutripod's `Order#payable_balance` / `Order#fulfillable_balance`
+    # jsonb columns, which need to be recomputed from every PaymentRecord /
+    # FulfillmentRecord against the order — work that's safe to defer past
+    # the originating transaction.
+    #
+    # Class-form only: `:async` projections must declare `via: ProjectorClass`,
+    # whose `apply(target, entry)` should recompute from the log inside
+    # `with_lock` rather than apply a delta. Block-form per-kind handlers
+    # aren't safe under retry — incrementing a counter twice on retry is a
+    # silent data corruption bug — so block-form is rejected at registration
+    # time (see `Projector#projects_onto`).
+    #
+    # The strategy installs an `after_create_commit` callback once per entry
+    # class. The callback walks every `:async`-mode projection registered on
+    # the class and enqueues `StandardLedger::ProjectionJob` per (entry,
+    # projection) pair, honoring the optional `if:` guard.
+    #
+    # ## with_modes interop
+    #
+    # `StandardLedger.with_modes(EntryClass => :inline) { ... }` forces async
+    # projections to run synchronously inside the block — useful in unit
+    # specs that want end-to-end coverage without standing up a job runner.
+    # Inline-override mode skips the enqueue and runs `target.with_lock {
+    # projector.apply(target, entry) }` directly. The override is read in
+    # `#call`; specs can capture the empty job queue via `have_enqueued_job`
+    # / `perform_enqueued_jobs` and still observe the projection's effects.
+    class Async
+      # Install the `after_create_commit` callback on `entry_class` exactly
+      # once. Subsequent calls (e.g. when a second `:async` projection is
+      # added later in the class body) are no-ops — the same callback
+      # handles all `:async` projections registered on the class.
+      #
+      # @param entry_class [Class] the host entry class.
+      # @return [void]
+      # @raise [ArgumentError] when `entry_class` is not ActiveRecord-backed
+      #   (no `after_create_commit` hook available). `:async` mode requires
+      #   AR transactional callbacks; non-AR entry classes can't dispatch
+      #   the post-commit enqueue.
+      def self.install!(entry_class)
+        return if entry_class.instance_variable_get(:@_standard_ledger_async_installed)
+
+        unless entry_class.respond_to?(:after_create_commit)
+          raise ArgumentError,
+                "Modes::Async requires an ActiveRecord-backed entry class on " \
+                "#{entry_class.name || entry_class.inspect} — the entry class must inherit " \
+                "from ActiveRecord::Base. Use :inline mode for plain-Ruby entry classes."
+        end
+
+        entry_class.after_create_commit { StandardLedger::Modes::Async.new.call(self) }
+        entry_class.instance_variable_set(:@_standard_ledger_async_installed, true)
+      end
+
+      # Enqueue `ProjectionJob` for every `:async` projection registered on
+      # the entry's class. Called from the `after_create_commit` callback
+      # installed by `.install!`.
+      #
+      # Honors the optional `if:` guard (skips enqueue when guard returns
+      # false) and `StandardLedger.mode_override_for(entry_class)` (when set
+      # to `:inline`, runs the projection synchronously inside `with_lock`
+      # instead of enqueueing).
+      #
+      # A nil target at enqueue time skips silently — the entry's FK was
+      # unset for this projection's association, so there's nothing to
+      # project onto. (The job has its own nil-target guard; this short-
+      # circuit just avoids the wasted enqueue.)
+      #
+      # @param entry [ActiveRecord::Base] the just-committed entry.
+      # @return [void]
+      def call(entry)
+        definitions = async_definitions_for(entry.class)
+        return if definitions.empty?
+
+        override = StandardLedger.mode_override_for(entry.class)
+
+        definitions.each do |definition|
+          next if definition.guard && !entry.instance_exec(&definition.guard)
+
+          if override == :inline
+            run_inline(entry, definition)
+          else
+            target = entry.public_send(definition.target_association)
+            next if target.nil?
+
+            job_class = StandardLedger.config.default_async_job || StandardLedger::ProjectionJob
+            job_class.perform_later(entry, definition.target_association.to_s)
+          end
+        end
+      end
+
+      private
+
+      def async_definitions_for(entry_class)
+        return [] unless entry_class.respond_to?(:standard_ledger_projections_for)
+
+        entry_class.standard_ledger_projections_for(:async)
+      end
+
+      # `with_modes(EntryClass => :inline)` short-circuit: run the projector
+      # synchronously inside `with_lock`, mirroring the job's behavior
+      # without the enqueue. Skips silently when the target is nil so the
+      # nil-FK contract matches the enqueue path.
+      def run_inline(entry, definition)
+        target = entry.public_send(definition.target_association)
+        return if target.nil?
+
+        prefix = StandardLedger.config.notification_namespace
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        begin
+          target.with_lock do
+            definition.projector_class.new.apply(target, entry)
+          end
+        rescue StandardError => e
+          duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+          StandardLedger::EventEmitter.emit(
+            "#{prefix}.projection.failed",
+            entry: entry, target: target, projection: definition.target_association,
+            mode: :async, error: e, duration_ms: duration_ms, attempt: 1
+          )
+          raise
+        end
+
+        duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+        StandardLedger::EventEmitter.emit(
+          "#{prefix}.projection.applied",
+          entry: entry, target: target, projection: definition.target_association,
+          mode: :async, duration_ms: duration_ms, attempt: 1
+        )
+      end
+    end
+  end
+end

data/lib/standard_ledger/modes/matview.rb

@@ -63,6 +63,7 @@ module StandardLedger
       #   the SQL — re-raised after the `failed` event fires.
       def self.refresh!(view_name, concurrently:)
         validate_view_name!(view_name)
+        check_transaction_state!(view_name, concurrently: concurrently)
 
         prefix = StandardLedger.config.notification_namespace
         sql = build_refresh_sql(view_name, concurrently: concurrently)
@@ -76,9 +77,10 @@ module StandardLedger
           view: view_name.to_s, concurrently: concurrently, duration_ms: duration_ms
         )
       rescue StandardError => e
-        # ArgumentError from the validator should propagate without firing
-        # the failed notification — the SQL was never issued.
-        raise if e.is_a?(ArgumentError)
+        # ArgumentError from the validator and RefreshInsideTransaction from
+        # the boundary check should propagate without firing the failed
+        # notification — the SQL was never issued.
+        raise if e.is_a?(ArgumentError) || e.is_a?(StandardLedger::RefreshInsideTransaction)
 
         StandardLedger::EventEmitter.emit(
           "#{prefix}.projection.failed",
@@ -95,13 +97,42 @@ module StandardLedger
       # injection isn't possible even when a host carelessly pipes a config
       # value into the call.
       def self.validate_view_name!(view_name)
-        return if view_name.to_s.match?(/\A[a-zA-Z_][a-zA-Z0-9_.]*\z/)
+        # Bare identifier OR exactly one schema-qualified `schema.view` part.
+        # The previous shape `\A[a-zA-Z_][a-zA-Z0-9_.]*\z` allowed trailing
+        # dots (`reporting.`) and unlimited qualification (`a.b.c.d`); both
+        # would round-trip to a Postgres syntax error at `connection.execute`
+        # time rather than the gem boundary.
+        return if view_name.to_s.match?(/\A[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?\z/)
 
         raise ArgumentError,
               "view_name must be a valid SQL identifier; got #{view_name.inspect}"
       end
       private_class_method :validate_view_name!
 
+      # Reject `refresh!` calls issued from inside an open transaction when
+      # `concurrently: true`. Postgres rejects
+      # `REFRESH MATERIALIZED VIEW CONCURRENTLY` inside a transaction block
+      # (and would otherwise raise `PG::ActiveSqlTransaction` mid-call); we
+      # catch it at the gem boundary so the failure is attributable.
+      #
+      # The non-concurrent (`concurrently: false`) form *is* permitted inside
+      # a transaction by Postgres, so we only guard the concurrent path.
+      #
+      # Use `connection.add_transaction_record { … }` to defer to after-commit
+      # if you need read-your-write semantics from inside a transactional
+      # operation; otherwise, move the refresh outside the transaction.
+      def self.check_transaction_state!(view_name, concurrently:)
+        return unless concurrently
+        return unless ActiveRecord::Base.connection.transaction_open?
+
+        raise StandardLedger::RefreshInsideTransaction,
+              "StandardLedger.refresh!(#{view_name.inspect}) cannot run inside a transaction with " \
+              "concurrently: true — Postgres rejects `REFRESH MATERIALIZED VIEW CONCURRENTLY` inside " \
+              "transaction blocks. Move the call outside the transaction, or defer it via " \
+              "`connection.add_transaction_record { ... }` for after-commit execution."
+      end
+      private_class_method :check_transaction_state!
+
       def self.build_refresh_sql(view_name, concurrently:)
         if concurrently
           "REFRESH MATERIALIZED VIEW CONCURRENTLY #{view_name}"

data/lib/standard_ledger/modes/trigger.rb

@@ -0,0 +1,50 @@
+module StandardLedger
+  module Modes
+    # `:trigger` mode: the host owns a database trigger (created in a Rails
+    # migration) that updates the projection target's columns on every
+    # entry INSERT. The gem records the trigger's name and the equivalent
+    # rebuild SQL, but does **not** create or manage the trigger itself —
+    # giving a Ruby DSL the power to install/replace triggers is a deploy
+    # footgun (silent re-creation on `db:schema:load` against a non-empty
+    # DB), and triggers are versioned by `db/schema.rb` like any other DDL.
+    #
+    # Two consumers read the recorded metadata:
+    #
+    # - `StandardLedger.rebuild!` runs the rebuild SQL when invoked,
+    #   binding `:target_id` to each target the log references. The same
+    #   recompute path as `:sql` mode — the only difference is that the
+    #   after-create application is performed by the database trigger
+    #   rather than a Ruby callback.
+    # - The `standard_ledger:doctor` rake task verifies that the named
+    #   trigger exists in the connected schema. Migration drift (a missing
+    #   or renamed trigger) is caught at deploy time, not at runtime.
+    #
+    # Unlike `:inline` and `:sql`, this strategy does NOT install an
+    # `after_create` callback — the trigger fires from the database. The
+    # `install!` no-op only marks the entry class as having at least one
+    # `:trigger` projection registered (mirrors the `Modes::Matview` shape).
+    #
+    # See `standard_ledger-design.md` §5.3.4 for the full contract.
+    class Trigger
+      # Mark the entry class as having at least one `:trigger` projection
+      # registered. The actual trigger metadata lives on the entry class's
+      # `standard_ledger_projections` array; this method exists only to
+      # mirror the `Modes::*.install!` shape so `Projector#install_mode_callbacks_for`
+      # can dispatch uniformly across modes.
+      #
+      # No `after_create` callback is installed — the trigger runs in the
+      # database, not Ruby. Idempotent across multiple `:trigger`
+      # projections on the same entry class.
+      #
+      # @param entry_class [Class] the host entry class (unused — kept for
+      #   parity with the other strategy classes).
+      # @return [void]
+      def self.install!(_entry_class)
+        # Intentionally empty: trigger projections fire from the DB, so
+        # there's no Ruby-side callback to wire. The DSL has already
+        # captured `trigger_name` and `recompute_sql` on the Definition;
+        # `rebuild!` and the `doctor` rake task consume those directly.
+      end
+    end
+  end
+end

data/lib/standard_ledger/projector.rb

@@ -34,7 +34,7 @@ module StandardLedger
     # projections; they're `nil` for every other mode.
     Definition = Struct.new(
       :target_association, :mode, :projector_class, :handlers, :guard, :lock, :permissive,
-      :recompute_sql, :view, :refresh_options, :options,
+      :recompute_sql, :trigger_name, :view, :refresh_options, :options,
       keyword_init: true
     )
 
@@ -62,12 +62,253 @@ module StandardLedger
       #   metadata, e.g. `{ every: 5.minutes, concurrently: true }`. The
       #   gem records this on the Definition for hosts to read when wiring
       #   their scheduler; the gem does NOT auto-schedule.
+      # @param trigger_name [String, Symbol, nil] for `mode: :trigger` only —
+      #   the name of the host-owned database trigger. Required when mode is
+      #   `:trigger`; ignored otherwise. The gem does NOT create or manage
+      #   the trigger; it records the name so `standard_ledger:doctor` can
+      #   verify the trigger's presence in the connected schema.
       # @yield optional block-DSL form: register per-kind handlers via
       #   `on(:kind) { |target, entry| ... }`. Not allowed for `mode: :matview`.
       # @return [Definition] the registered projection.
-      def projects_onto(target_association, mode:, via: nil, if: nil, lock: nil, permissive: false, view: nil, refresh: nil, **options, &block)
+      def projects_onto(target_association, mode:, via: nil, if: nil, lock: nil, permissive: false,
+                        view: nil, refresh: nil, trigger_name: nil, counters: nil,
+                        rebuild_sql: nil, **options, &block)
         guard = binding.local_variable_get(:if) # `if:` is a reserved keyword
 
+        # `counters:` is sugar for the most common :inline shape — a hash
+        # mapping `kind => column` that synthesises one
+        # `on(kind) { |t, _| t.class.increment_counter(col, t.id) }` per
+        # entry. Direct UPDATE (the class-method form) is intentional: it
+        # invalidates the SQL query cache for the target table on each
+        # call, which keeps multiple sibling-entry creates in a single
+        # transaction (e.g. via `accepts_nested_attributes_for`) from
+        # losing updates against stale cached reads. Block form remains
+        # available for non-counter projections.
+        if counters
+          if mode != :inline
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `counters:` with mode: #{mode.inspect}; " \
+                  "the counters shortcut is :inline-only — counter caches don't fit the async/sql/" \
+                  "trigger/matview contracts"
+          end
+          if block || via
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `counters:` together with a block or `via:`; " \
+                  "the counters shortcut synthesises handlers automatically — use one form or the other"
+          end
+          unless counters.is_a?(Hash) && counters.all? { |k, v| k.is_a?(Symbol) && v.is_a?(Symbol) }
+            raise ArgumentError,
+                  "projects_onto :#{target_association} `counters:` must be a Hash of Symbol kind => Symbol column"
+          end
+
+          block = ->(*) {
+            counters.each do |kind, column|
+              on(kind) { |target, _| target.class.increment_counter(column, target.id) }
+            end
+          }
+        end
+
+        # `rebuild_sql:` keyword form for `:trigger` mode — equivalent to
+        # the legacy block-DSL `rebuild_sql "..."` clause but doesn't
+        # require a block. The block-DSL form is still supported.
+        if rebuild_sql && mode == :trigger
+          if block
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got both `rebuild_sql:` and a block — " \
+                  "use one form or the other"
+          end
+          # Capture the parameter value into a local before building the
+          # block: when the synthesised block is `instance_eval`'d on
+          # `TriggerDsl`, the bare name `rebuild_sql` resolves to
+          # `TriggerDsl#rebuild_sql` (the writer), not the keyword
+          # parameter we want to pass in.
+          rebuild_sql_value = rebuild_sql
+          block = ->(*) { rebuild_sql(rebuild_sql_value) }
+        end
+
+        if mode == :manual
+          # `:manual` records the projection contract (target + projector
+          # class) without installing any callback. Use this when the
+          # entry's interesting lifecycle event is not the create itself
+          # — typically an AASM/state-machine model where the projection
+          # should fire on a transition (e.g. `validate_disbursement!`)
+          # rather than `after_create`. Hosts invoke the projector
+          # explicitly from operation code; the gem's role is to make
+          # the contract introspectable (via `standard_ledger_projections`)
+          # and to give `StandardLedger.rebuild!` a class handle for log
+          # replay.
+          if block
+            raise ArgumentError,
+                  "projects_onto :#{target_association} mode: :manual does not accept a block — " \
+                  "the entry's lifecycle is owned by the host, so per-kind handlers can't fire " \
+                  "automatically. Use `via: ProjectorClass` and invoke the projector explicitly " \
+                  "from the operation that drives the lifecycle event."
+          end
+
+          if via.nil?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} mode: :manual requires `via: ProjectorClass` " \
+                  "whose `apply(target, entry)` is invoked explicitly by host code on the lifecycle " \
+                  "event the gem cannot observe (e.g. an AASM transition)."
+          end
+
+          unless lock.nil?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `lock:` with mode: :manual; " \
+                  "the host owns the dispatch boundary and is responsible for any locking it needs."
+          end
+
+          if permissive
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `permissive: true` with mode: :manual; " \
+                  "`permissive:` is only meaningful with the block form."
+          end
+
+          definition = Definition.new(
+            target_association: target_association,
+            mode: mode,
+            projector_class: via,
+            handlers: {},
+            guard: guard,
+            lock: lock,
+            permissive: permissive,
+            recompute_sql: nil,
+            trigger_name: nil,
+            view: nil,
+            refresh_options: nil,
+            options: options
+          )
+
+          self.standard_ledger_projections = standard_ledger_projections + [ definition ]
+          # No `install_mode_callbacks_for` — the host owns the dispatch.
+          return definition
+        end
+
+        if mode == :async
+          if block
+            raise ArgumentError,
+                  "projects_onto :#{target_association} mode: :async does not accept a block — " \
+                  "use `via: ProjectorClass` whose `apply(target, entry)` recomputes from the log " \
+                  "inside `with_lock` for retry-safety. Block-form per-kind handlers aren't safe " \
+                  "under async retry."
+          end
+
+          if via.nil?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} mode: :async requires `via: ProjectorClass` " \
+                  "(class-form only — see the registration error message for block-form for the why)"
+          end
+
+          unless lock.nil?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `lock:` with mode: :async; " \
+                  ":async always wraps the projector in `target.with_lock` for retry-safety, " \
+                  "so the option is redundant. Drop it."
+          end
+
+          if permissive
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `permissive: true` with mode: :async; " \
+                  "`permissive:` is only meaningful with the block form, and `:async` mode rejects " \
+                  "block-form for retry-safety reasons"
+          end
+
+          definition = Definition.new(
+            target_association: target_association,
+            mode: mode,
+            projector_class: via,
+            handlers: {},
+            guard: guard,
+            lock: lock,
+            permissive: permissive,
+            recompute_sql: nil,
+            trigger_name: nil,
+            view: nil,
+            refresh_options: nil,
+            options: options
+          )
+
+          self.standard_ledger_projections = standard_ledger_projections + [ definition ]
+          install_mode_callbacks_for(definition)
+          return definition
+        end
+
+        if mode == :trigger
+          if via
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `via:` with mode: :trigger; " \
+                  "the trigger is the contract — there is no projector class. The host " \
+                  "owns the trigger via a Rails migration; the gem only records the " \
+                  "trigger's name and rebuild SQL"
+          end
+
+          unless lock.nil?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `lock:` with mode: :trigger; " \
+                  "`lock:` is not supported by :trigger mode — the database trigger handles " \
+                  "concurrency atomically"
+          end
+
+          if permissive
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `permissive:` with mode: :trigger; " \
+                  "`permissive:` is not supported by :trigger mode — the trigger doesn't " \
+                  "dispatch through per-kind handlers"
+          end
+
+          if guard
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `if:` with mode: :trigger; " \
+                  "`if:` is not supported by :trigger mode — the database trigger fires " \
+                  "unconditionally from the DB on INSERT, so a Ruby-side guard would " \
+                  "silently never run"
+          end
+
+          if trigger_name.nil? || trigger_name.to_s.empty?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} requires `trigger_name: \"...\"` for mode: :trigger; " \
+                  "the gem records the trigger's name so `standard_ledger:doctor` can verify its presence"
+          end
+
+          unless block
+            raise ArgumentError,
+                  "projects_onto :#{target_association} requires a block with `rebuild_sql \"...\"` for mode: :trigger"
+          end
+
+          dsl = TriggerDsl.new
+          dsl.instance_eval(&block)
+
+          if dsl.rebuild_sql_text.nil?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} block is empty; mode: :trigger requires a `rebuild_sql \"...\"` clause"
+          end
+
+          unless dsl.rebuild_sql_text.include?(":target_id")
+            raise ArgumentError,
+                  "projects_onto :#{target_association} rebuild SQL must include the `:target_id` placeholder; " \
+                  "it's bound to each target's id when `StandardLedger.rebuild!` walks the log"
+          end
+
+          definition = Definition.new(
+            target_association: target_association,
+            mode: mode,
+            projector_class: nil,
+            handlers: {},
+            guard: guard,
+            lock: lock,
+            permissive: permissive,
+            recompute_sql: dsl.rebuild_sql_text,
+            trigger_name: trigger_name.to_s,
+            view: nil,
+            refresh_options: nil,
+            options: options
+          )
+
+          self.standard_ledger_projections = standard_ledger_projections + [ definition ]
+          install_mode_callbacks_for(definition)
+          return definition
+        end
+
         if mode == :sql
           if via
             raise ArgumentError,
@@ -118,6 +359,7 @@ module StandardLedger
             lock: lock,
             permissive: permissive,
             recompute_sql: dsl.recompute_sql,
+            trigger_name: nil,
             view: nil,
             refresh_options: nil,
             options: options
@@ -150,6 +392,7 @@ module StandardLedger
             lock: lock,
             permissive: permissive,
             recompute_sql: nil,
+            trigger_name: nil,
             view: view.to_s,
             refresh_options: refresh || {},
             options: options
@@ -200,6 +443,7 @@ module StandardLedger
           lock: lock,
           permissive: permissive,
           recompute_sql: nil,
+          trigger_name: nil,
           view: nil,
           refresh_options: nil,
           options: options
@@ -222,10 +466,14 @@ module StandardLedger
         case definition.mode
         when :inline
           StandardLedger::Modes::Inline.install!(self)
+        when :async
+          StandardLedger::Modes::Async.install!(self)
         when :sql
           StandardLedger::Modes::Sql.install!(self)
         when :matview
           StandardLedger::Modes::Matview.install!(self)
+        when :trigger
+          StandardLedger::Modes::Trigger.install!(self)
         end
       end
 
@@ -275,6 +523,12 @@ module StandardLedger
               "the recompute SQL runs through `Modes::Sql#call` directly with no per-kind dispatch"
       end
 
+      if definition.mode == :trigger
+        raise Error,
+              "apply_projection! is not supported for mode: :trigger; " \
+              "the database trigger fires from the DB on INSERT, not from Ruby"
+      end
+
       return false if definition.guard && !instance_exec(&definition.guard)
 
       target = public_send(definition.target_association)
@@ -357,5 +611,28 @@ module StandardLedger
         @recompute_sql = sql
       end
     end
+
+    # Internal collector for the `:trigger`-mode block-DSL form. Captures
+    # the `rebuild_sql "..."` clause's SQL string. The trigger itself is
+    # owned by the host (created in a Rails migration); the gem only
+    # records this rebuild SQL so `StandardLedger.rebuild!` can recompute
+    # the projection from the log when invoked. Like `:sql` mode, the SQL
+    # must be expressible as a single statement with `:target_id` bound
+    # from each target's id at rebuild time.
+    class TriggerDsl
+      attr_reader :rebuild_sql_text
+
+      def rebuild_sql(sql)
+        unless sql.is_a?(String)
+          raise ArgumentError, "rebuild_sql requires a SQL string; got #{sql.class}"
+        end
+        unless @rebuild_sql_text.nil?
+          raise ArgumentError,
+                "rebuild_sql called more than once in the same projects_onto block; " \
+                ":trigger mode supports exactly one rebuild_sql clause per projection"
+        end
+        @rebuild_sql_text = sql
+      end
+    end
   end
 end

data/lib/standard_ledger/version.rb

@@ -1,3 +1,3 @@
 module StandardLedger
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end