standard_ledger 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c0d328d7c7f7c420d4b9abdcddeb6b1578b4c2798d33e0b53f44f36f3ed0e437
+  data.tar.gz: 481811ac4fb4b479d95e008798ce0c64182aa78c40f9d030866d8695d61bb953
+SHA512:
+  metadata.gz: 5bc96a821455069e8717e4c5904bafb8498d27f57f9b4b58a76266a47fb132bb3b1ff83fc08c3f36e8f939d2e5e1da7ceb16fc6035de2b458b26d2ef891c640e
+  data.tar.gz: 0751a94baaacaf4423452add7215c6a67ad79b2b3e81074180314ec96ffcdf9c9b02a4843bebc964f1fa3191a293e62275f2a537cfb5617fae8dd1bd18a804c5

data/CHANGELOG.md

@@ -0,0 +1,260 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The format
+is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.2.0] - 2026-05-05
+
+### Added
+- `StandardLedger::EventEmitter` — internal dispatcher that routes
+  gem events through `Rails.event.notify` on Rails 8.1+ and falls back
+  to `ActiveSupport::Notifications.instrument` on older Rails. Subscriber
+  exceptions are swallowed (printed via `warn`) so observability cannot
+  break the host's request path. All existing event names and payloads
+  are preserved — host subscribers via `ActiveSupport::Notifications.subscribe`
+  continue to work unchanged. Mirrors the `StandardCircuit::EventEmitter`
+  pattern for cross-gem consistency.
+- `:matview` projection mode + ad-hoc refresh API. The host owns the
+  PostgreSQL materialized view (created in a migration via `scenic` or
+  hand-rolled SQL); the gem owns the refresh schedule and the ad-hoc
+  refresh primitive.
+  - `projects_onto :assoc, mode: :matview, view: "view_name", refresh: { every: 5.minutes, concurrently: true }`
+    declares a matview projection. The `view:` keyword is required;
+    `refresh:` is optional metadata for the host's scheduler. Block-DSL
+    is not accepted (matview projections have no per-kind handlers —
+    they refresh on a schedule). `Definition` gains `view` and
+    `refresh_options` fields, populated only for `:matview` mode.
+  - `StandardLedger::Modes::Matview` strategy — `install!` records the
+    matview registration on the entry class without installing any
+    `after_create` callback (matview is scheduled, not entry-driven);
+    `.refresh!(view_name, concurrently:)` issues `REFRESH MATERIALIZED
+    VIEW [CONCURRENTLY] <view_name>` against the active connection,
+    instruments `<prefix>.projection.refreshed` on success and
+    `<prefix>.projection.failed` on raise (re-raising so the host's
+    scheduler / job runner sees the failure). The `view_name` is
+    validated against `/\A[a-zA-Z_][a-zA-Z0-9_.]*\z/` to refuse SQL
+    injection via crafted identifiers.
+  - `StandardLedger.refresh!(view_name, concurrently: nil)` — module-level
+    ad-hoc refresh API. `concurrently: nil` (default) consults
+    `Config#matview_refresh_strategy`; `true`/`false` overrides per call.
+    Returns a `Result` with `projections[:refreshed]` listing the view
+    refreshed; re-raises on SQL failure after firing the `failed` event.
+    Hosts call this at the end of read-your-write-critical operations
+    (e.g. luminality's `PromptPacks::DrawOperation` refreshing
+    `user_prompt_inventories` after a draw).
+  - `StandardLedger::MatviewRefreshJob` — thin `ActiveJob::Base` wrapper
+    around `StandardLedger.refresh!`. Hosts wire their scheduler
+    (SolidQueue Recurring Tasks, sidekiq-cron, etc.) at this job class
+    with `(view_name, concurrently:)` arguments. The gem deliberately
+    does not auto-schedule — schedule cadence and backend selection is a
+    host concern.
+  - `StandardLedger.rebuild!(EntryClass)` extends to `:matview`
+    projections: each registered matview projection triggers a single
+    `refresh!` (no per-target loop — the matview holds state for every
+    target in one relation). `target:` / `target_class:` scoping is
+    silently ignored for matviews (Postgres has no partial-refresh
+    primitive). `result.projections[:rebuilt]` includes a
+    `{ target_class: nil, target_id: nil, projection:, view: }` entry per
+    refreshed view.
+- `:sql` mode: single-`UPDATE` recompute projections that bind
+  `:target_id` from the entry's foreign key. Block-DSL takes a single
+  `recompute "..."` clause instead of per-kind `on(:kind)` handlers; the
+  same SQL serves both the after-create path and `StandardLedger.rebuild!`.
+  Fires inside `after_create` (in the entry's transaction), so failures
+  roll back the entry alongside the projection. Skips silently on nil
+  FK or false `if:` guard. Notifications under the configured prefix:
+  `<prefix>.projection.applied` (mode: `:sql`, `target: nil`, includes
+  `duration_ms`) and `<prefix>.projection.failed` (re-raises after the
+  payload is published). Registration validates that `:target_id`
+  appears in the SQL, that no `via:`/`lock:`/`permissive:` are supplied
+  (none are meaningful for `:sql` mode — the recompute SQL is the whole
+  contract), and that the block actually called `recompute` exactly once.
+  `StandardLedger.rebuild!` runs the same statement against each target
+  the log references; `target:` / `target_class:` / no-arg scoping
+  works the same as for `:inline`.
+- Integration specs for both new modes
+  (`spec/standard_ledger/sql_integration_spec.rb` and
+  `spec/standard_ledger/matview_integration_spec.rb`) cover the
+  end-to-end flows including registration validation, transactional
+  semantics, notifications, idempotent install, and rebuild paths.
+- Install generator: `rails g standard_ledger:install` writes
+  `config/initializers/standard_ledger.rb` with commented-out examples
+  covering every public `Config` setting (async retries, scheduler,
+  matview strategy, notification namespace, host Result interop). The
+  generator is idempotent — re-running on an existing initializer skips
+  with a clear message; pass `--force` to overwrite.
+- RSpec helpers behind an opt-in `require "standard_ledger/rspec"` (typically
+  loaded from the host's `spec/rails_helper.rb`):
+  - `post_ledger_entry(EntryClass).with(kind:, targets:, attrs:)` block
+    matcher — subscribes to `<namespace>.entry.created` for the duration of
+    the block and asserts that a matching event fired (or, in the negated
+    form, that none did). Honors a custom `notification_namespace`.
+  - `StandardLedger.with_modes(EntryClass => :inline) { ... }` block —
+    captures a thread-local override map so future async-mode projections
+    can be forced inline inside the block. Restored on block exit
+    (including on exception); nested blocks compose;
+    `StandardLedger.reset_mode_overrides!` clears the map (the auto-cleanup
+    hook calls this so host-configured Config survives between examples).
+    `StandardLedger.mode_override_for(entry_class)` reads the active
+    override for use by mode strategies as they ship. The `with_modes`
+    sugar is auto-included into RSpec example groups via
+    `StandardLedger::RSpec::Helpers`.
+  - Auto-cleanup hook (`RSpec.configure { before(:each) { StandardLedger.reset_mode_overrides! } }`)
+    so per-spec override state doesn't leak between examples without
+    clobbering the host's initializer-level Config.
+- `StandardLedger::Entry` runtime: read-only enforcement after persistence
+  (`save`/`update`/`destroy` raise `ActiveRecord::ReadOnlyRecord` when
+  `immutable: true`, the default). `immutable: false` opts out.
+- `StandardLedger::Entry` idempotency rescue: `create!` traps
+  `ActiveRecord::RecordNotUnique` against the configured
+  `[*scope, idempotency_key]` unique index, looks up the existing row,
+  and returns it with `idempotent? == true`. `idempotency_key: nil` skips
+  the rescue and behaves as a regular `create!`.
+- Lazy boot-time index validation: the first idempotent `create!` call on
+  an Entry verifies a unique index covers exactly `[*scope,
+  idempotency_key]` (set equality, order-insensitive); raises
+  `MissingIdempotencyIndex` with a clear message if missing or if the
+  index covers extra columns. Cached per-class.
+- `spec/dummy/` minimal Rails-free AR harness backed by SQLite
+  `:memory:`, loaded from `spec/spec_helper.rb` so AR-backed integration
+  tests can run without a host app.
+- `Projector#apply_projection!(definition)` — runtime evaluator that resolves
+  the target association, evaluates the optional `if:` guard against the
+  entry, looks up the per-kind handler (with `:_` wildcard fallback when
+  `permissive: true`), and invokes the handler or `via:` projector class.
+  Wraps the call in `target.with_lock { ... }` when `lock: :pessimistic`.
+  Skips silently when the target is `nil`; raises
+  `StandardLedger::UnhandledKind` when no handler matches and the projection
+  is non-permissive; raises `StandardLedger::Error` when the entry's kind
+  column is `nil`.
+- `Projector.standard_ledger_projections_for(mode)` — class-side filter that
+  returns the registered definitions whose `mode` matches the argument, for
+  the per-mode strategy classes (`Modes::Inline`, future `Modes::Async`,
+  ...) to discover which projections they own.
+- `projects_onto` registration validation: now raises `ArgumentError` when a
+  block and `via:` are both given (mutually exclusive), when the block is
+  empty (no `on(:kind)` calls), or when neither a block nor `via:` is
+  supplied.
+- `StandardLedger::Modes::Inline` runtime: applies inline-mode projections
+  inside `after_create`, transactional with the entry insert. A single
+  `after_create` callback is installed once per entry class on first
+  `:inline` registration (`Modes::Inline.install!`), and dispatches to
+  every `:inline` definition via `entry.apply_projection!`. Multiple
+  projections targeting the same association coalesce into a single
+  UPDATE per (entry, target): handlers run in declared order, then
+  `target.save!` persists the accumulated in-memory mutations once.
+  When any projection in a per-target group declares `lock: :pessimistic`,
+  the entire apply-then-save cycle is wrapped in `target.with_lock`, so
+  the row lock spans both handler invocation and the coalesced save —
+  closing the lost-update window that an inner-only lock would leave open
+  between lock release and save. Lock interpretation is the mode's
+  responsibility; `Projector#apply_projection!` no longer wraps in
+  `with_lock` itself. `:inline` mode now refuses to install on a non-AR
+  entry class — `Modes::Inline.install!` raises `ArgumentError` instead
+  of silently no-op-ing.
+- `StandardLedger.post(EntryClass, kind:, targets:, attrs:)` module API —
+  sugar over `EntryClass.create!` that maps `targets:` onto the entry's
+  `belongs_to` setters via `reflect_on_association`. Returns a
+  `StandardLedger::Result` (or the host's Result type when
+  `Config#custom_result?` is true). Wraps `ActiveRecord::RecordInvalid`
+  into `Result.failure(errors:)`; lets every other exception propagate so
+  the entry's transaction rolls back. `targets:` accepts model instances
+  only; pass foreign keys via `attrs:` (e.g. `voucher_scheme_id: 42`)
+  when an instance isn't on hand. `result.projections[:inline]` reflects
+  the projections that *actually* ran for this entry — projections
+  short-circuited by an `if:` guard, a nil target, or a permissive
+  no-handler miss are excluded, and an idempotent retry returns
+  `[]` (no projections fire on the rescue path).
+- ActiveSupport::Notifications instrumentation under the configured
+  `notification_namespace` prefix (default `"standard_ledger"`):
+  - `<prefix>.entry.created` — `after_commit on: :create`. Payload
+    `{ entry:, kind:, targets: { name => target } }`. Targets are
+    discovered from the entry's non-polymorphic `belongs_to` reflections.
+  - `<prefix>.projection.applied` — fired per inline projection on
+    success. Payload `{ entry:, target:, projection:, mode: :inline,
+    duration_ms: }`.
+  - `<prefix>.projection.failed` — fired per inline projection on raise,
+    before re-raising so the entry's transaction rolls back. Payload
+    `{ entry:, target:, projection:, error: }`.
+- Host Result interop in `StandardLedger.post`: when both
+  `config.result_class` and `config.result_adapter` are set, the adapter
+  is invoked with `success:, value:, errors:, entry:, idempotent:,
+  projections:` and its return value is returned as-is. Falls back to
+  `StandardLedger::Result` otherwise.
+- Integration spec (`spec/standard_ledger/inline_integration_spec.rb`)
+  exercising the end-to-end flow against the `spec/dummy/` SQLite
+  harness: multi-target fan-out, transactional rollback on projector
+  raise, idempotent-retry projection skip, all three notifications,
+  `lock: :pessimistic`, multi-counter coalescing, and Result interop.
+- `StandardLedger.rebuild!(EntryClass, target:, target_class:,
+  batch_size:)` log-replay path. Recomputes projections from the
+  entry log by delegating to the registered projector class's
+  `rebuild(target)`. Scope is one of: a single `target:` instance,
+  every row of `target_class:`, or (with neither) every projection
+  on the entry class for every target referenced by the log. Each
+  (target, projection) rebuild runs in its own transaction; per
+  design doc §5.5, failures mid-loop are NOT unwound across earlier
+  successes. Refuses block-form (delta) projections with
+  `StandardLedger::NotRebuildable`, and modes other than `:inline`
+  with `StandardLedger::Error` until their respective mode PRs land.
+  Returns a Result (or host's Result via the adapter) with
+  `projections[:rebuilt]` listing each (target_class, target_id,
+  projection) that was rebuilt.
+- `<prefix>.projection.rebuilt` notification fires for each
+  successful target rebuild. Payload `{ entry_class:, target:,
+  projection:, mode: }`. Joins the existing `entry.created`,
+  `projection.applied`, and `projection.failed` events under the
+  configured `notification_namespace`.
+- Integration spec
+  (`spec/standard_ledger/rebuild_integration_spec.rb`) covers the
+  end-to-end rebuild flow: 50-entry log replay restoring counters
+  after truncation, `target:` / `target_class:` / no-arg scoping,
+  block-form / no-`rebuild` / unsupported-mode raises, the
+  `projection.rebuilt` notification, and host Result interop.
+
+## [0.1.0] - 2026-05-04
+
+Initial scaffold. Establishes the gem layout, public API surface stubs, and the
+build/test pipeline. **Not yet usable in production** — see the design doc
+(`standard_ledger-design.md` in the workspace root) for the full v0.1 → v0.2
+roadmap.
+
+### Added
+- Rails Engine with `isolate_namespace StandardLedger`, no routes, no tables.
+- `StandardLedger.configure { |c| ... }` block with `Config` settings:
+  `default_async_job`, `default_async_retries`, `scheduler`,
+  `matview_refresh_strategy`, `result_class`, `result_adapter`,
+  `notification_namespace`.
+- `StandardLedger::Result` with `success?` / `failure?` / `idempotent?` /
+  `entry` / `value` / `errors` / `projections`. `Config#custom_result?`
+  governs whether the gem returns its own type or delegates to the host's via
+  `result_adapter`.
+- `StandardLedger::Entry` concern: `ledger_entry kind:, idempotency_key:,
+  scope:, immutable:` class macro stores configuration on the host model.
+  Read-only enforcement and idempotency rescue land in the next PR.
+- `StandardLedger::Projector` concern: `projects_onto target, mode:, via:,
+  if:, lock:, permissive:` class macro with block-DSL `on(:kind) { ... }`
+  registration. Stores `Definition` structs on the host model.
+- `StandardLedger::Projection` base class for class-form projectors with
+  `apply` and `rebuild` interface.
+- `StandardLedger::Modes::Inline` strategy class skeleton; `#call` raises
+  `NotImplementedError` until the nutripod vouchers integration lands.
+- Error hierarchy: `Error`, `UnhandledKind`, `NotRebuildable`,
+  `MissingIdempotencyIndex`, `PartialFailure`.
+- RSpec suite with passing specs for version, configure, reset, Config
+  defaults, and Result success/failure helpers.
+- GitHub Actions CI on Ruby 3.4.4 running RSpec + RuboCop.
+
+### Pending (tracked in design doc, lands in subsequent PRs)
+- Remaining mode implementations: `:async` (`ProjectionJob` + `with_lock`)
+  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
+[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/MIT-LICENSE

@@ -0,0 +1,21 @@
+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.

data/README.md

@@ -0,0 +1,287 @@
+# standard_ledger
+
+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)
+> for the full design and rollout plan.
+
+## What it is
+
+Across our four Rails apps (nutripod-web, luminality-web, fundbright-web,
+sidekick-web) we keep building the same thing: an immutable journal table
+whose rows update one or more cached aggregates on parent records. Inventory
+movements, voucher issuance, payment records, fulfillment records, prompt
+transactions, entitlement grants, validation outcomes, device firmware
+updates — same shape, eight different ad-hoc implementations.
+
+`standard_ledger` extracts the pattern into a single declarative DSL that
+lives on top of the host's existing ActiveRecord models. The gem **does not
+own the schema** — host apps already have entry tables and aggregate columns,
+and the gem adapts to them rather than replacing them.
+
+## Sketch
+
+```ruby
+class VoucherRecord < ApplicationRecord
+  include StandardLedger::Entry
+  include StandardLedger::Projector
+
+  ledger_entry kind:            :action,
+               idempotency_key: :serial_no,
+               scope:           :organisation_id
+
+  projects_onto :voucher_scheme, mode: :inline do
+    on(:grant)    { |scheme, _| scheme.increment(:granted_vouchers_count) }
+    on(:redeem)   { |scheme, _| scheme.increment(:redeemed_vouchers_count) }
+    on(:consume)  { |scheme, _| scheme.increment(:consumed_vouchers_count) }
+    on(:clawback) { |scheme, _| scheme.increment(:clawed_back_vouchers_count) }
+  end
+
+  projects_onto :customer_profile,
+                mode: :inline,
+                if:   -> { customer_profile_id.present? } do
+    on(:grant)    { |profile, _| profile.increment(:granted_vouchers_count) }
+    on(:redeem)   { |profile, _| profile.increment(:redeemed_vouchers_count) }
+    on(:consume)  { |profile, _| profile.increment(:consumed_vouchers_count) }
+    on(:clawback) { |profile, _| profile.increment(:clawed_back_vouchers_count) }
+  end
+end
+```
+
+Post an entry with the module API (sugar over `VoucherRecord.create!`):
+
+```ruby
+result = StandardLedger.post(VoucherRecord,
+  kind:    :grant,
+  targets: { voucher_scheme: scheme, customer_profile: profile },
+  attrs:   { organisation_id: org.id, serial_no: "v-2025-1" })
+
+result.success?     # => true
+result.entry        # => the persisted VoucherRecord
+result.idempotent?  # => false (true on retry against the same serial_no)
+result.projections  # => { inline: [:voucher_scheme, :customer_profile] }
+```
+
+Counters on both targets are incremented inside the same transaction as
+the INSERT — if any projection raises, the entry rolls back too. Posting
+twice with the same `serial_no` returns the original entry (with
+`idempotent? == true`) and skips the projection.
+
+Rebuild a target's projection from the log when its counters drift
+or a projection bug needs replaying — extract a `Projection` subclass
+that implements `rebuild(target)` and pass it via `via:`:
+
+```ruby
+class SchemeProjector < StandardLedger::Projection
+  def apply(scheme, entry)
+    scheme.increment(:"#{entry.action}_vouchers_count")
+    scheme.save!
+  end
+
+  def rebuild(scheme)
+    records = VoucherRecord.where(voucher_scheme_id: scheme.id)
+    scheme.update!(
+      granted_vouchers_count:  records.where(action: "grant").count,
+      redeemed_vouchers_count: records.where(action: "redeem").count
+    )
+  end
+end
+
+# Single target, single class, or every target across every projection.
+StandardLedger.rebuild!(VoucherRecord, target: scheme)
+StandardLedger.rebuild!(VoucherRecord, target_class: VoucherScheme)
+StandardLedger.rebuild!(VoucherRecord)
+```
+
+Each (target, projection) pair runs in its own transaction; failures
+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 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`:
+
+```ruby
+class VoucherRecord < ApplicationRecord
+  include StandardLedger::Entry
+  include StandardLedger::Projector
+
+  ledger_entry kind: :action, idempotency_key: :serial_no, scope: :organisation_id
+
+  belongs_to :voucher_scheme
+
+  projects_onto :voucher_scheme, mode: :sql do
+    recompute <<~SQL
+      UPDATE voucher_schemes SET
+        granted_vouchers_count     = (SELECT COUNT(*) FROM voucher_records WHERE voucher_scheme_id = :target_id AND action = 'grant'),
+        redeemed_vouchers_count    = (SELECT COUNT(*) FROM voucher_records WHERE voucher_scheme_id = :target_id AND action = 'redeem'),
+        consumed_vouchers_count    = (SELECT COUNT(*) FROM voucher_records WHERE voucher_scheme_id = :target_id AND action = 'consume'),
+        clawed_back_vouchers_count = (SELECT COUNT(*) FROM voucher_records WHERE voucher_scheme_id = :target_id AND action = 'clawback')
+      WHERE id = :target_id
+    SQL
+  end
+end
+```
+
+The gem binds `:target_id` from the entry's foreign key. The recompute
+SQL is the entire contract — `:sql` projections are naturally
+rebuildable: `StandardLedger.rebuild!` runs the same statement against
+every target the log references.
+
+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):
+
+```ruby
+class PromptTxn < ApplicationRecord
+  include StandardLedger::Entry
+  include StandardLedger::Projector
+
+  belongs_to :user_profile
+
+  ledger_entry kind: :event, idempotency_key: nil
+
+  projects_onto :user_profile,
+                mode:    :matview,
+                view:    "user_prompt_inventories",
+                refresh: { every: 5.minutes, concurrently: true }
+end
+
+# Schedule the recurring refresh from the host (SolidQueue Recurring
+# Tasks, sidekiq-cron, etc.) targeting:
+#   StandardLedger::MatviewRefreshJob
+#   args: ["user_prompt_inventories", { concurrently: true }]
+
+# Ad-hoc refresh after a critical write:
+StandardLedger.refresh!(:user_prompt_inventories)               # honors Config#matview_refresh_strategy
+StandardLedger.refresh!("user_prompt_inventories", concurrently: true)
+```
+
+`StandardLedger.rebuild!(PromptTxn)` is equivalent to refreshing every
+`:matview` projection on the entry class — for matview, 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.
+
+Note: the default `:concurrent` strategy (and `concurrently: true`) requires
+a unique index on the matview — Postgres rejects `REFRESH MATERIALIZED VIEW
+CONCURRENTLY` otherwise. Add a unique index in the host migration that
+creates the view, or set `Config#matview_refresh_strategy = :blocking` (or
+pass `concurrently: false` per-call) if a unique index isn't an option.
+
+Five projection modes — pick per declaration:
+
+| Mode | Where the work runs | Transactional? | Rebuildable? |
+|---|---|---|---|
+| `:inline` | `after_create`, in the entry's transaction | yes | yes (if projector implements `rebuild`) |
+| `:async` | `after_create_commit` job, `with_lock` | no | yes (if projector implements `rebuild`) |
+| `:sql` | `after_create`, single `UPDATE ... FROM (SELECT ...)` | yes | yes (rebuild = same SQL) |
+| `:trigger` | the database, on INSERT | yes (same statement) | yes (host-owned trigger; gem records rebuild SQL) |
+| `:matview` | scheduled `REFRESH MATERIALIZED VIEW CONCURRENTLY` | no | trivially (refresh = rebuild) |
+
+## Installation
+
+The gem is private during incubation. Pin from git:
+
+```ruby
+gem "standard_ledger", git: "https://github.com/rarebit-one/standard_ledger", ref: "<sha>"
+```
+
+Then run the install generator to drop a configured initializer in place:
+
+```bash
+bin/rails g standard_ledger:install
+```
+
+This writes `config/initializers/standard_ledger.rb` with commented-out
+examples covering every public `Config` setting — uncomment and edit only
+what you want to override. The generator is idempotent; re-running on an
+existing initializer skips with a clear message (pass `--force` to
+overwrite).
+
+A typical configuration looks like:
+
+```ruby
+StandardLedger.configure do |c|
+  c.default_async_retries     = 3
+  c.scheduler                 = :solid_queue
+  c.matview_refresh_strategy  = :concurrent
+
+  # Optional — return the host's Result type from StandardLedger.post:
+  c.result_class   = ApplicationOperation::Result
+  c.result_adapter = ->(success:, value:, errors:, entry:, idempotent:, projections:) {
+    ApplicationOperation::Result.new(success:, value: value || entry, errors:)
+  }
+end
+```
+
+## Testing
+
+The gem ships an opt-in RSpec support file. Hosts add this to their
+`spec/rails_helper.rb`:
+
+```ruby
+require "standard_ledger/rspec"
+```
+
+That registers a `before(:each)` hook that calls `StandardLedger.reset!`
+between examples (so per-spec configuration doesn't leak), and exposes:
+
+- `post_ledger_entry(EntryClass).with(...)` — a block matcher that
+  subscribes to the `<namespace>.entry.created` notification for the
+  duration of the block and asserts an entry of the expected class was
+  written (with optional `kind:`/`targets:`/`attrs:` constraints).
+
+  ```ruby
+  it "records a voucher grant" do
+    expect {
+      Vouchers::IssueOperation.call(scheme: scheme, profile: profile)
+    }.to post_ledger_entry(VoucherRecord).with(
+      kind:    :grant,
+      targets: { voucher_scheme: scheme, customer_profile: profile },
+      attrs:   { serial_no: "v-2025-1" }
+    )
+  end
+  ```
+
+- `with_modes(EntryClass => :inline) { ... }` — forces specific entry
+  classes' projections to run inline for the duration of the block. The
+  override is thread-local and restored on block exit, so async-mode
+  projections can be exercised end-to-end in a unit spec without a job
+  runner.
+
+  ```ruby
+  it "fast-runs an async projection inline" do
+    with_modes(PaymentRecord => :inline) do
+      Orders::CheckoutOperation.call(...)
+    end
+  end
+  ```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Relationship to standard_audit
+
+Different gems, different concerns:
+
+- **`standard_audit`** — "user X took action Y on target Z," free-form
+  metadata, no projection.
+- **`standard_ledger`** — "this delta updates these targets," typed kind,
+  mandatory projection.
+
+A single host operation typically writes one of each, in one transaction.
+Neither subsumes the other.
+
+## License
+
+MIT. See [MIT-LICENSE](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/generators/standard_ledger/install/install_generator.rb

@@ -0,0 +1,34 @@
+require "rails/generators"
+
+module StandardLedger
+  module Generators
+    # Installs StandardLedger in a host Rails application.
+    #
+    # Writes config/initializers/standard_ledger.rb with commented-out
+    # examples covering the public Config DSL.
+    #
+    # Idempotent: re-running on an existing initializer logs and skips.
+    # Pass +--force+ to overwrite.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc <<~DESC
+        Installs StandardLedger. Writes config/initializers/standard_ledger.rb
+        with commented-out examples covering the public Config DSL.
+
+        The generator is idempotent — already-installed initializer is skipped
+        with a clear message. Pass --force to overwrite.
+      DESC
+
+      def create_initializer_file
+        path = "config/initializers/standard_ledger.rb"
+        if File.exist?(File.join(destination_root, path)) && !options.force?
+          say_status("skip", "#{path} already present, skipping (use --force to overwrite)", :yellow)
+          return
+        end
+
+        template "initializer.rb.tt", path
+      end
+    end
+  end
+end