standard_ledger 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 276066f9976675bcd6ed7220d0df2d72518c355eab43036807cf53c1c1da7e00
-  data.tar.gz: 01de25809973bb72ed2414f32f5c6c9398f45f2d44fed75bfdb1743c9beaaedc
+  metadata.gz: 411ad3db9a71ca8adddecc84d407dabddbd167c7ed00e534e975a700b3a2e8f2
+  data.tar.gz: aeb938a4e1fb16c6df67fbb76a93a5687c40116be040df5da44e65541ce4d282
 SHA512:
-  metadata.gz: bc772c009801e0bf6ab2e3568e95aeff7305413fce076742d89dfb62388cada99a168659fc0745807ca661c31bd30cc33529b105c4f7bd163a91090d3b5603ab
-  data.tar.gz: 1002bacfe4f93410a2d06ffda6dec585328c0c248d518f3e0e12148a9bd5effb451f02dbb1967569b3e2d30b3d8c71bcc4abba53efa7e41d218f451ee21d659c
+  metadata.gz: 2d0cd11b66c8d22b76cf9444e8840d92c35ccd81d4eba224e8123b208aa5c706503bc9cf6e9bbf1dc7bff564df4728adac79eeeacc254a976efb8cfa1fd0907a
+  data.tar.gz: 5f352fe00a36e01ef43aa4d8efb197a32314c43f0b31657342996dc91bcf422933e4076b851813bd6c6fd7ab69a52d18f53e9650fbced76292b9deca52b6ce0b

data/CHANGELOG.md

