standard_ledger 0.5.1 → 0.7.0

data/lib/standard_ledger.rb

@@ -1,7 +1,6 @@
 require "active_support"
 require "active_support/notifications"
 require "active_support/core_ext/string/inflections"
-require "concurrent"
 
 require "standard_ledger/version"
 require "standard_ledger/errors"
@@ -10,30 +9,24 @@ require "standard_ledger/result"
 require "standard_ledger/config"
 require "standard_ledger/entry"
 require "standard_ledger/projection"
-require "standard_ledger/projector"
-require "standard_ledger/modes/inline"
-require "standard_ledger/modes/sql"
-require "standard_ledger/modes/matview"
-require "standard_ledger/modes/trigger"
-require "standard_ledger/modes/async"
-require "standard_ledger/jobs/matview_refresh_job"
-require "standard_ledger/jobs/projection_job"
-require "standard_ledger/engine" if defined?(::Rails::Engine)
+require "standard_ledger/matview"
 
-# StandardLedger captures the recurring "immutable journal entry → N
-# aggregate projections" pattern as a declarative DSL on host ActiveRecord
-# models. See `standard_ledger-design.md` in the workspace root for the
-# full design discussion.
+# StandardLedger captures the "immutable, append-only journal entry" pattern
+# for host ActiveRecord models, plus two small helpers that sit next to it:
+# a `post` sugar for writing entries and a `refresh!` wrapper for host-owned
+# materialized views. See `standard_ledger-design.md` for the design notes.
 #
 # Public surface:
 #
 #   StandardLedger.configure { |c| ... }   # configure once at boot
 #   StandardLedger.config                  # read configured values
-#   StandardLedger.post(EntryClass, ...)   # write an entry + project
-#   StandardLedger.rebuild!(EntryClass)    # recompute projections from log
-#   StandardLedger.refresh!(:view_name)    # ad-hoc matview refresh
-#   StandardLedger.reset!                  # full test helper (wipes config + overrides)
-#   StandardLedger.reset_mode_overrides!   # clears only the with_modes thread-local
+#   StandardLedger.post(EntryClass, ...)   # write an entry, return a Result
+#   StandardLedger.refresh!(:view_name)    # refresh a materialized view
+#   StandardLedger.reset!                  # test helper (wipes config)
+#
+# 0.6.0 removed the projection engine (`projects_onto`, the projection
+# modes, `rebuild!`, `with_modes`, the jobs and the `doctor` task) — no
+# consuming app used it. See CHANGELOG.md for the upgrade note.
 module StandardLedger
   class << self
     # Configure the gem once per app, typically from
@@ -47,31 +40,15 @@ module StandardLedger
       @config ||= Config.new
     end
 
-    # Full reset: clears the cached `Config` AND any thread-local `with_modes`
-    # overrides. Use this when a spec needs to verify the gem's boot path or
-    # when the host has *not* installed a Rails initializer (so wiping
-    # `@config` is harmless). Hosts that *do* configure the gem in an
-    # initializer should not call this between examples — use
-    # `reset_mode_overrides!` instead, which the auto-cleanup hook already
-    # invokes.
+    # Clears the cached `Config`. Intended for specs that exercise the gem's
+    # boot path; hosts that configure the gem from an initializer should not
+    # call this between examples (it would undo their initializer config).
     def reset!
       @config = nil
-      reset_mode_overrides!
-    end
-
-    # Test-friendly reset that only clears the thread-local `with_modes`
-    # override map, leaving `Config` intact. The `standard_ledger/rspec`
-    # auto-cleanup hook calls this in `before(:each)` so a host's initializer
-    # config (e.g. a configured `result_adapter`) survives across examples
-    # while per-example mode overrides still get torn down cleanly.
-    def reset_mode_overrides!
-      Thread.current[:standard_ledger_mode_overrides] = nil
     end
 
     # Sugar over `EntryClass.create!` that maps `targets:` onto the entry's
