standard_ledger 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0d328d7c7f7c420d4b9abdcddeb6b1578b4c2798d33e0b53f44f36f3ed0e437
-  data.tar.gz: 481811ac4fb4b479d95e008798ce0c64182aa78c40f9d030866d8695d61bb953
+  metadata.gz: 276066f9976675bcd6ed7220d0df2d72518c355eab43036807cf53c1c1da7e00
+  data.tar.gz: 01de25809973bb72ed2414f32f5c6c9398f45f2d44fed75bfdb1743c9beaaedc
 SHA512:
-  metadata.gz: 5bc96a821455069e8717e4c5904bafb8498d27f57f9b4b58a76266a47fb132bb3b1ff83fc08c3f36e8f939d2e5e1da7ceb16fc6035de2b458b26d2ef891c640e
-  data.tar.gz: 0751a94baaacaf4423452add7215c6a67ad79b2b3e81074180314ec96ffcdf9c9b02a4843bebc964f1fa3191a293e62275f2a537cfb5617fae8dd1bd18a804c5
+  metadata.gz: bc772c009801e0bf6ab2e3568e95aeff7305413fce076742d89dfb62388cada99a168659fc0745807ca661c31bd30cc33529b105c4f7bd163a91090d3b5603ab
+  data.tar.gz: 1002bacfe4f93410a2d06ffda6dec585328c0c248d518f3e0e12148a9bd5effb451f02dbb1967569b3e2d30b3d8c71bcc4abba53efa7e41d218f451ee21d659c

data/CHANGELOG.md

@@ -8,6 +8,123 @@ project adheres to [Semantic Versioning](https://semver.org/).
 
 Nothing yet.
 
+## [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 +372,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/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

data/lib/standard_ledger/modes/async.rb

@@ -0,0 +1,141 @@
+module StandardLedger
+  module Modes
+    # `:async` mode: applies the projection in a background job enqueued
+    # from the entry's `after_create_commit` callback. The job runs after
+    # the outer transaction has committed, so the entry is durable before
+    # the projection runs — and a job failure does NOT roll back the entry.
+    #
+    # 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, which need to be recomputed from every PaymentRecord /
+    # FulfillmentRecord against the order — work that's safe to defer past
+    # the originating transaction.
+    #
+    # Class-form only: `:async` projections must declare `via: ProjectorClass`,
+    # whose `apply(target, entry)` should recompute from the log inside
+    # `with_lock` rather than apply a delta. Block-form per-kind handlers
+    # aren't safe under retry — incrementing a counter twice on retry is a
+    # silent data corruption bug — so block-form is rejected at registration
+    # time (see `Projector#projects_onto`).
+    #
+    # The strategy installs an `after_create_commit` callback once per entry
+    # class. The callback walks every `:async`-mode projection registered on
+    # the class and enqueues `StandardLedger::ProjectionJob` per (entry,
+    # projection) pair, honoring the optional `if:` guard.
+    #
+    # ## with_modes interop
+    #
+    # `StandardLedger.with_modes(EntryClass => :inline) { ... }` forces async
+    # projections to run synchronously inside the block — useful in unit
+    # specs that want end-to-end coverage without standing up a job runner.
+    # Inline-override mode skips the enqueue and runs `target.with_lock {
+    # projector.apply(target, entry) }` directly. The override is read in
+    # `#call`; specs can capture the empty job queue via `have_enqueued_job`
+    # / `perform_enqueued_jobs` and still observe the projection's effects.
+    class Async
+      # Install the `after_create_commit` callback on `entry_class` exactly
+      # once. Subsequent calls (e.g. when a second `:async` projection is
+      # added later in the class body) are no-ops — the same callback
+      # handles all `:async` projections registered on the class.
+      #
+      # @param entry_class [Class] the host entry class.
+      # @return [void]
+      # @raise [ArgumentError] when `entry_class` is not ActiveRecord-backed
+      #   (no `after_create_commit` hook available). `:async` mode requires
+      #   AR transactional callbacks; non-AR entry classes can't dispatch
+      #   the post-commit enqueue.
+      def self.install!(entry_class)
+        return if entry_class.instance_variable_get(:@_standard_ledger_async_installed)
+
+        unless entry_class.respond_to?(:after_create_commit)
+          raise ArgumentError,
+                "Modes::Async requires an ActiveRecord-backed entry class on " \
+                "#{entry_class.name || entry_class.inspect} — the entry class must inherit " \
+                "from ActiveRecord::Base. Use :inline mode for plain-Ruby entry classes."
+        end
+
+        entry_class.after_create_commit { StandardLedger::Modes::Async.new.call(self) }
+        entry_class.instance_variable_set(:@_standard_ledger_async_installed, true)
+      end
+
+      # Enqueue `ProjectionJob` for every `:async` projection registered on
+      # the entry's class. Called from the `after_create_commit` callback
+      # installed by `.install!`.
+      #
+      # Honors the optional `if:` guard (skips enqueue when guard returns
+      # false) and `StandardLedger.mode_override_for(entry_class)` (when set
+      # to `:inline`, runs the projection synchronously inside `with_lock`
+      # instead of enqueueing).
+      #
+      # A nil target at enqueue time skips silently — the entry's FK was
+      # unset for this projection's association, so there's nothing to
+      # project onto. (The job has its own nil-target guard; this short-
+      # circuit just avoids the wasted enqueue.)
+      #
+      # @param entry [ActiveRecord::Base] the just-committed entry.
+      # @return [void]
+      def call(entry)
+        definitions = async_definitions_for(entry.class)
+        return if definitions.empty?
+
+        override = StandardLedger.mode_override_for(entry.class)
+
+        definitions.each do |definition|
+          next if definition.guard && !entry.instance_exec(&definition.guard)
+
+          if override == :inline
+            run_inline(entry, definition)
+          else
+            target = entry.public_send(definition.target_association)
+            next if target.nil?
+
+            job_class = StandardLedger.config.default_async_job || StandardLedger::ProjectionJob
+            job_class.perform_later(entry, definition.target_association.to_s)
+          end
+        end
+      end
+
+      private
+
+      def async_definitions_for(entry_class)
+        return [] unless entry_class.respond_to?(:standard_ledger_projections_for)
+
+        entry_class.standard_ledger_projections_for(:async)
+      end
+
+      # `with_modes(EntryClass => :inline)` short-circuit: run the projector
+      # synchronously inside `with_lock`, mirroring the job's behavior
+      # without the enqueue. Skips silently when the target is nil so the
+      # nil-FK contract matches the enqueue path.
+      def run_inline(entry, definition)
+        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: 1
+          )
+          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: 1
+        )
+      end
+    end
+  end
+end

