standard_ledger 0.2.0

data/lib/generators/standard_ledger/install/templates/initializer.rb.tt

@@ -0,0 +1,66 @@
+# StandardLedger configuration
+# Generated by: rails g standard_ledger:install
+#
+# StandardLedger captures the recurring "immutable journal entry → N
+# aggregate projections" pattern as a declarative DSL on host ActiveRecord
+# models. See https://github.com/rarebit-one/standard_ledger for the gem
+# README.
+#
+# All commented-out lines below show the public DSL — uncomment and edit
+# the ones that apply to your app.
+
+StandardLedger.configure do |c|
+  # ---------------------------------------------------------------------------
+  # Async mode
+  # ---------------------------------------------------------------------------
+
+  # The ActiveJob class used by `:async` mode projections. Defaults to
+  # `StandardLedger::ProjectionJob`. Hosts can supply their own job class
+  # (e.g. for custom queue routing or per-projection telemetry).
+  # Default: nil (resolved lazily to StandardLedger::ProjectionJob)
+  # c.default_async_job = Orders::FulfillableProjectionJob
+
+  # Number of times an `:async` projection will retry before dead-lettering.
+  # Default: 3.
+  # c.default_async_retries = 3
+
+  # ---------------------------------------------------------------------------
+  # Matview mode
+  # ---------------------------------------------------------------------------
+
+  # Scheduler backend for `:matview` refresh jobs.
+  # One of :solid_queue, :sidekiq_cron, :custom. Default: :solid_queue.
+  # c.scheduler = :solid_queue
+
+  # Default refresh strategy for `:matview` projections.
+  # :concurrent (REFRESH MATERIALIZED VIEW CONCURRENTLY — requires a unique
+  # index on the view) or :blocking. Default: :concurrent.
+  # c.matview_refresh_strategy = :concurrent
+
+  # ---------------------------------------------------------------------------
+  # Notifications
+  # ---------------------------------------------------------------------------
+
+  # Prefix for ActiveSupport::Notifications events emitted by the gem.
+  # Default: "standard_ledger". Events:
+  #   <prefix>.entry.created
+  #   <prefix>.projection.applied
+  #   <prefix>.projection.failed
+  # c.notification_namespace = "standard_ledger"
+
+  # ---------------------------------------------------------------------------
+  # Host Result interop
+  # ---------------------------------------------------------------------------
+  # Optional: return the host's Result type from StandardLedger.post.
+  # When both result_class and result_adapter are set, post() returns
+  # instances of result_class via the adapter; otherwise it returns
+  # StandardLedger::Result.
+  #
+  # The adapter receives keyword args:
+  #   success:, value:, errors:, entry:, idempotent:, projections:
+  #
+  # c.result_class   = ApplicationOperation::Result
+  # c.result_adapter = ->(success:, value:, errors:, entry:, idempotent:, projections:) {
+  #   ApplicationOperation::Result.new(success:, value: value || entry, errors:)
+  # }
+end

data/lib/standard_ledger/config.rb

@@ -0,0 +1,62 @@
+module StandardLedger
+  # Host-configurable settings, populated via `StandardLedger.configure { |c| ... }`
+  # in an initializer. All attributes have sensible defaults; hosts only override
+  # what they need.
+  #
+  # @see StandardLedger.configure
+  class Config
+    # The ActiveJob class used by `:async` mode projections. Defaults to
+    # `StandardLedger::ProjectionJob`. Hosts can supply their own job class
+    # (e.g. for custom queue routing or per-projection telemetry) via
+    # `c.default_async_job = Orders::FulfillableProjectionJob`.
+    attr_accessor :default_async_job
+
+    # Number of times an `:async` projection will retry before dead-lettering.
+    # Default: 3.
+    attr_accessor :default_async_retries
+
+    # Scheduler backend for `:matview` refresh jobs. One of
+    # `:solid_queue`, `:sidekiq_cron`, `:custom`. Default: `:solid_queue`
+    # (matches all four consuming apps).
+    attr_accessor :scheduler
+
+    # Default refresh strategy for `:matview` projections. Either
+    # `:concurrent` (REFRESH MATERIALIZED VIEW CONCURRENTLY — requires a
+    # unique index on the view) or `:blocking`. Default: `:concurrent`.
+    attr_accessor :matview_refresh_strategy
+
+    # Optional: the host application's Result class. When set together with
+    # `result_adapter`, `StandardLedger.post` returns instances of this class
+    # instead of `StandardLedger::Result`.
+    attr_accessor :result_class
+
+    # Optional: a callable that translates the gem's result fields into the
+    # host's Result type. Receives keyword args:
+    # `success:, value:, errors:, entry:, idempotent:, projections:`.
+    # Required when `result_class` is set.
+    attr_accessor :result_adapter
+
+    # Prefix for `ActiveSupport::Notifications` events emitted by the gem.
+    # Default: `"standard_ledger"`. Events:
+    # `<prefix>.entry.created`, `<prefix>.projection.applied`,
+    # `<prefix>.projection.failed`, `<prefix>.projection.refreshed`,
+    # `<prefix>.projection.rebuilt`.
+    attr_accessor :notification_namespace
+
+    def initialize
+      @default_async_job        = nil   # resolved lazily to avoid loading the job constant before Rails boots
+      @default_async_retries    = 3
+      @scheduler                = :solid_queue
+      @matview_refresh_strategy = :concurrent
+      @result_class             = nil
+      @result_adapter           = nil
+      @notification_namespace   = "standard_ledger"
+    end
+
+    # True when the host has wired up its own Result type. When false, the gem
+    # returns its built-in `StandardLedger::Result`.
+    def custom_result?
+      !result_class.nil? && !result_adapter.nil?
+    end
+  end
+end