-    # `belongs_to` foreign keys. Equivalent to calling `create!` directly
-    # with the assignments folded together — the inline projection callback
-    # fires from the same code path either way.
+    # `belongs_to` associations and wraps the outcome in a Result.
     #
     # @example
     #   StandardLedger.post(VoucherRecord,
@@ -94,11 +71,10 @@ module StandardLedger
     #   foreign key directly via `attrs:` (e.g. `voucher_scheme_id: 42`).
     # @param attrs [Hash] additional attributes merged into the create call.
     # @return [StandardLedger::Result, Object] the gem's Result, or the
-    #   host's Result type when `Config#custom_result?` is true. The Result's
-    #   `projections[:inline]` contains the target_association names of the
-    #   inline projections that actually ran for this entry — projections
-    #   skipped by an `if:` guard are excluded, and an idempotent retry
-    #   returns an empty array (no projections fire on the rescue path).
+    #   host's Result type when `Config#custom_result?` is true. `idempotent?`
+    #   is true when the create matched an existing row via the entry's
+    #   idempotency key. `projections` is always `{}` since 0.6.0; the key is
+    #   kept so existing `result_adapter` lambdas keep their signature.
     def post(entry_class, kind:, targets: {}, attrs: {})
       kind_column = resolve_kind_column(entry_class)
       create_attrs = build_create_attrs(entry_class, kind_column, kind, targets, attrs)
@@ -108,247 +84,76 @@ module StandardLedger
       build_result(
         success: true,
         entry: entry,
-        idempotent: entry.respond_to?(:idempotent?) && entry.idempotent?,
-        projections: { inline: applied_projections_for(entry) }
+        idempotent: entry.respond_to?(:idempotent?) && entry.idempotent?
       )
     rescue ActiveRecord::RecordInvalid => e
       build_result(success: false, entry: e.record, errors: e.record.errors.full_messages)
     end
 