data/lib/standard_ledger/modes/trigger.rb

@@ -0,0 +1,50 @@
+module StandardLedger
+  module Modes
+    # `:trigger` mode: the host owns a database trigger (created in a Rails
+    # migration) that updates the projection target's columns on every
+    # entry INSERT. The gem records the trigger's name and the equivalent
+    # rebuild SQL, but does **not** create or manage the trigger itself —
+    # 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.
+    #
+    # Two consumers read the recorded metadata:
+    #
+    # - `StandardLedger.rebuild!` runs the rebuild SQL when invoked,
+    #   binding `:target_id` to each target the log references. The same
+    #   recompute path as `:sql` mode — the only difference is that the
+    #   after-create application is performed by the database trigger
+    #   rather than a Ruby callback.
+    # - The `standard_ledger:doctor` rake task verifies that the named
+    #   trigger exists in the connected schema. Migration drift (a missing
+    #   or renamed trigger) is caught at deploy time, not at runtime.
+    #
+    # Unlike `:inline` and `:sql`, this strategy does NOT install an
+    # `after_create` callback — the trigger fires from the database. The
+    # `install!` no-op only marks the entry class as having at least one
+    # `:trigger` projection registered (mirrors the `Modes::Matview` shape).
+    #
+    # See `standard_ledger-design.md` §5.3.4 for the full contract.
+    class Trigger
+      # Mark the entry class as having at least one `:trigger` projection
+      # registered. The actual trigger metadata lives on the entry class's
+      # `standard_ledger_projections` array; this method exists only to
+      # mirror the `Modes::*.install!` shape so `Projector#install_mode_callbacks_for`
+      # can dispatch uniformly across modes.
+      #
+      # No `after_create` callback is installed — the trigger runs in the
+      # database, not Ruby. Idempotent across multiple `:trigger`
+      # projections on the same entry class.
+      #
+      # @param entry_class [Class] the host entry class (unused — kept for
+      #   parity with the other strategy classes).
+      # @return [void]
+      def self.install!(_entry_class)
+        # Intentionally empty: trigger projections fire from the DB, so
+        # there's no Ruby-side callback to wire. The DSL has already
+        # captured `trigger_name` and `recompute_sql` on the Definition;
+        # `rebuild!` and the `doctor` rake task consume those directly.
+      end
+    end
+  end
+end