data/lib/standard_ledger/engine.rb

@@ -0,0 +1,19 @@
+module StandardLedger
+  # Boot hook for Rails apps. The engine registers no routes and provides no
+  # tables — its only role is to ensure the gem's notification subscribers
+  # (if any are registered by the host) are wired up after the host's
+  # initializers have finished running.
+  #
+  # We hook `after: :load_config_initializers` so any host-side
+  # `StandardLedger.configure` block in `config/initializers/*` has finished
+  # before subscribers are attached.
+  class Engine < ::Rails::Engine
+    isolate_namespace StandardLedger
+
+    initializer "standard_ledger.notifications", after: :load_config_initializers do
+      # Notification wiring lands here in a follow-up PR. Today this is a
+      # no-op — the gem emits events but ships no internal subscribers; hosts
+      # subscribe directly via ActiveSupport::Notifications.subscribe.
+    end
+  end
+end

data/lib/standard_ledger/entry.rb

@@ -0,0 +1,253 @@
+require "active_support/concern"
+
+module StandardLedger
+  # Marks an ActiveRecord model as a ledger entry: an immutable, append-only
+  # row that may project onto one or more aggregate targets.
+  #
+  # Including this concern installs:
+  #   - the `ledger_entry` class macro (declares immutability + idempotency)
+  #   - read-only behavior post-creation (when `immutable: true`, the default)
+  #   - idempotency-by-unique-index (when `idempotency_key:` is non-nil)
+  #
+  # Projection registration happens via the separate `Projector` concern —
+  # the two are decoupled so that an entry can be marked immutable without
+  # also opting into projections, and vice versa.
+  #
+  # @example
+  #   class VoucherRecord < ApplicationRecord
+  #     include StandardLedger::Entry
+  #
+  #     ledger_entry kind:            :action,
+  #                  idempotency_key: :serial_no,
+  #                  scope:           :organisation_id
+  #   end
+  module Entry
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Declare the entry's contract. Stores the configuration on the class
+      # for later inspection by `StandardLedger.post`, `Projection.rebuild!`,
+      # and the `standard_ledger:doctor` rake task.
+      #
+      # @param kind [Symbol] the column holding the entry's kind/action
+      #   discriminator. Defaults to `:kind`.
+      # @param idempotency_key [Symbol, nil] the column whose unique index
+      #   guards against duplicate inserts. `nil` means the entry is not
+      #   idempotent — explicitly opt-in to that.
+      # @param scope [Symbol, Array<Symbol>, nil] additional columns the
+      #   idempotency index is scoped by (e.g. `:organisation_id`).
+      # @param immutable [Boolean] when true (default), `save`/`update`/
+      #   `destroy` raise after the row is persisted.
+      def ledger_entry(kind: :kind, idempotency_key: nil, scope: nil, immutable: true)
+        self.standard_ledger_entry_config = {
+          kind: kind,
+          idempotency_key: idempotency_key,
+          scope: Array(scope).compact,
+          immutable: immutable
+        }
+        self.standard_ledger_idempotency_index_validated = false
+      end
+
+      def standard_ledger_entry?
+        !standard_ledger_entry_config.nil?
+      end
+
+      # Override AR's `create!` to add idempotency-by-unique-index semantics.
+      # When the configured unique constraint trips, look up and return the
+      # existing row with `idempotent? == true` instead of raising.
+      #
+      # @note Block-form `create! { |r| r.field = val }` is not supported for
+      #   the idempotent rescue: AR passes `attributes = nil` in that path so
+      #   we can't construct the find_by lookup. The rescue still functions
+      #   for the rest of the create — a colliding insert from a block-form
+      #   call simply re-raises `RecordNotUnique` like vanilla ActiveRecord.
+      def create!(attributes = nil, &block)
+        config = standard_ledger_entry_config
+        return super if config.nil? || config[:idempotency_key].nil?
+
+        validate_standard_ledger_idempotency_index!
+
+        super
+      rescue ActiveRecord::RecordNotUnique => e
+        raise unless standard_ledger_idempotency_violation?(e)
+
+        existing = find_existing_standard_ledger_entry(attributes)
+        raise if existing.nil?
+
+        existing.instance_variable_set(:@_standard_ledger_idempotent, true)
+        existing
+      end
+
+      # Verify that the table has a unique index covering exactly
+      # `[*scope, idempotency_key]` (column set equality; order-insensitive).
+      # Cached so the introspection runs once per class.
+      #
+      # The check-then-set on `standard_ledger_idempotency_index_validated`
+      # has a benign race: two threads can both observe `false`, both run the
+      # introspection, and both flip the flag to `true`. That's intentional
+      # — the validation is pure and idempotent, so duplicate work is cheap
+      # and the result is identical. No mutex needed; do not add one.
+      def validate_standard_ledger_idempotency_index!
+        return if standard_ledger_idempotency_index_validated
+
+        config = standard_ledger_entry_config
+        return if config.nil? || config[:idempotency_key].nil?
+
+        required = (config[:scope] + [ config[:idempotency_key] ]).map(&:to_s).to_set
+        indexes  = connection.indexes(table_name)
+
+        match = indexes.any? do |index|
+          index.unique && index.columns.map(&:to_s).to_set == required
+        end
+
+        unless match
+          raise StandardLedger::MissingIdempotencyIndex,
+                "#{name} declares idempotency_key: #{config[:idempotency_key].inspect} " \
+                "with scope: #{config[:scope].inspect} but no matching unique index " \
+                "covers exactly #{required.to_a.sort.inspect} on `#{table_name}`."
+        end
+
+        self.standard_ledger_idempotency_index_validated = true
+      end
+
+      private
+
+      def find_existing_standard_ledger_entry(attributes)
+        return nil if attributes.nil?
+
+        config = standard_ledger_entry_config
+        lookup_columns = config[:scope] + [ config[:idempotency_key] ]
+        attrs = attributes.is_a?(Hash) ? attributes.transform_keys(&:to_sym) : {}
+        lookup = lookup_columns.each_with_object({}) do |col, memo|
+          memo[col] = attrs[col.to_sym]
+        end
+
+        # Bail if any lookup value is nil — `find_by` would emit
+        # `WHERE col IS NULL` and could match an unrelated row whose column
+        # legitimately holds NULL. We require all idempotency columns to be
+        # present in `attributes` to make a confident match.
+        return nil if lookup.any? { |_, value| value.nil? }
+
+        find_by(lookup)
+      end
+
+      # Confirm the RecordNotUnique was raised by *our* idempotency index,
+      # not some other unique constraint on the table (surrogate key,
+      # business column, etc.). The wrapped DB exception's message usually
+      # mentions the index name or the column list — a substring match on
+      # each idempotency column name is good enough across PostgreSQL and
+      # SQLite without parsing vendor-specific formats.
+      #
+      # Adapter caveat: MySQL's unique-violation message contains only the
+      # index name (e.g. `Duplicate entry 'val' for key 'idx_name'`), not
+      # the column list. So this check returns false on MySQL unless the
+      # index is named after its columns. The fail-closed behavior re-raises
+      # the original RecordNotUnique, which is the correct outcome for an
+      # unrecognized violation — never the wrong one for a misclassified
+      # one. None of the host apps target MySQL today; revisit if that
+      # changes.
+      def standard_ledger_idempotency_violation?(exception)
+        config = standard_ledger_entry_config
+        columns = (config[:scope] + [ config[:idempotency_key] ]).map(&:to_s)
+        message = String(exception.message) + String(exception.cause&.message)
+
+        columns.all? { |col| message.include?(col) }
+      end
+    end
+
+    included do
+      class_attribute :standard_ledger_entry_config, instance_writer: false
+      class_attribute :standard_ledger_idempotency_index_validated, instance_writer: false
+      self.standard_ledger_entry_config = nil
+      self.standard_ledger_idempotency_index_validated = false
+
+      # The destroy guard only matters for AR includers (the production case);
+      # plain Ruby classes that include Entry for testing the DSL surface
+      # get the macro registration without the callback. AR's `readonly?`
+      # path covers save/update on persisted rows; this catch-all stops
+      # `destroy` for the AR case.
+      if respond_to?(:before_destroy)
+        before_destroy :standard_ledger_raise_readonly, if: :standard_ledger_immutable?
+      end
+
+      # Emit `<namespace>.entry.created` after the row is durably committed
+      # so subscribers (audit logs, metric pipelines) see it only when the
+      # entry is real. Idempotent returns from `create!`'s rescue do not
+      # fire `after_commit on: :create` (no INSERT happened), which is the
+      # correct behavior: the original write fired the event already.
+      if respond_to?(:after_commit)
+        after_commit :standard_ledger_emit_entry_created, on: :create
+      end
+    end
+
+    # Returns true when this row was returned from an idempotent `create!`
+    # rescue — i.e. an existing row matched the unique constraint and was
+    # returned instead of inserted.
+    def idempotent?
+      !!@_standard_ledger_idempotent
+    end
+
+    # AR consults `readonly?` from `save`/`update` paths; raising
+    # ReadOnlyRecord here matches the ActiveRecord contract for persisted
+    # immutable rows. New, unpersisted instances stay writable so the
+    # initial INSERT can land.
+    def readonly?
+      return super unless standard_ledger_immutable?
+
+      !new_record?
+    end
+
+    # Returns the entry's belongs_to targets keyed by association name.
+    # Used by the `entry.created` notification payload and by
+    # `StandardLedger.post`'s telemetry. Skips polymorphic and missing
+    # associations so the payload only includes what's actually present.
+    #
+    # Performance trade-off: this fires from `after_commit`, where AR may
+    # have cleared the association cache. Each `public_send(reflection.name)`
+    # can therefore issue a SELECT to reload the cached target. For the
+    # typical 1–2 belongs_to entry, that's negligible. If profiling on a
+    # high-cardinality entry shows this matters, capture targets earlier
+    # (e.g. in `before_create`) and stash them on the instance — deferred
+    # to a future PR. Notably, an inline-mode caller has already resolved
+    # these targets by the time `after_commit` runs, so the SELECTs would
+    # only happen for entries with belongs_to associations that are *not*
+    # registered as projection targets.
+    #
+    # @return [Hash{Symbol => ActiveRecord::Base}]
+    def standard_ledger_targets
+      return {} unless self.class.respond_to?(:reflect_on_all_associations)
+
+      self.class.reflect_on_all_associations(:belongs_to).each_with_object({}) do |reflection, memo|
+        next if reflection.polymorphic?
+
+        target = public_send(reflection.name)
+        memo[reflection.name] = target unless target.nil?
+      end
+    end
+
+    private
+
+    def standard_ledger_immutable?
+      config = self.class.standard_ledger_entry_config
+      !config.nil? && config[:immutable]
+    end
+
+    def standard_ledger_raise_readonly
+      raise ActiveRecord::ReadOnlyRecord
+    end
+
+    # Publish `<namespace>.entry.created` once the row is durably committed.
+    # `after_commit on: :create` only fires for real INSERTs, so idempotent
+    # returns from the `create!` rescue path are correctly skipped.
+    def standard_ledger_emit_entry_created
+      config = self.class.standard_ledger_entry_config
+      kind_value = config ? public_send(config[:kind]) : nil
+      prefix = StandardLedger.config.notification_namespace
+
+      StandardLedger::EventEmitter.emit(
+        "#{prefix}.entry.created",
+        entry: self, kind: kind_value, targets: standard_ledger_targets
+      )
+    end
+  end
+end