-    # Force specific entry classes' projections to run in the supplied mode
-    # for the duration of the block. Intended for tests that want to drive an
-    # async-mode projection inline so the spec doesn't need a job runner.
-    #
-    # The override map is stored thread-locally so concurrent specs (or the
-    # gem's own `:async` workers) don't observe each other's overrides. Mode
-    # strategies consult `StandardLedger.mode_override_for(entry_class)`
-    # before falling back to the projection's declared mode.
-    #
-    # The block's prior override map is restored on exit, including on
-    # exception, so nested `with_modes` calls compose cleanly: the inner
-    # block's keys win during its scope, then the outer map is restored
-    # untouched.
-    #
-    # Today only `:inline` exists as a real mode, so this is a no-op for
-    # already-inline projections. The hook lands now so async projections
-    # can opt into the inline path the moment `Modes::Async` ships.
-    #
-    # @example
-    #   StandardLedger.with_modes(PaymentRecord => :inline) do
-    #     Orders::CheckoutOperation.call(...)
-    #   end
-    #
-    # @example string keys (resolved via const_get)
-    #   StandardLedger.with_modes("PaymentRecord" => :inline) do
-    #     ...
-    #   end
-    #
-    # @param overrides [Hash{Class, String, Symbol => Symbol}] entry class (or
-    #   constant name / underscored symbol) → forced mode symbol.
-    def with_modes(overrides)
-      resolved = resolve_mode_overrides(overrides)
-
-      prior = Thread.current[:standard_ledger_mode_overrides]
-      merged = (prior || {}).merge(resolved)
-      Thread.current[:standard_ledger_mode_overrides] = merged
-
-      yield
-    ensure
-      Thread.current[:standard_ledger_mode_overrides] = prior
-    end
-
-    # Read the active override (if any) for `entry_class`. Mode strategies
-    # call this in their `install!` / `#call` paths before deciding whether
-    # to dispatch to the declared mode or the override mode. Returns `nil`
-    # outside any `with_modes` block.
-    #
-    # @param entry_class [Class] the host entry class.
-    # @return [Symbol, nil] the override mode, or `nil` for "no override".
-    def mode_override_for(entry_class)
-      overrides = Thread.current[:standard_ledger_mode_overrides]
-      return nil if overrides.nil?
-
-      overrides[entry_class]
-    end
-
-    # Recompute projections from the entry log for one or more targets.
-    # The deterministic counterpart to `post`: instead of applying the
-    # delta from a single new entry, this replays the full log onto the
-    # target by delegating to the projector class's `rebuild(target)`.
-    #
-    # Scope (mutually exclusive — pass at most one):
-    #
-    # - `target:` — rebuild every projection whose `target_association`
-    #   resolves to `target.class`, for that single instance.
-    # - `target_class:` — rebuild every matching projection for every
-    #   target referenced by the log for that AR class, in `find_each`
-    #   batches. Targets with zero log entries are skipped (rebuilding a
-    #   target the log never touched would zero its counters — destructive
-    #   rather than corrective).
-    # - neither — rebuild every projection on `entry_class` for every
-    #   target referenced by the log.
-    #
-    # Per-mode rules:
-    #
-    # - `:inline` projections must be class-form (`via: ProjectorClass`)
-    #   AND that class must implement `rebuild`. Block-form projections
-    #   are delta-based — they cannot be reconstructed from the log
-    #   without the host providing a recompute path — so they raise
-    #   `StandardLedger::NotRebuildable` here.
-    # - `:matview` projections rebuild by issuing a single
-    #   `REFRESH MATERIALIZED VIEW [CONCURRENTLY] <view>` — for matview,
-    #   refresh *is* rebuild. Postgres has no partial-refresh primitive,
-    #   so `target:` / `target_class:` scope arguments are ignored for
-    #   `:matview` projections and the full view is always refreshed.
-    # - `:sql` and `:trigger` projections rebuild by running their
-    #   recorded rebuild SQL with `:target_id` bound to each target's
-    #   id. For `:trigger`, the database trigger fires on entry INSERT;
-    #   `rebuild!` runs the same logical recompute against each target
-    #   the log references. The gem does NOT verify or recreate the
-    #   trigger here — `standard_ledger:doctor` is the deploy-time
-    #   check for trigger presence.
-    # - `:async` projections rebuild via the same per-target semantics as
-    #   `:inline` (delegates to `definition.projector_class.new.rebuild(target)`).
-    #   The mode difference is only in the after-create path (in-transaction
-    #   vs. post-commit job), not in the rebuild path, which always runs
-    #   synchronously.
-    #
-    # Atomicity: each (target, projection) pair runs in its own
-    # transaction. A failure mid-loop is **not** rolled back — earlier
-    # successful rebuilds remain applied. Concurrent posts to the entry
-    # log during rebuild produce eventually-correct state: the rebuild
-    # operates on a snapshot of the log up to the projector's own
-    # SELECT, and any entries written after that snapshot project
-    # normally via the entry's own callback path. See design doc §5.5.
-    #
-    # @example rebuild a single target
-    #   StandardLedger.rebuild!(VoucherRecord, target: scheme)
-    #
-    # @example rebuild every scheme
-    #   StandardLedger.rebuild!(VoucherRecord, target_class: VoucherScheme)
-    #
-    # @example rebuild every projection across every target
-    #   StandardLedger.rebuild!(VoucherRecord)
-    #
-    # @param entry_class [Class] an `ActiveRecord::Base` subclass that
-    #   includes `StandardLedger::Projector`.
-    # @param target [ActiveRecord::Base, nil] one specific projection
-    #   target instance.
-    # @param target_class [Class, nil] rebuild for every target of this
-    #   AR class that the log references. Targets with zero log entries
-    #   are skipped.
-    # @param batch_size [Integer] passed to `find_each` when iterating
-    #   targets. Default 1000.
-    # @return [StandardLedger::Result, Object] success result with
-    #   `projections[:rebuilt] = [{ target_class:, target_id:,
-    #   projection: }, ...]`, one entry per (target, projection) pair
-    #   that ran. Failure result with `errors:` when any rebuild raises.
-    #   Returns the host's Result type when `Config#custom_result?` is
-    #   true, otherwise `StandardLedger::Result`.
-    # @raise [StandardLedger::NotRebuildable] when an applicable
-    #   projection has no rebuildable projector (block-form, or class
-    #   form whose `rebuild` raises `NotRebuildable`).
-    # @raise [StandardLedger::Error] when an applicable projection
-    #   declares a mode `rebuild!` does not yet support.
-    # @raise [ArgumentError] when both `target:` and `target_class:`
-    #   are supplied, when the entry class does not respond to
-    #   `standard_ledger_projections`, or when a non-nil scope
-    #   (`target:` / `target_class:`) matches no registered projection.
-    # @note Memory: when neither `target:` nor `target_class:` is given,
-    #   the no-scope and `target_class:` paths first load every distinct
-    #   foreign-key value from the log into memory via `distinct.pluck`
-    #   before batching the targets themselves. For very large logs,
-    #   prefer `target:` to scope to a single target rather than
-    #   rebuilding the full set.
-    def rebuild!(entry_class, target: nil, target_class: nil, batch_size: 1000)
-      if target && target_class
-        raise ArgumentError,
-              "rebuild! accepts at most one of `target:` or `target_class:` — got both"
-      end
-
-      unless entry_class.respond_to?(:standard_ledger_projections)
-        raise ArgumentError,
-              "#{entry_class.name || entry_class.inspect} does not include StandardLedger::Projector; " \
-              "rebuild! requires registered projections"
-      end
-
-      definitions = applicable_definitions_for_rebuild(entry_class, target: target, target_class: target_class)
-      validate_definitions_present!(entry_class, definitions, target: target, target_class: target_class)
-      rebuilt = []
-
-      definitions.each do |definition|
-        validate_rebuildable_mode!(entry_class, definition)
-
-        if definition.mode == :matview
-          rebuild_matview_definition(definition)
-          rebuilt << {
-            target_class: nil,
-            target_id:    nil,
-            projection:   definition.target_association,
-            view:         definition.view
-          }
-          next
-        end
-
-        validate_rebuildable_projector!(entry_class, definition)
-
-        each_rebuild_target(entry_class, definition, target: target, batch_size: batch_size) do |t|
-          if definition.mode == :sql || definition.mode == :trigger
-            rebuild_one_sql(entry_class, definition, t)
-          else
-            rebuild_one(entry_class, definition, t)
-          end
-          rebuilt << { target_class: t.class, target_id: t.id, projection: definition.target_association }
-        end
-      end
-
-      build_result(success: true, projections: { rebuilt: rebuilt })
-    rescue StandardLedger::Error, ArgumentError
-      # Programmer-error / unsupported-mode / not-rebuildable raises bubble
-      # up unchanged — these are deterministic, not data-dependent failures.
-      raise
-    rescue StandardError => e
-      # A projector raised mid-rebuild. Earlier successful rebuilds are
-      # NOT unwound (the contract is per-target transactional, not
-      # cross-target atomic) — we surface the failure but return.
-      build_result(success: false, errors: [ e.message ], projections: { rebuilt: rebuilt })
-    end
-
     # Refresh a host-owned materialized view. Issues
     # `REFRESH MATERIALIZED VIEW [CONCURRENTLY] <view_name>` against the
