standard_ledger 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 276066f9976675bcd6ed7220d0df2d72518c355eab43036807cf53c1c1da7e00
-  data.tar.gz: 01de25809973bb72ed2414f32f5c6c9398f45f2d44fed75bfdb1743c9beaaedc
+  metadata.gz: 89af058a7d94051bc75f8e853d1be397270b52bc5a02020dfdd41484c6cacda5
+  data.tar.gz: 50eef558981621f3561c42095d294f87f09d7ed18e8fc5a5919c0801262f257b
 SHA512:
-  metadata.gz: bc772c009801e0bf6ab2e3568e95aeff7305413fce076742d89dfb62388cada99a168659fc0745807ca661c31bd30cc33529b105c4f7bd163a91090d3b5603ab
-  data.tar.gz: 1002bacfe4f93410a2d06ffda6dec585328c0c248d518f3e0e12148a9bd5effb451f02dbb1967569b3e2d30b3d8c71bcc4abba53efa7e41d218f451ee21d659c
+  metadata.gz: 16d8c529a99909adb4739feb0ea76e996ebd709c044bc56dd2722bc041f4c17670d2bb383a48072df9a686bc02b1c2a49add8206618ddeb7fb86dd2b45e61c9f
+  data.tar.gz: 5f152b064c69e8da3f7e2767c4b3914da197599ed64ecc8e512be6c34e334af25337f83fd68080c7811a3f4772df647d5799ae635cb0116409286455bd86bf0e

data/CHANGELOG.md

@@ -6,7 +6,81 @@ project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
-Nothing yet.
+## [0.5.0] - 2026-09-22
+
+### Changed
+- `required_ruby_version` raised from `>= 3.4` to `>= 4.0`, and the repo's
+  `.ruby-version` moved from 3.4.4 to 4.0.1 to match. The 3.4 floor was never
+  exercised — CI has only ever run the 4.0.x matrix — and every consumer runs
+  4.0.x. This aligns the gem with the rest of the `standard_*` family.
+
+### Documentation
+- New README **Events** section documenting all five lifecycle events
+  (`entry.created`, `projection.applied`, `projection.failed`,
+  `projection.refreshed`, `projection.rebuilt`), their payloads, and the four
+  places a payload shape differs from the obvious one: `:sql` mode sends
+  `target: nil`, `:matview` events carry `view:`/`concurrently:` instead of
+  `entry:`/`target:`, `projection.rebuilt` carries `entry_class:` rather than
+  `entry:`, and input errors (matview name validation,
+  `RefreshInsideTransaction`) propagate without firing `projection.failed`.
+  Also records that subscriber exceptions are swallowed by design.
+- README installation now shows the RubyGems pin. It still said "private during
+  incubation, pin from git"; the gem has been on RubyGems since 2026-05-07 and
+  the last git-pinned consumer was converted in 2026-07.
+- `CLAUDE.md` consumer list corrected: it listed two consumers and claimed
+  git+tag consumption. There are four (`fundbright-web`, `luminality-web`,
+  `sidekick-web`, `jumpdrive-web`), all plain rubygems.
+
+## [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
 
@@ -372,7 +446,9 @@ roadmap.
   and `:trigger` (host-owned, gem records rebuild SQL).
 - `standard_ledger:doctor` rake task (verifies trigger presence, etc.).
 
-[Unreleased]: https://github.com/rarebit-one/standard_ledger/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/rarebit-one/standard_ledger/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/rarebit-one/standard_ledger/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/rarebit-one/standard_ledger/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/rarebit-one/standard_ledger/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/rarebit-one/standard_ledger/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/rarebit-one/standard_ledger/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Rarebit One
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -283,12 +283,16 @@ Five projection modes — pick per declaration:
 
 ## Installation
 
-The gem is private during incubation. Pin from git:
+The gem is published on RubyGems:
 
 ```ruby
-gem "standard_ledger", git: "https://github.com/rarebit-one/standard_ledger", ref: "<sha>"
+gem "standard_ledger", "~> 0.4"
 ```
 