data/lib/standard_ledger/errors.rb

@@ -0,0 +1,33 @@
+module StandardLedger
+  class Error < StandardError; end
+
+  # Raised at registration time when a `projects_onto` block declares an
+  # `on(:kind)` for a kind that the entry's enum/set does not include, or
+  # when an entry is posted with a kind that no projection has registered
+  # a handler for. Use `permissive: true` on the projection to opt out.
+  class UnhandledKind < Error; end
+
+  # Raised by `StandardLedger.rebuild!` when the projector does not implement
+  # `rebuild` and is therefore not replayable from the entry log. Delta-based
+  # projectors (e.g. `increment_counter`-flavored) typically raise this
+  # because they cannot be reconstructed without summing the full log.
+  class NotRebuildable < Error; end
+
+  # Raised at boot when an Entry declares `idempotency_key:` but no matching
+  # unique index exists on the entry table. Caught early instead of silently
+  # admitting duplicates at runtime.
+  class MissingIdempotencyIndex < Error; end
+
+  # Raised by `StandardLedger.post` when the inline portion of fan-out
+  # succeeded but enqueuing one or more async projections failed. The entry
+  # itself is durable; callers may choose to roll back or accept-and-log.
+  class PartialFailure < Error
+    attr_reader :enqueued, :failed
+
+    def initialize(enqueued:, failed:)
+      @enqueued = enqueued
+      @failed = failed
+      super("Enqueued #{enqueued.size} projections; #{failed.size} failed to enqueue")
+    end
+  end
+end