-    # active connection and emits the standard `<prefix>.projection.refreshed`
-    # notification on success (or `<prefix>.projection.failed` on raise,
-    # before re-raising — the host's scheduler / job runner needs to see the
-    # failure to drive its retry path).
-    #
-    # Two callers reach for this:
-    #
-    # - **Hosts**, after a critical write that needs read-your-write semantics
-    #   on a `:matview` projection (e.g. luminality's `PromptPacks::DrawOperation`
-    #   refreshes `user_prompt_inventories` at the end of the operation so the
-    #   user sees their post-draw count immediately, instead of waiting for
-    #   the next scheduled refresh).
-    # - **`StandardLedger::MatviewRefreshJob`**, the ActiveJob class hosts
-    #   point their scheduler at; that job is a thin wrapper around this
-    #   method.
+    # active connection and emits `<prefix>.projection.refreshed` on success.
+    # When the refresh SQL raises, it emits `<prefix>.projection.failed`,
+    # reports the error through `Rails.error` (`handled: false`,
+    # `severity: :error`, `context: { view:, concurrently: }`,
+    # `source: "standard_ledger"`) and re-raises, so the host's job runner
+    # still drives its retry path. Hosts don't need their own
+    # report-and-re-raise; Rails skips an exception it has already reported,
+    # so an existing one is harmless. Argument errors and
+    # `RefreshInsideTransaction` are programming errors raised before any
+    # SQL runs; they are not reported by the gem.
+    #
+    # @example scheduled job refreshing a list of views
+    #   VIEWS.each { |view| StandardLedger.refresh!(view, concurrently: :auto) }
     #
     # @param view_name [String, Symbol] the materialized view to refresh.