@@ -8,6 +8,57 @@ project adheres to [Semantic Versioning](https://semver.org/).
 
 Nothing yet.
 
+## [0.4.0] - 2026-05-07
+
+### Added
+- New `:manual` projection mode. Records the projection contract
+  (target + projector class) without installing any callback —
+  intended for AASM/state-machine entries whose interesting lifecycle
+  event is a transition rather than `after_create`. Hosts invoke the
+  projector explicitly from operation code; the gem keeps the
+  contract introspectable (`standard_ledger_projections`) and
+  log-replayable via `StandardLedger.rebuild!`. Requires
+  `via: ProjectorClass`; rejects blocks, locks, and `permissive:`.
+- New `allow_destroy:` keyword on `ledger_entry`. When `true`, an
+  immutable entry permits `destroy` (including `dependent: :destroy`
+  cascades from a parent record) while still blocking `save`/`update`.
+  The default is `false` — preserves the strict journal contract.
+  Use this when an owning record's destroy cascade needs to reap
+  events for sandbox tear-down or GDPR erasure.
+- New `counters:` shortcut for `:inline` projections. A
+  `kind => column` Hash 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, keeping
+  multiple sibling-entry creates inside 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.
+- New `rebuild_sql:` keyword on `:trigger` mode. Equivalent to the
+  block-DSL `rebuild_sql "..."` clause, callable without a block.
+- Partial unique indexes are now accepted by the idempotency-index
+  validator when their predicate is the canonical
+  `<idempotency_key> IS NOT NULL` shape. Other predicates still raise
+  `MissingIdempotencyIndex` with a clearer error message.
+- New `StandardLedger::RefreshInsideTransaction` error. Raised when
+  `StandardLedger.refresh!(view, concurrently: true)` is called
+  inside an open transaction — Postgres rejects
+  `REFRESH MATERIALIZED VIEW CONCURRENTLY` inside transaction blocks,
+  and the gem now catches this at the boundary instead of letting
+  `PG::ActiveSqlTransaction` escape mid-call. The non-concurrent
+  form is still permitted by Postgres inside transactions and is
+  unaffected. No SQL is issued and no `.refreshed`/`.failed` event
+  fires when the guard rejects.
+- `docs/MIGRATION_GUIDE.md` covering the five real-world adoption
+  paths (counter caches, custom inline logic, bespoke jobs, existing
+  Postgres triggers, AASM state machines) and the cascade-delete /
+  refresh-in-transaction edge cases.
+
+### Documentation
+- `ledger_entry`'s YARD now notes that a single-symbol `scope:` is
+  normalised to a flat array on the stored config; assertions in
+  host specs should compare against `[:foo]`, not `:foo`.
+
 ## [0.3.0] - 2026-05-05
 
 ### Added

data/lib/standard_ledger/entry.rb

@@ -35,15 +35,29 @@ module StandardLedger
       #   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)
+      #   idempotency index is scoped by (e.g. `:organisation_id`). Always
+      #   normalised to a flat array on the stored config so downstream
+      #   reads don't need to handle both shapes — assertions in host specs
+      #   should compare against `[:foo]`, not `:foo`.
+      # @param immutable [Boolean] when true (default), `save`/`update`
+      #   raise after the row is persisted. Also blocks `destroy` unless
+      #   `allow_destroy: true` is set.
+      # @param allow_destroy [Boolean] when true, `destroy` (including
+      #   `dependent: :destroy` cascades from a parent record) is permitted
+      #   even on `immutable: true` entries. Use this when an owning record
+      #   declares `has_many :events, dependent: :destroy` and you want the
+      #   cascade to work for cleanup paths (sandbox tear-down, GDPR
+      #   erasure, etc.) while still blocking app-code mutations to
+      #   persisted entries. Defaults to `false` — keeping the strict
+      #   journal contract.
+      def ledger_entry(kind: :kind, idempotency_key: nil, scope: nil,
+                       immutable: true, allow_destroy: false)
         self.standard_ledger_entry_config = {
           kind: kind,
           idempotency_key: idempotency_key,
           scope: Array(scope).compact,
-          immutable: immutable
+          immutable: immutable,
+          allow_destroy: allow_destroy
         }
         self.standard_ledger_idempotency_index_validated = false
       end
@@ -97,14 +111,28 @@ module StandardLedger
         indexes  = connection.indexes(table_name)
 
         match = indexes.any? do |index|
-          index.unique && index.columns.map(&:to_s).to_set == required
+          next false unless index.unique
+          next false unless index.columns.map(&:to_s).to_set == required
+
+          # Full-table unique indexes are always valid. Partial indexes are
+          # accepted only when the predicate is the canonical
+          # `<idempotency_key> IS NOT NULL` shape — that's the common
+          # real-world pattern (e.g. an event table whose serial number is
+          # optional but unique-per-scope when present), and it preserves
+          # the gem's idempotency contract: rows with a non-null key are
+          # deduped; rows without one are explicitly opting out.
+          standard_ledger_index_predicate_acceptable?(index, config[:idempotency_key])
         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}`."
+                "covers exactly #{required.to_a.sort.inspect} on `#{table_name}`. " \
+                "If a matching partial index exists, its WHERE predicate must be " \
+                "`#{config[:idempotency_key]} IS NOT NULL` (other predicates aren't " \
+                "automatically validated — opt out of the check by setting " \
+                "idempotency_key: nil and enforcing uniqueness another way)."
         end
 
         self.standard_ledger_idempotency_index_validated = true
@@ -112,6 +140,29 @@ module StandardLedger
 
       private
 
