standard_ledger 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74163637dfcb14c019f6481391644b45849cad04108b580e5a8de524720ed1ca
-  data.tar.gz: d022e52db16ba6e838c47c9e94ead8fa1f876afb37ffa5f8b3b5390d4877b157
+  metadata.gz: ddedb70c2937f7108178cce27f7150b58c39c5aadfdab2561947b626bd345d9c
+  data.tar.gz: be910d616703d17691bdc6f184247b5efe78bc959006c24f43ee4bfbeb5df263
 SHA512:
-  metadata.gz: e9b7f1b51851431f1e44c5129dac815517ce064860a83d210d8f94ed8b30e7a90dc393d92af4e702516fcc0a804e613cc7859d582b4ce042d31220970835fb5d
-  data.tar.gz: c11d063fd3e01c8feb06176742df0167ff363c375de4c03d979a7dee52ca21e1388917fd2e1b10e770409b2a703aa5f223f496bc8f2619368b40fa0c323a1cb9
+  metadata.gz: 1bd764a4596fb6468f5ffa9b2d51e39a5203f6135bbdbde6cacec33091aa0e86cedaa1393392f417378a720f6e26987438c8a46fc80028204ecf0250ed3a7c49
+  data.tar.gz: 829aad11a875317df036555736281f0ca6d961045bd3a5b2dd6090592ce0aabce772583b34d7fd403c69a4f331bb11f46e6a9622ccc62f510fb0574dea8bd85a

data/CHANGELOG.md