-    # @param concurrently [Boolean, nil] `nil` (default — read
-    #   `Config#matview_refresh_strategy`), `true` (force CONCURRENTLY), or
-    #   `false` (force a blocking refresh).
-    # @return [StandardLedger::Result, Object] success result on completion;
-    #   the host's Result type when `Config#custom_result?` is true. On SQL
-    #   failure the underlying exception propagates after the
-    #   `<prefix>.projection.failed` event fires.
+    #   Must be a bare or `schema.view` SQL identifier.
+    # @param concurrently [Boolean, Symbol, nil]
+    #   - `true` — force `CONCURRENTLY`. Raises `RefreshInsideTransaction`
+    #     inside an open transaction; Postgres raises if the view is empty
+    #     or has no suitable unique index.
+    #   - `false` — force a plain (blocking) refresh.
+    #   - `:auto` — use `CONCURRENTLY` only when it can succeed: no open
+    #     transaction, the view is populated, and it has a unique index
+    #     without a WHERE clause or expressions. Otherwise fall back to a
+    #     plain refresh. If the catalog probe itself fails, the error is
+    #     reported via `Rails.error` (handled) and a plain refresh runs.
+    #   - `nil` (default) — read `Config#matview_refresh_strategy`
+    #     (`:concurrent` => `true`, `:blocking` => `false`, `:auto` => `:auto`).
+    # @return [StandardLedger::Result, Object] success result with
+    #   `projections[:refreshed] = [{ view:, concurrently: }]`, where
+    #   `concurrently` is the resolved Boolean. The host's Result type when
+    #   `Config#custom_result?` is true.
+    # @raise [ArgumentError] when `view_name` is not a valid identifier or
+    #   `concurrently` is not one of the values above.
+    # @raise [StandardLedger::RefreshInsideTransaction] for
+    #   `concurrently: true` inside an open transaction.
     def refresh!(view_name, concurrently: nil)
-      effective = effective_concurrent_flag(concurrently)
-      Modes::Matview.refresh!(view_name, concurrently: effective)
+      effective = Matview.resolve_concurrently(view_name, requested_concurrently(concurrently))
+      Matview.refresh!(view_name, concurrently: effective)
       build_result(
         success: true,
         projections: { refreshed: [ { view: view_name.to_s, concurrently: effective } ] }
       )
     end
 
+    # Report +error+ through `Rails.error` (or `ActiveSupport.error_reporter`
+    # outside Rails) with `source: "standard_ledger"`. A reporter failure is
+    # swallowed so it can never mask the error being reported.
+    #
+    # @api private
+    def report_error(error, handled:, severity:, context:)
+      reporter =
+        if defined?(::Rails) && ::Rails.respond_to?(:error)
+          ::Rails.error
+        elsif ActiveSupport.respond_to?(:error_reporter)
+          ActiveSupport.error_reporter
+        end
+      reporter&.report(error, handled: handled, severity: severity, context: context, source: "standard_ledger")
+    rescue StandardError
+      nil
+    end
+
     private
 
     # Resolve the kind column name for an entry class. Falls back to `:kind`
@@ -359,11 +164,10 @@ module StandardLedger
       config ? config[:kind] : :kind
     end
 