+      # Match a partial-index predicate of the form `<col> IS NOT NULL`
+      # (with optional whitespace and optional table/schema qualification
+      # on the column reference). Full-table indexes (no predicate) always
+      # qualify. This is conservative: predicates outside this shape can
+      # still be perfectly valid for the host's idempotency intent, but
+      # we'd need a real SQL parser to decide that — better to raise and
+      # let the host either restructure their index or opt out via
+      # `idempotency_key: nil`.
+      def standard_ledger_index_predicate_acceptable?(index, idempotency_key)
+        predicate = index.where
+        return true if predicate.nil? || predicate.to_s.strip.empty?
+
+        col = idempotency_key.to_s
+        # Postgres wraps the index predicate in parentheses when it returns
+        # it via pg_indexes (e.g. `(idempotency_key IS NOT NULL)`) — strip
+        # those along with the per-adapter quoting characters before
+        # matching. SQLite returns the raw expression, so the same strip is
+        # a no-op there. The regex tolerates whitespace around the column
+        # and operator and accepts an optional table-qualifier prefix.
+        normalised = predicate.to_s.gsub(/["`\[\]()]/, "").strip
+        normalised.match?(/\A([\w]+\.)?#{Regexp.escape(col)}\s+IS\s+NOT\s+NULL\z/i)
+      end
+
       def find_existing_standard_ledger_entry(attributes)
         return nil if attributes.nil?
 
@@ -165,9 +216,11 @@ module StandardLedger
       # 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.
+      # `destroy` for the AR case unless the entry opts out via
+      # `allow_destroy: true` (typically because an owning record's
+      # `dependent: :destroy` cascade needs to reap them on cleanup).
       if respond_to?(:before_destroy)
-        before_destroy :standard_ledger_raise_readonly, if: :standard_ledger_immutable?
+        before_destroy :standard_ledger_raise_readonly, if: :standard_ledger_destroy_blocked?
       end
 
       # Emit `<namespace>.entry.created` after the row is durably committed
@@ -187,16 +240,40 @@ module StandardLedger
       !!@_standard_ledger_idempotent
     end
 
-    # AR consults `readonly?` from `save`/`update` paths; raising
+    # AR consults `readonly?` from `save`/`update`/`destroy` paths; raising
     # ReadOnlyRecord here matches the ActiveRecord contract for persisted
     # immutable rows. New, unpersisted instances stay writable so the
     # initial INSERT can land.
+    #
+    # When `allow_destroy: true` is set, `#destroy` toggles
+    # `@_standard_ledger_destroying` so `readonly?` returns false for the
+    # duration of the destroy call (and the duration of any cascade
+    # destroys that fire from its `dependent: :destroy` associations).
+    # The save/update path is unaffected — those still raise on
+    # persisted rows.
     def readonly?
       return super unless standard_ledger_immutable?
+      return false if @_standard_ledger_destroying
 
       !new_record?
     end
 
+    # Wrap `destroy` so it can bypass the `readonly?` guard when the
+    # entry has opted in via `allow_destroy: true`. This applies to
+    # `destroy`, `destroy!`, and `dependent: :destroy` cascades from a
+    # parent record (all routes call through `#destroy`).
+    def destroy
+      return super unless self.class.respond_to?(:standard_ledger_entry_config)
+
+      config = self.class.standard_ledger_entry_config
+      return super if config.nil? || !config[:immutable] || !config[:allow_destroy]
+
+      @_standard_ledger_destroying = true
+      super
+    ensure
+      @_standard_ledger_destroying = false
+    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
@@ -232,6 +309,18 @@ module StandardLedger
       !config.nil? && config[:immutable]
     end
 
+    # Destroys are blocked when the entry is `immutable: true` AND the user
+    # has not opted out via `allow_destroy: true`. Split out so the
+    # before_destroy guard can be conditional independently of the
+    # save/update `readonly?` path.
+    def standard_ledger_destroy_blocked?
+      config = self.class.standard_ledger_entry_config
+      return false if config.nil?
+      return false unless config[:immutable]
+
+      !config[:allow_destroy]
+    end
+
     def standard_ledger_raise_readonly
       raise ActiveRecord::ReadOnlyRecord
     end

data/lib/standard_ledger/errors.rb

@@ -30,4 +30,14 @@ module StandardLedger
       super("Enqueued #{enqueued.size} projections; #{failed.size} failed to enqueue")
     end
   end
+
+  # Raised when `StandardLedger.refresh!(view, concurrently: true)` is called
+  # inside an open transaction. PostgreSQL rejects
+  # `REFRESH MATERIALIZED VIEW CONCURRENTLY` inside transaction blocks; the
+  # gem catches this at the boundary so the failure is a clear,
+  # gem-attributable error instead of a raw `PG::ActiveSqlTransaction`.
+  # Callers wanting read-your-write semantics inside an operation should
+  # wrap the call in `connection.add_transaction_record { ... }` to defer
+  # to after-commit, or move the refresh outside the transaction block.
+  class RefreshInsideTransaction < Error; 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/projector.rb

@@ -70,9 +70,120 @@ module StandardLedger
       # @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, trigger_name: 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,

data/lib/standard_ledger/version.rb

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

data/lib/standard_ledger.rb

@@ -443,6 +443,7 @@ module StandardLedger
     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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_ledger
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jaryl Sim