data/lib/standard_ledger/projector.rb

@@ -34,7 +34,7 @@ module StandardLedger
     # projections; they're `nil` for every other mode.
     Definition = Struct.new(
       :target_association, :mode, :projector_class, :handlers, :guard, :lock, :permissive,
-      :recompute_sql, :view, :refresh_options, :options,
+      :recompute_sql, :trigger_name, :view, :refresh_options, :options,
       keyword_init: true
     )
 
@@ -62,12 +62,142 @@ module StandardLedger
       #   metadata, e.g. `{ every: 5.minutes, concurrently: true }`. The
       #   gem records this on the Definition for hosts to read when wiring
       #   their scheduler; the gem does NOT auto-schedule.
+      # @param trigger_name [String, Symbol, nil] for `mode: :trigger` only —
+      #   the name of the host-owned database trigger. Required when mode is
+      #   `:trigger`; ignored otherwise. The gem does NOT create or manage
+      #   the trigger; it records the name so `standard_ledger:doctor` can
+      #   verify the trigger's presence in the connected schema.
       # @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, **options, &block)
+      def projects_onto(target_association, mode:, via: nil, if: nil, lock: nil, permissive: false, view: nil, refresh: nil, trigger_name: nil, **options, &block)
         guard = binding.local_variable_get(:if) # `if:` is a reserved keyword
 
+        if mode == :async
+          if block
+            raise ArgumentError,
+                  "projects_onto :#{target_association} mode: :async does not accept a block — " \
+                  "use `via: ProjectorClass` whose `apply(target, entry)` recomputes from the log " \
+                  "inside `with_lock` for retry-safety. Block-form per-kind handlers aren't safe " \
+                  "under async retry."
+          end
+
+          if via.nil?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} mode: :async requires `via: ProjectorClass` " \
+                  "(class-form only — see the registration error message for block-form for the why)"
+          end
+
+          unless lock.nil?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `lock:` with mode: :async; " \
+                  ":async always wraps the projector in `target.with_lock` for retry-safety, " \
+                  "so the option is redundant. Drop it."
+          end
+
+          if permissive
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `permissive: true` with mode: :async; " \
+                  "`permissive:` is only meaningful with the block form, and `:async` mode rejects " \
+                  "block-form for retry-safety reasons"
+          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 ]
+          install_mode_callbacks_for(definition)
+          return definition
+        end
+
+        if mode == :trigger
+          if via
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `via:` with mode: :trigger; " \
+                  "the trigger is the contract — there is no projector class. The host " \
+                  "owns the trigger via a Rails migration; the gem only records the " \
+                  "trigger's name and rebuild SQL"
+          end
+
+          unless lock.nil?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `lock:` with mode: :trigger; " \
+                  "`lock:` is not supported by :trigger mode — the database trigger handles " \
+                  "concurrency atomically"
+          end
+
+          if permissive
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `permissive:` with mode: :trigger; " \
+                  "`permissive:` is not supported by :trigger mode — the trigger doesn't " \
+                  "dispatch through per-kind handlers"
+          end
+
+          if guard
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `if:` with mode: :trigger; " \
+                  "`if:` is not supported by :trigger mode — the database trigger fires " \
+                  "unconditionally from the DB on INSERT, so a Ruby-side guard would " \
+                  "silently never run"
+          end
+
+          if trigger_name.nil? || trigger_name.to_s.empty?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} requires `trigger_name: \"...\"` for mode: :trigger; " \
+                  "the gem records the trigger's name so `standard_ledger:doctor` can verify its presence"
+          end
+
+          unless block
+            raise ArgumentError,
+                  "projects_onto :#{target_association} requires a block with `rebuild_sql \"...\"` for mode: :trigger"
+          end
+
+          dsl = TriggerDsl.new
+          dsl.instance_eval(&block)
+
+          if dsl.rebuild_sql_text.nil?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} block is empty; mode: :trigger requires a `rebuild_sql \"...\"` clause"
+          end
+
+          unless dsl.rebuild_sql_text.include?(":target_id")
+            raise ArgumentError,
+                  "projects_onto :#{target_association} rebuild SQL must include the `:target_id` placeholder; " \
+                  "it's bound to each target's id when `StandardLedger.rebuild!` walks the log"
+          end
+
+          definition = Definition.new(
+            target_association: target_association,
+            mode: mode,
+            projector_class: nil,
+            handlers: {},
+            guard: guard,
+            lock: lock,
+            permissive: permissive,
+            recompute_sql: dsl.rebuild_sql_text,
+            trigger_name: trigger_name.to_s,
+            view: nil,
+            refresh_options: nil,
+            options: options
+          )
+
+          self.standard_ledger_projections = standard_ledger_projections + [ definition ]
+          install_mode_callbacks_for(definition)
+          return definition
+        end
+
         if mode == :sql
           if via
             raise ArgumentError,