data/lib/standard_ledger/event_emitter.rb

@@ -0,0 +1,50 @@
+module StandardLedger
+  # Internal helper that emits StandardLedger lifecycle events through whichever
+  # event reporter is live in the host process.
+  #
+  # - On Rails 8.1+, `Rails.event.notify(name, **payload)` is the canonical bus.
+  # - On older Rails (or any host without the structured reporter), we fall back
+  #   to `ActiveSupport::Notifications.instrument(name, payload)`.
+  #
+  # Detection is performed at *call time* — the gem is required before Rails has
+  # finished booting, so we cannot cache the decision at load time.
+  #
+  # @api private
+  module EventEmitter
+    module_function
+
+    # Emit a single event. Both backends are best-effort: any exception raised
+    # by a subscriber is swallowed so ledger observability never takes down a
+    # host's request path (the projection has already either succeeded or
+    # been rolled back by the time we emit).
+    def emit(event_name, payload)
+      if (bus = rails_event_bus)
+        bus.notify(event_name, **payload)
+      else
+        ::ActiveSupport::Notifications.instrument(event_name, payload)
+      end
+    rescue => e
+      warn "[StandardLedger] event emit for #{event_name.inspect} failed: #{e.class}: #{e.message}"
+    end
+
+    # Returns the Rails 8.1+ structured event bus when available, or `nil`
+    # to signal the AS::Notifications fallback. Single accessor so `emit`
+    # invokes `Rails.event` only once per call.
+    def rails_event_bus
+      return nil unless defined?(::Rails) &&
+                        ::Rails.respond_to?(:event) &&
+                        ::Rails.event.respond_to?(:notify)
+
+      ::Rails.event
+    end
+
+    # Boolean shorthand kept for callers (and specs) that just want to know
+    # whether the modern bus is live.
+    def rails_event_available?
+      !rails_event_bus.nil?
+    end
+
+    # Hides the singleton copy that `module_function` generated above.
+    private_class_method :rails_event_bus
+  end
+end