@@ -6,6 +6,134 @@ project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-24
+
+The Phase 4 release. The removals the cleanup plan scheduled for it (the
+`scheduler` config, `PartialFailure`, and the engine's no-op initializer)
+already shipped in 0.6.0, and 0.6.0 deprecated nothing, so this release only
+changes how `refresh!` reports failures. It is a minor bump because hosts that
+report refresh failures themselves should delete that code.
+
+### Changed
+- **`StandardLedger.refresh!` reports SQL failures through `Rails.error`.**
+  When the `REFRESH` statement raises, the gem emits `projection.failed` (as
+  before), then calls `Rails.error.report(error, handled: false,
+  severity: :error, context: { view:, concurrently: }, source:
+  "standard_ledger")`, then re-raises. It falls back to
+  `ActiveSupport.error_reporter` outside Rails. A reporter that raises is
+  ignored, so it can never mask the refresh error. Input errors raised before
+  any SQL runs are not reported (`ArgumentError`, `RefreshInsideTransaction`).
+  **No double reports:** Rails' `ErrorReporter` flags a reported exception
+  and skips it when the same object is reported again. That covers a host
+  rescue that reports and re-raises, and the executor wrapping the job.
+- The `:auto` catalog-probe failure report (handled, `:warning`) now goes
+  through the same `StandardLedger.report_error` helper (`@api private`).
+  Its payload is unchanged.
+
+### Upgrade notes (0.6.x → 0.7.0)
+1. Bump to `gem "standard_ledger", "~> 0.7"`. Nothing was removed, so no code
+   change is required.
+2. **Optional cleanup:** delete any report-and-re-raise rescue around
+   `refresh!`. Grepped `origin/main` of all consumers on 2026-09-24:
+   - luminality-web `app/jobs/refresh_admin_dashboard_metrics_job.rb:20-27`
+     (`rescue StandardError => e; Rails.error.report(e, handled: true,
+     context: { view: "admin_dashboard_metrics" }); raise`). Delete the rescue
+     and fix the header comment ("…does not report").
+   - sidekick-web `app/jobs/refresh_materialized_views_job.rb` has no rescue.
+     Its refresh failures are now reported by the gem, with view context,
+     before the job runner sees them.
+   - jumpdrive-web and fundbright-web don't call `refresh!`.
+3. **Expect a different Sentry grouping context** for refresh failures:
+   `source: "standard_ledger"` and `context.view`. The error class and
+   backtrace are unchanged.
+4. Sorbet apps: regenerate the gem RBI (`bin/tapioca gem standard_ledger`).
+   jumpdrive-web's `control-plane/config/initializers/standard_ledger.rb:12-13`
+   still mentions the removed `scheduler`/`default_async_*` config in a
+   comment. The comment is historical and harmless.
+
+## [0.6.0] - 2026-09-24
+
+A breaking release. The declarative projection engine is removed, and the gem
+now ships only what its four consumers use: `Entry`, `post`, `Projection`,
+`refresh!`, `Config`, the events, and the RSpec matcher. Before this release,
+every consumer's `main` (jumpdrive-web, sidekick-web, fundbright-web,
+luminality-web) was grepped (app, lib, config, spec, db). None of them
+referenced anything listed under **Removed**.
+
+### Removed
+- **Projection DSL:** `StandardLedger::Projector`, `projects_onto`,
+  `standard_ledger_projections`, `standard_ledger_projections_for`, and the
+  `Projector::Definition` struct.
+- **All projection modes:** `StandardLedger::Modes::Inline`, `::Async`, `::Sql`,
+  `::Trigger`, `::Matview` (its refresh logic moved to the private
+  `StandardLedger::Matview`), and `:manual`.
+- **Jobs:** `StandardLedger::ProjectionJob` and
+  `StandardLedger::MatviewRefreshJob`. The gem no longer depends on `activejob`
+  (or declares `concurrent-ruby` directly).
+- **`StandardLedger.rebuild!`**. `Projection#rebuild` stays as a method your own
+  code calls.
+- **Test-mode overrides:** `StandardLedger.with_modes`,
+  `StandardLedger.mode_override_for`, `StandardLedger.reset_mode_overrides!`,
+  `StandardLedger::RSpec::Helpers`, and the `before(:each)` hook that
+  `require "standard_ledger/rspec"` used to register. The file now defines only
+  the `post_ledger_entry` matcher.
+- **`rake standard_ledger:doctor`** and `StandardLedger::Engine`. The engine
+  had no routes or tables, and its initializer was a no-op. The install
+  generator still works without it.
+- **Errors:** `StandardLedger::PartialFailure` (never raised) and
+  `StandardLedger::UnhandledKind` (only raised by the projection DSL).
+- **Config:** `default_async_job`, `default_async_retries`, and `scheduler`.
+  None of them was read by anything outside the engine, and no consumer
+  initializer sets them (jumpdrive-web's generated initializer only has them
+  as comments).
+- **Events:** `<prefix>.projection.applied` and `<prefix>.projection.rebuilt`
+  (only the engine emitted them). `entry.created`, `projection.refreshed` and
+  `projection.failed` are unchanged.
+- `StandardLedger.post` no longer reports `projections[:inline]`. It always
+  passes `projections: {}`. The keyword is still passed to `result_adapter`,
+  so existing six-keyword adapters keep working.
+
+### Added
+- `StandardLedger.refresh!(view, concurrently: :auto)` uses
+  `REFRESH MATERIALIZED VIEW CONCURRENTLY` only when it can succeed: no open
+  transaction, the view is populated (`pg_class.relispopulated`), and it has a
+  valid unique index without a `WHERE` clause or expressions (`pg_index`).
+  Otherwise it runs a plain refresh. If the catalog probe raises, the error is
+  reported through `Rails.error` (`handled: true`, `severity: :warning`,
+  `source: "standard_ledger"`) and the refresh falls back to plain. This
+  replaces the rescue-and-retry around `PG::ObjectNotInPrerequisiteState` /
+  `RefreshInsideTransaction` in sidekick-web's `RefreshMaterializedViewsJob`.
+  It was verified against PostgreSQL 17 for an empty view, unique, non-unique,
+  partial and expression indexes, a refresh inside a transaction, and a
+  missing view.
+- `Config#matview_refresh_strategy` accepts `:auto`.
+
+### Changed
+- `refresh!` now raises `ArgumentError` for an unknown `concurrently:` value
+  or an unknown `matview_refresh_strategy`. Before, an unknown strategy
+  silently meant a blocking refresh.
+- `RefreshInsideTransaction`'s message now suggests `concurrently: :auto`.
+- The gemspec summary, description, README, design doc, `AGENTS.md`, and
+  `docs/MIGRATION_GUIDE.md` now describe the slimmed gem. The design doc keeps
+  a history section on the removed engine (§8).
+
+### Upgrade note (0.5.x → 0.6.0)
+1. Bump to `gem "standard_ledger", "~> 0.6"`. No consumer on 2026-09-24
+   referenced anything removed, so no application code changes are needed.
+2. **Sorbet/Tapioca apps:** regenerate the RBIs (`bin/tapioca gem
+   standard_ledger` and `bin/tapioca dsl`). Delete any stale
+   `sorbet/rbi/dsl/standard_ledger/{projector,projection_job,matview_refresh_job}.rbi`.
+   All four consumers carry these today, and they describe constants that no
+   longer exist, so `tapioca dsl --verify` will flag them.
+3. If your initializer sets `c.default_async_job`, `c.default_async_retries`
+   or `c.scheduler`, delete the line (it now raises `NoMethodError`). The
+   generated initializer only has them as comments, which you can remove too.
+4. Optional: replace hand-rolled "try CONCURRENTLY, fall back to plain"
+   logic with `StandardLedger.refresh!(view, concurrently: :auto)`, or set
+   `c.matview_refresh_strategy = :auto`.
+5. If you ever did depend on the engine, pin `~> 0.5` and see git tag
+   `v0.5.1` and design doc §8.
+
 ## [0.5.1] - 2026-09-24
 
 ### Fixed
@@ -466,7 +594,8 @@ 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.5.1...HEAD
+[Unreleased]: https://github.com/rarebit-one/standard_ledger/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/rarebit-one/standard_ledger/compare/v0.5.1...v0.6.0
 [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