@@ -118,6 +248,7 @@ module StandardLedger
             lock: lock,
             permissive: permissive,
             recompute_sql: dsl.recompute_sql,
+            trigger_name: nil,
             view: nil,
             refresh_options: nil,
             options: options
@@ -150,6 +281,7 @@ module StandardLedger
             lock: lock,
             permissive: permissive,
             recompute_sql: nil,
+            trigger_name: nil,
             view: view.to_s,
             refresh_options: refresh || {},
             options: options
@@ -200,6 +332,7 @@ module StandardLedger
           lock: lock,
           permissive: permissive,
           recompute_sql: nil,
+          trigger_name: nil,
           view: nil,
           refresh_options: nil,
           options: options
@@ -222,10 +355,14 @@ module StandardLedger
         case definition.mode
         when :inline
           StandardLedger::Modes::Inline.install!(self)
+        when :async
+          StandardLedger::Modes::Async.install!(self)
         when :sql
           StandardLedger::Modes::Sql.install!(self)
         when :matview
           StandardLedger::Modes::Matview.install!(self)
+        when :trigger
+          StandardLedger::Modes::Trigger.install!(self)
         end
       end
 
@@ -275,6 +412,12 @@ module StandardLedger
               "the recompute SQL runs through `Modes::Sql#call` directly with no per-kind dispatch"
       end
 
+      if definition.mode == :trigger
+        raise Error,
+              "apply_projection! is not supported for mode: :trigger; " \
+              "the database trigger fires from the DB on INSERT, not from Ruby"
+      end
+
       return false if definition.guard && !instance_exec(&definition.guard)
 
       target = public_send(definition.target_association)
@@ -357,5 +500,28 @@ module StandardLedger
         @recompute_sql = sql
       end
     end
+
+    # Internal collector for the `:trigger`-mode block-DSL form. Captures
+    # the `rebuild_sql "..."` clause's SQL string. The trigger itself is
+    # owned by the host (created in a Rails migration); the gem only
+    # records this rebuild SQL so `StandardLedger.rebuild!` can recompute
+    # the projection from the log when invoked. Like `:sql` mode, the SQL
+    # must be expressible as a single statement with `:target_id` bound
+    # from each target's id at rebuild time.
+    class TriggerDsl
+      attr_reader :rebuild_sql_text
+
+      def rebuild_sql(sql)
+        unless sql.is_a?(String)
+          raise ArgumentError, "rebuild_sql requires a SQL string; got #{sql.class}"
+        end
+        unless @rebuild_sql_text.nil?
+          raise ArgumentError,
+                "rebuild_sql called more than once in the same projects_onto block; " \
+                ":trigger mode supports exactly one rebuild_sql clause per projection"
+        end
+        @rebuild_sql_text = sql
+      end
+    end
   end
 end

data/lib/standard_ledger/version.rb

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

data/lib/standard_ledger.rb

@@ -14,7 +14,10 @@ require "standard_ledger/projector"
 require "standard_ledger/modes/inline"
 require "standard_ledger/modes/sql"
 require "standard_ledger/modes/matview"
+require "standard_ledger/modes/trigger"
+require "standard_ledger/modes/async"
 require "standard_ledger/jobs/matview_refresh_job"
+require "standard_ledger/jobs/projection_job"
 require "standard_ledger/engine" if defined?(::Rails::Engine)
 
 # StandardLedger captures the recurring "immutable journal entry → N
@@ -197,9 +200,18 @@ module StandardLedger
     #   refresh *is* rebuild. Postgres has no partial-refresh primitive,
     #   so `target:` / `target_class:` scope arguments are ignored for
     #   `:matview` projections and the full view is always refreshed.
