standard_ledger 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 411ad3db9a71ca8adddecc84d407dabddbd167c7ed00e534e975a700b3a2e8f2
-  data.tar.gz: aeb938a4e1fb16c6df67fbb76a93a5687c40116be040df5da44e65541ce4d282
+  metadata.gz: 89af058a7d94051bc75f8e853d1be397270b52bc5a02020dfdd41484c6cacda5
+  data.tar.gz: 50eef558981621f3561c42095d294f87f09d7ed18e8fc5a5919c0801262f257b
 SHA512:
-  metadata.gz: 2d0cd11b66c8d22b76cf9444e8840d92c35ccd81d4eba224e8123b208aa5c706503bc9cf6e9bbf1dc7bff564df4728adac79eeeacc254a976efb8cfa1fd0907a
-  data.tar.gz: 5f352fe00a36e01ef43aa4d8efb197a32314c43f0b31657342996dc91bcf422933e4076b851813bd6c6fd7ab69a52d18f53e9650fbced76292b9deca52b6ce0b
+  metadata.gz: 16d8c529a99909adb4739feb0ea76e996ebd709c044bc56dd2722bc041f4c17670d2bb383a48072df9a686bc02b1c2a49add8206618ddeb7fb86dd2b45e61c9f
+  data.tar.gz: 5f152b064c69e8da3f7e2767c4b3914da197599ed64ecc8e512be6c34e334af25337f83fd68080c7811a3f4772df647d5799ae635cb0116409286455bd86bf0e

data/CHANGELOG.md

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

data/LICENSE

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

data/README.md

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

data/lib/standard_ledger/version.rb

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

data/MIT-LICENSE

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