standard_ledger 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0d328d7c7f7c420d4b9abdcddeb6b1578b4c2798d33e0b53f44f36f3ed0e437
-  data.tar.gz: 481811ac4fb4b479d95e008798ce0c64182aa78c40f9d030866d8695d61bb953
+  metadata.gz: 411ad3db9a71ca8adddecc84d407dabddbd167c7ed00e534e975a700b3a2e8f2
+  data.tar.gz: aeb938a4e1fb16c6df67fbb76a93a5687c40116be040df5da44e65541ce4d282
 SHA512:
-  metadata.gz: 5bc96a821455069e8717e4c5904bafb8498d27f57f9b4b58a76266a47fb132bb3b1ff83fc08c3f36e8f939d2e5e1da7ceb16fc6035de2b458b26d2ef891c640e
-  data.tar.gz: 0751a94baaacaf4423452add7215c6a67ad79b2b3e81074180314ec96ffcdf9c9b02a4843bebc964f1fa3191a293e62275f2a537cfb5617fae8dd1bd18a804c5
+  metadata.gz: 2d0cd11b66c8d22b76cf9444e8840d92c35ccd81d4eba224e8123b208aa5c706503bc9cf6e9bbf1dc7bff564df4728adac79eeeacc254a976efb8cfa1fd0907a
+  data.tar.gz: 5f352fe00a36e01ef43aa4d8efb197a32314c43f0b31657342996dc91bcf422933e4076b851813bd6c6fd7ab69a52d18f53e9650fbced76292b9deca52b6ce0b

data/CHANGELOG.md