-    # - `:async`, `:sql`, `:trigger` modes are not yet supported by
-    #   `rebuild!`; they raise `StandardLedger::Error`. Each lands with
-    #   its mode's own PR.
+    # - `:sql` and `:trigger` projections rebuild by running their
+    #   recorded rebuild SQL with `:target_id` bound to each target's
+    #   id. For `:trigger`, the database trigger fires on entry INSERT;
+    #   `rebuild!` runs the same logical recompute against each target
+    #   the log references. The gem does NOT verify or recreate the
+    #   trigger here — `standard_ledger:doctor` is the deploy-time
+    #   check for trigger presence.
+    # - `:async` projections rebuild via the same per-target semantics as
+    #   `:inline` (delegates to `definition.projector_class.new.rebuild(target)`).
+    #   The mode difference is only in the after-create path (in-transaction
+    #   vs. post-commit job), not in the rebuild path, which always runs
+    #   synchronously.
     #
     # Atomicity: each (target, projection) pair runs in its own
     # transaction. A failure mid-loop is **not** rolled back — earlier
@@ -281,7 +293,7 @@ module StandardLedger
         validate_rebuildable_projector!(entry_class, definition)
 
         each_rebuild_target(entry_class, definition, target: target, batch_size: batch_size) do |t|
-          if definition.mode == :sql
+          if definition.mode == :sql || definition.mode == :trigger
             rebuild_one_sql(entry_class, definition, t)
           else
             rebuild_one(entry_class, definition, t)
@@ -420,13 +432,20 @@ module StandardLedger
       reflection.klass
     end
 
-    # Refuse to rebuild for modes that don't yet implement the
-    # log-replay path. `:inline`, `:sql`, and `:matview` are the supported
-    # modes today; `:async` and `:trigger` land with their own mode PRs.
+    # All five projection modes (`:inline`, `:async`, `:sql`, `:matview`,
+    # `:trigger`) implement a log-replay path through this method.
+    #
+    # `:async` and `:inline` share the same per-target rebuild semantics —
+    # both delegate to `definition.projector_class.new.rebuild(target)`.
+    # The difference between the two modes is only in the after-create
+    # path (in-transaction vs. post-commit job), not in the rebuild path,
+    # which always runs synchronously.
     def validate_rebuildable_mode!(entry_class, definition)
       return if definition.mode == :inline
+      return if definition.mode == :async
       return if definition.mode == :sql
       return if definition.mode == :matview
+      return if definition.mode == :trigger
 
       raise StandardLedger::Error,
             "rebuild! does not yet support mode: #{definition.mode.inspect} " \
@@ -463,10 +482,12 @@ module StandardLedger
     # rebuildable should extract a `Projection` subclass and implement
     # `rebuild(target)`.
     def validate_rebuildable_projector!(entry_class, definition)
-      # `:sql` mode carries its rebuild path in the recompute SQL itself —
-      # no projector class is required (and `via:` is rejected at
-      # registration). Skip the class-form preflight checks below.
+      # `:sql` and `:trigger` modes carry their rebuild path in the
+      # recompute / rebuild SQL itself — no projector class is required
+      # (and `via:` is rejected at registration). Skip the class-form
+      # preflight checks below.
       return if definition.mode == :sql
+      return if definition.mode == :trigger
 
       if definition.projector_class.nil?
         raise StandardLedger::NotRebuildable,
@@ -535,11 +556,12 @@ module StandardLedger
       )
     end
 
-    # `:sql` mode rebuild path: run the same recompute SQL the
-    # `after_create` callback runs, just bound to this target's id rather
-    # than the entry's foreign key. The recompute SQL is the entire
-    # contract for `:sql` projections — there's no projector class to
-    # invoke; the after-create and rebuild paths share one statement.
+    # `:sql` / `:trigger` mode rebuild path: run the recorded recompute
+    # SQL bound to this target's id. For `:sql` mode this is the same
+    # statement the `after_create` callback runs; for `:trigger` mode
+    # it's the rebuild SQL the host registered (the database trigger
+    # itself owns the after-INSERT path). Either way there's no
+    # projector class to invoke — the SQL is the entire contract.
     def rebuild_one_sql(entry_class, definition, target)
       target.class.transaction do
         sql = ActiveRecord::Base.sanitize_sql_array([ definition.recompute_sql, { target_id: target.id } ])

data/lib/tasks/standard_ledger.rake