data/lib/standard_ledger/jobs/matview_refresh_job.rb

@@ -0,0 +1,28 @@
+require "active_job"
+
+module StandardLedger
+  # Thin ActiveJob wrapper that delegates to `StandardLedger.refresh!`. Hosts
+  # point their scheduler (SolidQueue Recurring Tasks, sidekiq-cron, etc.) at
+  # this job class with the view name as the argument. The gem deliberately
+  # does not auto-schedule — schedule cadence and backend selection is a host
+  # concern (the host's scheduler config has the wider context: queue routing,
+  # recurring task DSL, etc.).
+  #
+  # The job runs on ActiveJob's `:default` queue. Hosts running high-frequency
+  # refreshes (e.g. every minute) on a shared `:default` queue may want to
+  # isolate matview refreshes onto a dedicated queue so a slow refresh doesn't
+  # starve other latency-sensitive jobs — subclass and override `queue_as`
+  # (e.g. `queue_as :standard_ledger`) and point the scheduler at the
+  # subclass.
+  #
+  # @example SolidQueue Recurring Tasks (config/recurring.yml)
+  #   refresh_user_prompt_inventories:
+  #     class: StandardLedger::MatviewRefreshJob
+  #     args: ["user_prompt_inventories", { concurrently: true }]
+  #     schedule: "every 5 minutes"
+  class MatviewRefreshJob < ::ActiveJob::Base
+    def perform(view_name, concurrently: nil)
+      StandardLedger.refresh!(view_name, concurrently: concurrently)
+    end
+  end
+end