@@ -8,6 +8,174 @@ 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
+- `:async` projection mode + `StandardLedger::ProjectionJob`. Used when
+  the projection is too expensive or stateful for the entry's transaction
+  (jsonb rebuild, multi-row aggregate) — the canonical example is
+  nutripod's `Order#payable_balance` / `Order#fulfillable_balance` jsonb
+  columns. The strategy installs an `after_create_commit` callback that
+  enqueues `StandardLedger::ProjectionJob` per (entry, projection) pair;
+  the job resolves the target via the entry's `belongs_to`, wraps
+  `target.with_lock { projector.apply(target, entry) }`, and fires the
+  same `<prefix>.projection.applied` / `<prefix>.projection.failed`
+  events as `:inline` (with an additional `attempt:` key drawn from
+  ActiveJob's `executions` accessor).
+  - Class-form only: `:async` projections must declare `via: ProjectorClass`.
+    The projector's `apply(target, entry)` should recompute from the log
+    inside `with_lock` rather than apply a delta — async retries can run
+    the projector more than once, so block-form per-kind handlers
+    (incrementing counters) are silently corrupting under retry. The
+    registration path rejects block forms with a clear ArgumentError;
+    `lock:` and `permissive: true` are also rejected (`with_lock` is
+    unconditional and there are no per-kind handlers).
+  - Retries: `Config#default_async_retries` (default 3 total attempts —
+    one initial run + two retries, matching ActiveJob's `retry_on
+    attempts:` semantics) caps the attempt count. The job uses a
+    hand-rolled `rescue_from(StandardError)` that reads the cap at
+    perform time so reconfiguration in tests / hosts takes effect
+    immediately, with `discard_on StandardLedger::Error` so programmer
+    errors (missing definition, renamed association) skip the retry
+    budget entirely. Each failure emits its own
+    `<prefix>.projection.failed` event with the current `attempt` so
+    subscribers see the full retry history.
+  - `Config#default_async_job` — hosts can swap the default
+    `StandardLedger::ProjectionJob` for their own subclass (per-mode
+    queue routing, custom retry policies). The strategy reads it at
+    enqueue time.
+  - `with_modes(EntryClass => :inline)` interop: when the override map
+    forces an entry class to `:inline`, the strategy short-circuits the
+    enqueue and runs `target.with_lock { projector.apply(target, entry) }`
+    synchronously inside the block. Useful in unit specs that want
+    end-to-end coverage without standing up a job runner. Notifications
+    fire with `mode: :async, attempt: 1` so subscribers can't tell the
+    difference.
+  - `StandardLedger.rebuild!` extends to `:async` projections — same
+    per-target rebuild semantics as `:inline` (delegates to
+    `definition.projector_class.new.rebuild(target)`). The mode
+    difference is only in the after-create path, not the rebuild path.
+- `:trigger` projection mode. The host owns the database trigger
+  (created in a Rails migration); the gem **does not create or manage
+  triggers** — that's deliberate, because giving a Ruby DSL the power
+  to install/replace triggers is a deploy footgun (silent re-creation
+  on `db:schema:load` against a non-empty DB), and triggers are
+  versioned by `db/schema.rb` like any other DDL. The gem only records
+  the trigger's name and the equivalent rebuild SQL.
+  - `projects_onto :assoc, mode: :trigger, trigger_name: "..." do
+    rebuild_sql "..." end` declares a trigger projection. The
+    `trigger_name:` keyword is required (a non-empty string); the
+    block must call `rebuild_sql "..."` exactly once with a SQL
+    string containing the `:target_id` placeholder. Registration
+    rejects `via:`, `lock:`, and `permissive:` (none are meaningful
+    for `:trigger` mode — the trigger is the contract). `Definition`
+    gains a `trigger_name` field, populated only for `:trigger` mode;
+    the rebuild SQL is stored in the existing `recompute_sql` slot
+    (shared with `:sql` mode — both modes use it the same way).
+  - `StandardLedger::Modes::Trigger` strategy — `install!` is a no-op
+    marker (trigger projections fire from the database, not Ruby, so
+    no `after_create` callback is wired). The strategy class exists
+    only to keep `Projector#install_mode_callbacks_for`'s dispatch
+    table uniform across modes and to mark the entry class as having
+    at least one `:trigger` projection registered.
+  - `StandardLedger.rebuild!(EntryClass)` extends to `:trigger`
+    projections: the same SQL recompute path as `:sql` mode runs the
+    recorded `rebuild_sql` against each target the log references,
+    binding `:target_id` to each target's id. `target:` /
+    `target_class:` / no-arg scoping works the same way.
+    `<prefix>.projection.rebuilt` fires per target with `mode:
+    :trigger`. The gem does NOT verify or recreate the trigger
+    during `rebuild!` — `standard_ledger:doctor` is the deploy-time
+    check.
+- `standard_ledger:doctor` rake task. Iterates every registered
+  `:trigger` projection across all loaded entry classes (discovered
+  by walking `ActiveRecord::Base.descendants` for classes that
+  include `StandardLedger::Projector` and have at least one `:trigger`
+  projection). For each, queries `pg_trigger` to confirm the named
+  trigger exists in the connected schema. Reports missing triggers
+  on stderr with a clear remediation message and exits 1; prints a
+  success message and exits 0 otherwise. **Postgres-only** — the
+  task queries `pg_trigger` directly and will raise on a non-Postgres
+  connection. SQLite has no comparable per-statement trigger
+  introspection that fits this gem's contract; the only adopter
+  today is nutripod-web (Postgres). The task is auto-loaded via
+  `Engine.rake_tasks` so `bin/rails -T standard_ledger` shows it
+  immediately after the gem is installed.
+- Integration spec for `:trigger` mode
+  (`spec/standard_ledger/trigger_integration_spec.rb`) covers DSL
+  registration validation (missing `trigger_name`, missing block,
+  empty block, `via:` / `lock:` / `permissive:` rejection,
+  `:target_id` placeholder enforcement, double `rebuild_sql` call),
+  the strategy's no-callback contract (creating an entry does NOT
+  mutate the target via Ruby — that's the trigger's job in
+  production), and `StandardLedger.rebuild!` for both single-target
+  and walk-the-log scoping with the `<prefix>.projection.rebuilt`
+  event firing with `mode: :trigger`.
+- Doctor task spec
+  (`spec/standard_ledger/tasks/doctor_spec.rb`) mocks the
+  `connection.exec_query` against `pg_trigger` to exercise the
+  task's three behaviours (success, failure with exit 1 + stderr
+  message, ignoring entry classes without `:trigger` projections)
+  without requiring a real Postgres database.
+- Integration spec for `:async` mode
+  (`spec/standard_ledger/async_integration_spec.rb`) covers DSL
+  registration validation, after-commit enqueue, multi-target fan-out,
+  nil-FK skip (both at enqueue and at perform), the `with_modes`
+  inline override, the `default_async_job` swap, retry-on-failure with
+  attempt-counter telemetry, the `discard_on StandardLedger::Error`
+  programmer-error path, and the rebuild path.
+
 ## [0.2.0] - 2026-05-05
 
 ### Added