@@ -0,0 +1,60 @@
+namespace :standard_ledger do
+  # PostgreSQL-only: queries `pg_trigger` directly. The only mode that
+  # registers a trigger today is `:trigger`, and the only adopter is
+  # nutripod-web (Postgres). SQLite has no comparable per-statement
+  # trigger introspection that makes sense for this gem's contract — if
+  # a non-Postgres host adopts `:trigger` mode in the future, they'll
+  # need to extend this task with a connection-adapter dispatch. The
+  # task is loud about its Postgres assumption: a `pg_trigger` query
+  # against a non-Postgres connection will raise, which is preferable
+  # to silently passing.
+  desc "Verify that every :trigger projection's trigger exists in the database (Postgres-only)"
+  task doctor: :environment do
+    require "standard_ledger"
+
+    # Discover entry classes by walking ActiveRecord descendants for
+    # ones that include `StandardLedger::Projector` and have at least
+    # one `:trigger` projection registered. The host's eager loading
+    # (Rails default in production / when explicitly invoked in dev)
+    # ensures all entry classes are loaded before this iterates.
+    entry_classes = ActiveRecord::Base.descendants.select { |klass|
+      klass.respond_to?(:standard_ledger_projections) &&
+        klass.standard_ledger_projections.any? { |d| d.mode == :trigger }
+    }
+
+    missing = []
+    entry_classes.each do |klass|
+      klass.standard_ledger_projections_for(:trigger).each do |definition|
+        # `pg_trigger.tgname` is the trigger's name as known to Postgres,
+        # but trigger names are scoped per-table — two tables can each
+        # have a trigger called e.g. `update_counts`. Join `pg_trigger`
+        # to `pg_class` and filter by the entry class's table name so the
+        # doctor reports presence on the *correct* table, not "anywhere
+        # in the schema". Use `klass.connection` (rather than
+        # `ActiveRecord::Base.connection`) so multi-DB setups query the
+        # connection that owns the entry class's table.
+        result = klass.connection.exec_query(
+          "SELECT 1 FROM pg_trigger t " \
+          "JOIN pg_class c ON c.oid = t.tgrelid " \
+          "WHERE t.tgname = $1 AND c.relname = $2 " \
+          "LIMIT 1",
+          "standard_ledger:doctor",
+          [ definition.trigger_name, klass.table_name ]
+        )
+        if result.rows.empty?
+          missing << "  #{klass.name}##{definition.target_association}: trigger #{definition.trigger_name.inspect} not found"
+        end
+      end
+    end
+
+    if missing.empty?
+      puts "All :trigger projections have their triggers present."
+    else
+      warn "Missing triggers detected:"
+      missing.each { |line| warn line }
+      warn ""
+      warn "Run the migration that creates the trigger, or check that the trigger name in `projects_onto` matches the actual trigger name in the schema."
+      exit 1
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_ledger
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -122,10 +122,11 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: StandardLedger captures the recurring 'append-only entry → N projection
-  updates' pattern as a declarative DSL on host ActiveRecord models. Supports inline,
-  sql, and matview projection modes (async and trigger modes land in subsequent releases);
-  enforces idempotency-by-unique-index; and provides a deterministic rebuild path
-  from the entry log.
+  updates' pattern as a declarative DSL on host ActiveRecord models. Supports five
+  projection modes — :inline, :async, :sql, :matview, :trigger — plus a deterministic
+  rebuild path from the entry log, ad-hoc materialized view refresh, and a doctor
+  rake task that verifies host-owned trigger presence. Enforces idempotency-by-unique-index
+  and immutability at the entry level.
 email:
 - code@jaryl.dev
 executables: []
@@ -145,9 +146,12 @@ files:
 - lib/standard_ledger/errors.rb
 - lib/standard_ledger/event_emitter.rb
 - lib/standard_ledger/jobs/matview_refresh_job.rb
+- lib/standard_ledger/jobs/projection_job.rb
+- lib/standard_ledger/modes/async.rb
 - lib/standard_ledger/modes/inline.rb
 - lib/standard_ledger/modes/matview.rb
 - lib/standard_ledger/modes/sql.rb
+- lib/standard_ledger/modes/trigger.rb
 - lib/standard_ledger/projection.rb
 - lib/standard_ledger/projector.rb
 - lib/standard_ledger/result.rb
@@ -155,6 +159,7 @@ files:
 - lib/standard_ledger/rspec/helpers.rb
 - lib/standard_ledger/rspec/matchers.rb
 - lib/standard_ledger/version.rb
+- lib/tasks/standard_ledger.rake
 homepage: https://github.com/rarebit-one/standard_ledger
 licenses:
 - MIT