standard_ledger 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 411ad3db9a71ca8adddecc84d407dabddbd167c7ed00e534e975a700b3a2e8f2
-  data.tar.gz: aeb938a4e1fb16c6df67fbb76a93a5687c40116be040df5da44e65541ce4d282
+  metadata.gz: 74163637dfcb14c019f6481391644b45849cad04108b580e5a8de524720ed1ca
+  data.tar.gz: d022e52db16ba6e838c47c9e94ead8fa1f876afb37ffa5f8b3b5390d4877b157
 SHA512:
-  metadata.gz: 2d0cd11b66c8d22b76cf9444e8840d92c35ccd81d4eba224e8123b208aa5c706503bc9cf6e9bbf1dc7bff564df4728adac79eeeacc254a976efb8cfa1fd0907a
-  data.tar.gz: 5f352fe00a36e01ef43aa4d8efb197a32314c43f0b31657342996dc91bcf422933e4076b851813bd6c6fd7ab69a52d18f53e9650fbced76292b9deca52b6ce0b
+  metadata.gz: e9b7f1b51851431f1e44c5129dac815517ce064860a83d210d8f94ed8b30e7a90dc393d92af4e702516fcc0a804e613cc7859d582b4ce042d31220970835fb5d
+  data.tar.gz: c11d063fd3e01c8feb06176742df0167ff363c375de4c03d979a7dee52ca21e1388917fd2e1b10e770409b2a703aa5f223f496bc8f2619368b40fa0c323a1cb9

data/CHANGELOG.md

@@ -6,7 +6,50 @@ project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
-Nothing yet.
+## [0.5.1] - 2026-09-24
+
+### Fixed
+- The `post_ledger_entry` RSpec matcher now listens on the channel
+  `StandardLedger::EventEmitter` emits through. It only subscribed to
+  `ActiveSupport::Notifications`, but on Rails 8.1+ the gem emits through
+  `Rails.event.notify`, so the matcher saw no events at all: every positive
+  expectation failed and every `not_to post_ledger_entry` passed without
+  checking anything. When `EventEmitter.rails_event_available?` is true, the
+  matcher now subscribes a collector to `Rails.event` for the block and
+  unsubscribes it afterwards.
+
+### Documentation
+- README **Testing** section (and `AGENTS.md`) said the RSpec support hook
+  calls `StandardLedger.reset!`. It calls `reset_mode_overrides!`, which keeps
+  host initializer configuration intact.
+- The engine initializer comment now tells hosts to subscribe via
+  `Rails.event.subscribe` on Rails 8.1+ rather than
+  `ActiveSupport::Notifications.subscribe`.
+
+## [0.5.0] - 2026-09-22
+
+### Changed
+- `required_ruby_version` raised from `>= 3.4` to `>= 4.0`, and the repo's
+  `.ruby-version` moved from 3.4.4 to 4.0.1 to match. The 3.4 floor was never
+  exercised — CI has only ever run the 4.0.x matrix — and every consumer runs
+  4.0.x. This aligns the gem with the rest of the `standard_*` family.
+
+### Documentation
+- New README **Events** section documenting all five lifecycle events
+  (`entry.created`, `projection.applied`, `projection.failed`,
+  `projection.refreshed`, `projection.rebuilt`), their payloads, and the four
+  places a payload shape differs from the obvious one: `:sql` mode sends
+  `target: nil`, `:matview` events carry `view:`/`concurrently:` instead of
+  `entry:`/`target:`, `projection.rebuilt` carries `entry_class:` rather than
+  `entry:`, and input errors (matview name validation,
+  `RefreshInsideTransaction`) propagate without firing `projection.failed`.
+  Also records that subscriber exceptions are swallowed by design.
+- README installation now shows the RubyGems pin. It still said "private during
+  incubation, pin from git"; the gem has been on RubyGems since 2026-05-07 and
+  the last git-pinned consumer was converted in 2026-07.
+- `CLAUDE.md` consumer list corrected: it listed two consumers and claimed
+  git+tag consumption. There are four (`fundbright-web`, `luminality-web`,
+  `sidekick-web`, `jumpdrive-web`), all plain rubygems.
 
 ## [0.4.0] - 2026-05-07
 
@@ -423,7 +466,10 @@ roadmap.
   and `:trigger` (host-owned, gem records rebuild SQL).
 - `standard_ledger:doctor` rake task (verifies trigger presence, etc.).
 