-    # Translate `targets:` into the matching foreign-key assignments by
-    # routing each value through the entry's `belongs_to` setter (after
-    # confirming via `reflect_on_association` that the key is a real
-    # association). Targets must be ActiveRecord instances; raw foreign-key
-    # ids should be passed via `attrs:` instead (`<assoc>_id: ...`).
+    # Translate `targets:` into association assignments after confirming via
+    # `reflect_on_association` that each key is a real association. Targets
+    # must be ActiveRecord instances; raw foreign-key ids should be passed via
+    # `attrs:` instead (`<assoc>_id: ...`).
     def build_create_attrs(entry_class, kind_column, kind, targets, attrs)
       assigned = { kind_column => kind }
 
@@ -384,212 +188,26 @@ module StandardLedger
       assigned.merge(attrs)
     end
 
-    # Filter the entry class's registered projections down to the set
-    # whose target association class matches the requested scope.
-    # When neither `target:` nor `target_class:` is supplied, every
-    # registered projection is in scope.
-    #
-    # @return [Array<Projector::Definition>]
-    def applicable_definitions_for_rebuild(entry_class, target:, target_class:)
-      requested_class = target_class || target&.class
-      return entry_class.standard_ledger_projections.dup if requested_class.nil?
+    # Normalise the public `concurrently:` argument. `nil` defers to
+    # `Config#matview_refresh_strategy`; explicit values are honored verbatim
+    # so callers can override the default per call.
+    def requested_concurrently(concurrently)
+      value = concurrently.nil? ? strategy_to_flag(config.matview_refresh_strategy) : concurrently
+      return value if [ true, false, :auto ].include?(value)
 
-      entry_class.standard_ledger_projections.select do |definition|
-        association_target_class(entry_class, definition) == requested_class
-      end
+      raise ArgumentError,
+            "concurrently: must be true, false, :auto, or nil; got #{concurrently.inspect}"
     end
 
-    # An empty `definitions` set means either (a) the host called
-    # `rebuild!` on an entry class that has no `projects_onto`
-    # declarations at all, or (b) a non-nil scope (`target:` /
-    # `target_class:`) was passed but no registered projection points at
-    # that AR class. Both are programmer errors — silently returning
-    # `Result.success` with `rebuilt: []` would let the mistake go
-    # undetected. Raise so the caller hears about it.
-    def validate_definitions_present!(entry_class, definitions, target:, target_class:)
-      return unless definitions.empty?
-
-      requested_class = target_class || target&.class
-
-      if requested_class
-        raise ArgumentError,
-              "#{entry_class.name} has no projections matching #{requested_class.name}; " \
-              "check the `projects_onto` declarations on #{entry_class.name}."
+    def strategy_to_flag(strategy)
+      case strategy
+      when :concurrent then true
+      when :blocking then false
+      when :auto then :auto
       else
         raise ArgumentError,