+(It was git-pinned during incubation. Don't reintroduce a `git:` reference —
+it makes a bare `bundle install` a prerequisite for every other command in a
+fresh checkout, blocking `rubocop`/`rspec` until it has been run.)
+
 Then run the install generator to drop a configured initializer in place:
 
 ```bash
@@ -317,6 +321,57 @@ StandardLedger.configure do |c|
 end
 ```
 
+## Events
+
+The gem emits five lifecycle events. On Rails 8.1+ they go through
+`Rails.event.notify(name, **payload)`; on older Rails (or any host without the
+structured reporter) they fall back to
+`ActiveSupport::Notifications.instrument(name, payload)`. The backend is
+detected per call, not cached at load — the gem is required before Rails has
+finished booting.
+
+Every name is prefixed with `Config#notification_namespace` (default
+`standard_ledger`), so a host that renames the namespace renames all five.
+
+| Event | Fired when | Payload |
+|---|---|---|
+| `<prefix>.entry.created` | after the entry's transaction commits | `entry:`, `kind:`, `targets:` (a `{ name => target }` hash) |
+| `<prefix>.projection.applied` | a projection wrote successfully | `entry:`, `target:`, `projection:`, `mode:`, `duration_ms:` — plus `attempt:` in `:async` mode |
+| `<prefix>.projection.failed` | a projection raised | the `applied` payload plus `error:` (the exception) |
+| `<prefix>.projection.refreshed` | a matview refresh succeeded | `view:`, `concurrently:`, `duration_ms:` |
+| `<prefix>.projection.rebuilt` | `StandardLedger.rebuild!` finished one target | `entry_class:`, `target:`, `projection:`, `mode:` |
+
+Four payload shapes are worth knowing before you write a subscriber that
+assumes a key is always present:
+
+- **`:sql` mode sends `target: nil`.** The recompute statement is bound by
+  `:target_id` and never loads the record, so there is no object to hand you.
+- **`:matview` events carry `view:`/`concurrently:` instead of
+  `entry:`/`target:`.** A refresh is view-wide — Postgres has no partial-refresh
+  primitive — so no single entry or target caused it. The matview variant of
+  `projection.failed` also carries `mode: :matview`, while
+  `projection.refreshed` carries no `mode:` at all.
+- **`projection.rebuilt` carries `entry_class:`, not `entry:`.** Rebuild is
+  log replay across an entire class; there is no originating entry.
+- **`projection.failed` is not fired for input errors.** An `ArgumentError`
+  from the matview name validator, or `RefreshInsideTransaction` from the
+  boundary check, propagates without an event — the SQL was never issued, so
+  nothing failed to project.
+
+**Subscriber exceptions are swallowed** (warned to stderr, not re-raised).
+Ledger observability must never take down a host's request path: by emit time
+the projection has already either succeeded or been rolled back, so there is
+nothing a raising subscriber could usefully abort. Don't put work in a
+subscriber that you need to have happened.
+
+Retries: `:async` projections are capped by `Config#default_async_retries`
+(default 3), and both `applied` and `failed` carry `attempt:` so subscribers
+can tell first-try success from retry success.
+
+`standard_audit` consumers can subscribe to `entry.created` to write an audit
+row; the gem itself never calls into audit. That coupling is deliberately the
+host's to opt into — see "Relationship to standard_audit" below.
+
 ## Testing
 
 The gem ships an opt-in RSpec support file. Hosts add this to their
@@ -382,4 +437,4 @@ Neither subsumes the other.
 
 ## License
 
-MIT. See [MIT-LICENSE](MIT-LICENSE).
+MIT. See [LICENSE](LICENSE).

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.5.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.5.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -134,7 +134,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- MIT-LICENSE
+- LICENSE
 - README.md
 - Rakefile
 - lib/generators/standard_ledger/install/install_generator.rb
@@ -175,7 +175,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/MIT-LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Jaryl Sim
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.