@@ -255,6 +423,7 @@ 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.2.0...HEAD
+[Unreleased]: https://github.com/rarebit-one/standard_ledger/compare/v0.3.0...HEAD
+[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/README.md

@@ -2,10 +2,12 @@
 
 Immutable journal entries with declarative aggregate projections for Rails apps.
 
-> **Status: v0.2.0** — production-ready for `:inline`, `:sql`, and `:matview`
-> projections (covering luminality-web, fundbright-web, and sidekick-web's
-> needs). `:async` and `:trigger` modes ship in subsequent PRs ahead of
-> nutripod-web adoption. See [`standard_ledger-design.md`](https://github.com/rarebit-one/standard_ledger/blob/main/standard_ledger-design.md)
+> **Status: v0.3.0** — feature-complete across all five projection modes
+> (`:inline`, `:async`, `:sql`, `:matview`, `:trigger`) plus
+> `StandardLedger.rebuild!` log-replay, `StandardLedger.refresh!` ad-hoc
+> matview refresh, and the `standard_ledger:doctor` rake task. Ready for
+> adoption in luminality-web, fundbright-web, sidekick-web, and
+> nutripod-web. See [`standard_ledger-design.md`](https://github.com/rarebit-one/standard_ledger/blob/main/standard_ledger-design.md)
 > for the full design and rollout plan.
 
 ## What it is
@@ -101,6 +103,50 @@ mid-loop are not unwound. Block-form (delta) projections raise
 `NotRebuildable` because they cannot be reconstructed from the log
 without a host-supplied recompute path.
 
+For projections too expensive or stateful to run inside the entry's
+transaction (jsonb rebuild, multi-row aggregate), use `mode: :async` —
+the strategy enqueues `StandardLedger::ProjectionJob` from
+`after_create_commit`, and the job runs `target.with_lock { projector.apply(target, entry) }`
+on the configured ActiveJob backend:
+
+```ruby
+class Orders::FulfillableProjector < StandardLedger::Projection
+  # Recompute the jsonb balance from the full log inside with_lock.
+  # `:async` projectors must be retry-safe — async retries can run
+  # `apply` more than once, so block-form per-kind handlers
+  # (incrementing counters) are rejected at registration time.
+  def apply(order, _entry)
+    order.update!(
+      fulfillable_balance: order.fulfillment_records.group(:key).sum(:amount)
+    )
+  end
+
+  def rebuild(order)
+    apply(order, nil)
+  end
+end
+
+class FulfillmentRecord < ApplicationRecord
+  include StandardLedger::Entry
+  include StandardLedger::Projector
+
+  belongs_to :order
+
+  ledger_entry kind: :action, idempotency_key: :external_ref, scope: :organisation_id
+
+  projects_onto :order, mode: :async, via: Orders::FulfillableProjector
+end
+```
+
+Retries are capped by `Config#default_async_retries` (default 3); the
+job emits `<prefix>.projection.applied` and `<prefix>.projection.failed`
+events with an additional `attempt:` key so subscribers can tell
+first-try success from retry success. Tests can force async projections
+to run inline via `StandardLedger.with_modes(FulfillmentRecord => :inline) { ... }`
+— the strategy short-circuits the enqueue and runs the projector
+synchronously inside `with_lock`, so end-to-end coverage works without a
+job runner.
+
 For projections expressible as a single `UPDATE` over an aggregate of the
 log, use `mode: :sql` — no Ruby-side handlers, no AR object loads, just
 a recompute statement that runs in the entry's `after_create`:
@@ -132,6 +178,58 @@ SQL is the entire contract — `:sql` projections are naturally
 rebuildable: `StandardLedger.rebuild!` runs the same statement against
 every target the log references.
 
+When the host **already has** a database trigger that updates the
+projection target on every entry INSERT, register it with `mode: :trigger`
+so the gem records the trigger's name and the equivalent rebuild SQL —
+without taking ownership of the trigger DDL. The host writes the trigger
+in a Rails migration; the gem only consumes the metadata.
+
+```ruby
+class InventoryRecord < ApplicationRecord
+  include StandardLedger::Entry
+  include StandardLedger::Projector
+
+  belongs_to :sku
+
+  ledger_entry kind: :action, idempotency_key: :serial_no, scope: :organisation_id
+
+  projects_onto :sku, mode: :trigger,
+                      trigger_name: "inventory_records_apply_to_skus" do
+    rebuild_sql <<~SQL
+      UPDATE skus SET
+        total_count    = c.total_count,
+        reserved_count = c.reserved_count,
+        free_count     = c.total_count - c.reserved_count
+      FROM (
+        SELECT sku_id,
+               COUNT(*) FILTER (WHERE action IN ('grant','adjust_in')) AS total_count,
+               COUNT(*) FILTER (WHERE action = 'reserve')              AS reserved_count
+        FROM inventory_records
+        WHERE sku_id = :target_id
+        GROUP BY sku_id
+      ) c
+      WHERE skus.id = :target_id AND skus.id = c.sku_id
+    SQL
+  end
+end
+```
+
+The trigger continues to fire on every `INSERT` (the host owns the DDL);
+the gem records the trigger name + rebuild SQL for two purposes:
+
+- `StandardLedger.rebuild!(InventoryRecord, target: sku)` runs the
+  recorded `rebuild_sql` with `:target_id` bound to each target's id.
+- `bin/rails standard_ledger:doctor` verifies that every registered
+  `:trigger` projection's named trigger exists in the connected schema
+  (queries `pg_trigger`). Run this as a deploy-time check — migration
+  drift surfaces immediately rather than at runtime. **Postgres-only**;
+  the task raises on non-Postgres connections.
+
+Registration rejects `via:`, `lock:`, and `permissive:` (none are
+meaningful when the trigger itself is the contract). The `trigger_name:`
+keyword is required; the block must call `rebuild_sql "..."` exactly
+once with a SQL string containing the `:target_id` placeholder.
+
 Refresh a `:matview` projection ad-hoc when the host needs immediate
 read-your-write semantics (e.g. at the end of a draw operation, before
 the next scheduled refresh would otherwise show stale counts):

data/lib/standard_ledger/config.rb

@@ -11,8 +11,9 @@ module StandardLedger
     # `c.default_async_job = Orders::FulfillableProjectionJob`.
     attr_accessor :default_async_job
 
-    # Number of times an `:async` projection will retry before dead-lettering.
-    # Default: 3.
+    # Total attempts (including the first) for an `:async` projection before
+    # the failure is propagated. Default: 3 (one initial run + two retries).
+    # Matches ActiveJob's `retry_on attempts:` semantics.
     attr_accessor :default_async_retries
 
     # Scheduler backend for `:matview` refresh jobs. One of

data/lib/standard_ledger/engine.rb

@@ -15,5 +15,12 @@ module StandardLedger
       # no-op — the gem emits events but ships no internal subscribers; hosts
       # subscribe directly via ActiveSupport::Notifications.subscribe.
     end
+
+    # Engines auto-discover `lib/tasks/*.rake` in most Rails versions, but
+    # we register explicitly for defence-in-depth. Hosts get
+    # `standard_ledger:doctor` available under `bin/rails -T standard_ledger`.
+    rake_tasks do
+      load File.expand_path("../tasks/standard_ledger.rake", __dir__)
+    end
   end
 end

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/jobs/projection_job.rb

@@ -0,0 +1,94 @@
+require "active_job"
+
+module StandardLedger
+  # ActiveJob class that runs a single `:async`-mode projection after the
+  # entry's outer transaction has committed. Enqueued by
+  # `StandardLedger::Modes::Async` from an `after_create_commit` callback.
+  #
+  # The job resolves the projection definition by `target_association` (the
+  # only stable handle — the Definition struct doesn't serialize cleanly
+  # through ActiveJob), looks up the target via the entry's `belongs_to`
+  # setter, and runs `target.with_lock { projector_class.new.apply(target,
+  # entry) }`. The projector must be class-form (`via: ProjectorClass`) and
+  # should recompute the aggregate from the log inside `apply` for retry
+  # safety — async projections can run more than once when the job retries.
+  #
+  # Retries are configurable per-projection via subclassing this job and
+  # overriding `retry_on`, or globally via `Config#default_async_retries`
+  # (default 3). When retries are exhausted, ActiveJob's dead-letter behavior
+  # takes over — the job still emits `<prefix>.projection.failed` on every
+  # attempt so subscribers see the full retry history.
+  #
+  # Notification payloads include `attempt:` (drawn from ActiveJob's
+  # `executions` accessor — 1 on first attempt, increments per retry) so
+  # subscribers can distinguish first-try success from retry-success.
+  class ProjectionJob < ::ActiveJob::Base
+    # Hand-rolled retry path so the attempt cap reads
+    # `Config#default_async_retries` at perform time. ActiveJob's
+    # `retry_on attempts:` requires a constant Integer (or `:unlimited`)
+    # and is captured at class-definition time — that's incompatible with
+    # the gem's pattern of letting hosts reconfigure `default_async_retries`
+    # in their initializer (or specs flipping it temporarily). We rescue
+    # `StandardError` and re-enqueue manually until the cap is reached.
+    rescue_from(StandardError) do |error|
+      attempts = StandardLedger.config.default_async_retries
+      if executions < attempts
+        # Compute a polynomial backoff inline. Mirrors ActiveJob's
+        # `:polynomially_longer` algorithm (`executions**4 + 2`) without
+        # depending on its private `determine_delay` API.
+        delay = (executions**4) + 2
+        retry_job(wait: delay, error: error)
+      else
+        raise error
+      end
+    end
+
+    # Discard programmer errors immediately — they're deterministic and
+    # retrying just burns the budget. `StandardLedger::Error` is raised by
+    # `#perform` on missing/renamed projection definitions and similar
+    # bookkeeping mistakes; the next attempt would raise the same error.
+    # Declared AFTER the `rescue_from(StandardError)` block above because
+    # `ActiveSupport::Rescuable` searches handlers from the most-recently-
+    # registered first — so this more-specific `StandardLedger::Error`
+    # handler wins over the catch-all retry path for its matching errors.
+    discard_on StandardLedger::Error
+
+    def perform(entry, target_association)
+      definition = entry.class.standard_ledger_projections.find { |d|
+        d.mode == :async && d.target_association == target_association.to_sym
+      }
+      if definition.nil?
+        raise StandardLedger::Error,
+              "no :async projection #{target_association.inspect} on #{entry.class.name}"
+      end
+
+      target = entry.public_send(definition.target_association)
+      return if target.nil?
+
+      prefix = StandardLedger.config.notification_namespace
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      begin
+        target.with_lock do
+          definition.projector_class.new.apply(target, entry)
+        end
+      rescue StandardError => e
+        duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+        StandardLedger::EventEmitter.emit(
+          "#{prefix}.projection.failed",
+          entry: entry, target: target, projection: definition.target_association,
+          mode: :async, error: e, duration_ms: duration_ms,
+          attempt: executions
+        )
+        raise
+      end
+
+      duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+      StandardLedger::EventEmitter.emit(
+        "#{prefix}.projection.applied",
+        entry: entry, target: target, projection: definition.target_association,
+        mode: :async, duration_ms: duration_ms, attempt: executions
+      )
+    end
+  end
+end