-              "#{entry_class.name} has no projections registered; " \
-              "add a `projects_onto` declaration before calling rebuild!."
-      end
-    end
-
-    # Resolve the AR class on the far side of a projection's
-    # `target_association`. Used to match `target:` / `target_class:`
-    # against registered projections.
-    def association_target_class(entry_class, definition)
-      reflection = entry_class.reflect_on_association(definition.target_association)
-      return nil if reflection.nil?
-
-      reflection.klass
-    end
-
-    # All five projection modes (`:inline`, `:async`, `:sql`, `:matview`,
-    # `:trigger`) implement a log-replay path through this method.
-    #
-    # `:async` and `:inline` share the same per-target rebuild semantics —
-    # both delegate to `definition.projector_class.new.rebuild(target)`.
-    # The difference between the two modes is only in the after-create
-    # path (in-transaction vs. post-commit job), not in the rebuild path,
-    # which always runs synchronously.
-    def validate_rebuildable_mode!(entry_class, definition)
-      return if definition.mode == :inline
-      return if definition.mode == :async
-      return if definition.mode == :manual
-      return if definition.mode == :sql
-      return if definition.mode == :matview
-      return if definition.mode == :trigger
-
-      raise StandardLedger::Error,
-            "rebuild! does not yet support mode: #{definition.mode.inspect} " \
-            "on #{entry_class.name}##{definition.target_association}; " \
-            "this mode's rebuild path lands in its own PR"
-    end
-
-    # Rebuild a `:matview` projection by issuing a single REFRESH against
-    # the registered view. There's no per-target loop — the matview holds
-    # state for every target in a single relation, so one refresh is the
-    # entire rebuild.
-    def rebuild_matview_definition(definition)
-      concurrently = definition.refresh_options[:concurrently]
-      effective = effective_concurrent_flag(concurrently)
-      Modes::Matview.refresh!(definition.view, concurrently: effective)
-    end
-
-    # Reduce the public `concurrently:` parameter to a Boolean by reading
-    # `Config#matview_refresh_strategy` only when the caller passed `nil`.
-    # `true`/`false` are honored verbatim so callers can override the
-    # default per-call (e.g. an ad-hoc blocking refresh on a view whose
-    # default is concurrent).
-    def effective_concurrent_flag(concurrently)
-      return concurrently unless concurrently.nil?
-
-      config.matview_refresh_strategy == :concurrent
-    end
-
-    # Block-form `:inline` projections register per-kind handlers
-    # (e.g. `on(:grant) { increment(...) }`) that describe a delta.
-    # There's no general way to recompute the aggregate from the log
-    # without the host providing a recompute path — so we refuse
-    # rather than guess. Hosts who want this projection to be
-    # rebuildable should extract a `Projection` subclass and implement
-    # `rebuild(target)`.
-    def validate_rebuildable_projector!(entry_class, definition)
-      # `:sql` and `:trigger` modes carry their rebuild path in the
-      # recompute / rebuild SQL itself — no projector class is required
-      # (and `via:` is rejected at registration). Skip the class-form
-      # preflight checks below.
-      return if definition.mode == :sql
-      return if definition.mode == :trigger
-
-      if definition.projector_class.nil?
-        raise StandardLedger::NotRebuildable,
-              "#{entry_class.name}##{definition.target_association} is a block-form projection " \
-              "and cannot be rebuilt from the entry log. Implement a Projection subclass with " \
-              "`rebuild(target)` and pass it via `via:` to make this projection rebuildable."
+              "Config#matview_refresh_strategy must be :concurrent, :blocking, or :auto; got #{strategy.inspect}"
       end