-[Unreleased]: https://github.com/rarebit-one/standard_ledger/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/rarebit-one/standard_ledger/compare/v0.5.1...HEAD
+[0.5.1]: https://github.com/rarebit-one/standard_ledger/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/rarebit-one/standard_ledger/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/rarebit-one/standard_ledger/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/rarebit-one/standard_ledger/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/rarebit-one/standard_ledger/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/rarebit-one/standard_ledger/releases/tag/v0.1.0

data/LICENSE

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

data/README.md

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

data/lib/standard_ledger/engine.rb

@@ -12,8 +12,10 @@ module StandardLedger
 
     initializer "standard_ledger.notifications", after: :load_config_initializers do
       # Notification wiring lands here in a follow-up PR. Today this is a
-      # no-op — the gem emits events but ships no internal subscribers; hosts
-      # subscribe directly via ActiveSupport::Notifications.subscribe.
+      # no-op — the gem emits events but ships no internal subscribers. On
+      # Rails 8.1+ events go through `Rails.event.notify`, so hosts subscribe
+      # with `Rails.event.subscribe`; on older Rails they fall back to
+      # ActiveSupport::Notifications (see StandardLedger::EventEmitter).
     end
 
     # Engines auto-discover `lib/tasks/*.rake` in most Rails versions, but

data/lib/standard_ledger/rspec/matchers.rb

@@ -1,5 +1,28 @@
 require "rspec/expectations"
 require "active_support/notifications"
+require "standard_ledger/event_emitter"
+
+module StandardLedger
+  module RSpec
+    # Collects `<namespace>.entry.created` payloads from `Rails.event` for the
+    # duration of a `post_ledger_entry` block. A dedicated object (not a
+    # Proc) because `EventReporter#unsubscribe` matches with `===`.
+    #
+    # @api private
+    class RailsEventCollector
+      attr_reader :payloads
+
+      def initialize(event_name)
+        @event_name = event_name
+        @payloads = []
+      end
+
+      def emit(event)
+        @payloads << event[:payload] if event[:name] == @event_name
+      end
+    end
+  end
+end
 
 # `post_ledger_entry` — assert that a block of code wrote a ledger entry.
 #
@@ -22,7 +45,9 @@ require "active_support/notifications"
 #   expect { ... }.to_not post_ledger_entry(VoucherRecord)
 #
 # The matcher subscribes to `<namespace>.entry.created` for the duration of
-# the block, captures every fired event, and asserts that at least one event
+# the block, on whichever channel `StandardLedger::EventEmitter` emits through
+# (`Rails.event` on Rails 8.1+, `ActiveSupport::Notifications` otherwise),
+# captures every fired event, and asserts that at least one event
 # matched the expected class (and, when chained, the expected `kind`,
 # `targets`, and `attrs`). The notification namespace is read from
 # `StandardLedger.config.notification_namespace`, so a host that customised
@@ -71,10 +96,35 @@ RSpec::Matchers.define :post_ledger_entry do |entry_class|
   # Helpers
   # ----------------------------------------------------------------------
 
+  # Listens on the same channel `EventEmitter.emit` picks. Listening only on
+  # AS::Notifications meant that on Rails 8.1 (where emit goes through
+  # `Rails.event`) the matcher saw nothing — every positive expectation
+  # failed and every negated one passed vacuously.
   def capture_entry_created_events(&block)
+    if StandardLedger::EventEmitter.rails_event_available?
+      capture_via_rails_event(&block)
+    else
+      capture_via_notifications(&block)
+    end
+  end
+
+  def capture_via_rails_event(&block)
+    bus = ::Rails.event
+    collector = StandardLedger::RSpec::RailsEventCollector.new(notification_event_name)
+    bus.subscribe(collector)
+
+    begin
+      block.call
+    ensure
+      bus.unsubscribe(collector)
+    end
+
+    collector.payloads
+  end
+
+  def capture_via_notifications(&block)
     events = []
-    name = notification_event_name
-    subscriber = ActiveSupport::Notifications.subscribe(name) do |*args|
+    subscriber = ActiveSupport::Notifications.subscribe(notification_event_name) do |*args|
       events << ActiveSupport::Notifications::Event.new(*args).payload
     end
 

data/lib/standard_ledger/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_ledger
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Jaryl Sim
@@ -134,7 +134,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- MIT-LICENSE
+- LICENSE
 - README.md
 - Rakefile
 - lib/generators/standard_ledger/install/install_generator.rb
@@ -175,7 +175,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/MIT-LICENSE

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