-
-      # Best-effort early detection: catches the common "host forgot to
-      # override `rebuild`" case before we iterate any targets. The owner
-      # check is fragile for projectors that inherit `rebuild` from an
-      # intermediate mixin/superclass — the inherited `rebuild` may still
-      # raise `NotRebuildable` at runtime. The authoritative gate is the
-      # base `Projection#rebuild` implementation, which raises
-      # `NotRebuildable` itself; the rescue clause in `rebuild!` re-raises
-      # it unchanged. So a fragility miss here just means the failure
-      # surfaces at iteration-time instead of pre-flight, which is
-      # acceptable for v0.1.
-      return if definition.projector_class.instance_method(:rebuild).owner != StandardLedger::Projection
-
-      raise StandardLedger::NotRebuildable,
-            "#{definition.projector_class.name}#rebuild is not implemented; " \
-            "override it to recompute #{entry_class.name}##{definition.target_association} " \
-            "from the entry log."
-    end
-
-    # Yield each target in scope for this projection's rebuild. With
-    # an explicit `target:` we yield once; with `target_class:` or no
-    # scope, we walk every distinct foreign-key value in the log and
-    # `find_each` the corresponding rows in batches.
-    def each_rebuild_target(entry_class, definition, target:, batch_size:)
-      if target
-        yield target
-        return
-      end
-
-      reflection = entry_class.reflect_on_association(definition.target_association)
-      target_klass = reflection.klass
-      foreign_key = reflection.foreign_key
-
-      # Pluck the distinct ids referenced by the log so we don't
-      # rebuild for targets that have no entries against them. Cast
-      # through `compact` to skip null FKs (legitimate when the entry
-      # has an `if:` guard that may not apply).
-      ids = entry_class.where.not(foreign_key => nil).distinct.pluck(foreign_key)
-      return if ids.empty?
-
-      target_klass.where(id: ids).find_each(batch_size: batch_size) do |t|
-        yield t
-      end
-    end
-
-    # Run a single (target, projection) rebuild inside its own
-    # transaction, then fire `<prefix>.projection.rebuilt` on success
-    # so observers can track per-target rebuild progress.
-    def rebuild_one(entry_class, definition, target)
-      target.class.transaction do
-        definition.projector_class.new.rebuild(target)
-      end
-
-      prefix = config.notification_namespace
-      StandardLedger::EventEmitter.emit(
-        "#{prefix}.projection.rebuilt",
-        entry_class: entry_class, target: target,
-        projection: definition.target_association, mode: definition.mode
-      )
-    end
-
-    # `:sql` / `:trigger` mode rebuild path: run the recorded recompute
-    # SQL bound to this target's id. For `:sql` mode this is the same
-    # statement the `after_create` callback runs; for `:trigger` mode
-    # it's the rebuild SQL the host registered (the database trigger
-    # itself owns the after-INSERT path). Either way there's no
-    # projector class to invoke — the SQL is the entire contract.
-    def rebuild_one_sql(entry_class, definition, target)
-      target.class.transaction do
-        sql = ActiveRecord::Base.sanitize_sql_array([ definition.recompute_sql, { target_id: target.id } ])
-        entry_class.connection.exec_update(sql)
-      end
-
-      prefix = config.notification_namespace
-      StandardLedger::EventEmitter.emit(
-        "#{prefix}.projection.rebuilt",
-        entry_class: entry_class, target: target,
-        projection: definition.target_association, mode: definition.mode
-      )
-    end
-
-    # Names of the `:inline`-mode projections that actually ran for this
-    # entry — surfaced in `result.projections[:inline]` so callers can
-    # distinguish "applied now" from "queued" from "scheduled" (§7).
-    #
-    # `Modes::Inline#call` populates `@_standard_ledger_applied_projections`
-    # on the entry instance with the target_association names that ran
-    # (skipping projections whose `if:` guard returned false, whose target
-    # was nil, or whose permissive miss didn't hit a `:_` wildcard). When
-    # the ivar isn't present — e.g. an idempotent rescue returned an
-    # existing row without firing `after_create` — we report an empty
-    # list, which accurately reflects that no projections ran on this call.
-    def applied_projections_for(entry)
-      Array(entry.instance_variable_get(:@_standard_ledger_applied_projections))
     end
 
     # Construct a Result via the host's adapter when configured, otherwise
@@ -607,37 +225,5 @@ module StandardLedger
         Result.failure(errors: errors, entry: entry, projections: projections)
       end
     end
-
-    # Resolve override-map keys to actual class constants so callers can
-    # write `with_modes(PaymentRecord => :inline)` *or*
-    # `with_modes(:payment_record => :inline)`. The String/Symbol form uses
-    # `String#classify` then `Object.const_get`; the Class form is passed
-    # through verbatim. Anything else raises so the caller fixes the typo
-    # rather than silently storing a key that nothing will ever match.
-    #
-    # An unresolvable String/Symbol key (typo: `:payment_recrd`) is caught
-    # and re-raised as `ArgumentError` with a `with_modes:`-prefixed message
-    # naming the offending key, rather than leaking `const_get`'s bare
-    # `NameError: uninitialized constant ...`.
-    def resolve_mode_overrides(overrides)
-      overrides.each_with_object({}) do |(key, mode), memo|
-        klass =
-          case key
-          when Class
-            key
-          when String, Symbol
-            begin
-              Object.const_get(key.to_s.classify)
-            rescue NameError
-              raise ArgumentError,
-                    "with_modes: could not resolve #{key.inspect} to a constant"
-            end
-          else
-            raise ArgumentError,
-                  "with_modes: expected Class, String, or Symbol key; got #{key.inspect}"
-          end
-        memo[klass] = mode
-      end
-    end
   end
 end