concerns_on_rails 1.28.2 → 1.28.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0a05169c98ce90531027509dbbdd4f00722678e2cfe246a5692484d9a12a111
-  data.tar.gz: 10d2cebdced9beed7b677b18a0b8c85dc82d1125672ada2f5c5f12b995fa1933
+  metadata.gz: 615b4ddcff3ebdffc7e32f618731510bf5e386fa015cb0a1ae958a4e6fb04d1c
+  data.tar.gz: 723b3ae2077f43fc5771947d2e610f011ca83ee8215b78fb0894a04400362220
 SHA512:
-  metadata.gz: 756646b2232fa428250bf502fbb7ce87a44bf39830d9ae4810e50482315394fa1aa0b0e1ed47fb9a4b87d677d11507adfb7e14206f0b27119235060c74f1513b
-  data.tar.gz: '08b14db3a23711b0531447c773b2d831ec37fcf8c2b84fa59b4f203c7375923297e3a9dd93597b6e0091f18e677752be0dca67b913a4a3b1dd61fb042b417fad'
+  metadata.gz: 352ff281ce000213b296a1b8ccae97478d6a6726644fb6bcf69c5f4e05d94c57e674f5cff59f3ed0ff8d90891c90b6ebc53affdec5f47ea64102ca88a3c40a0e
+  data.tar.gz: 595236a2464439aa26d10ed118fc5d307ca47022cac8e5c9cae6077419da39dc7a3fc2d085534bfb2d36bdf3625c99442054dc7fd5868be71b9034923aa66e11

data/CHANGELOG.md

@@ -1,5 +1,167 @@
 <!-- CHANGELOG.md -->
 
+## 1.28.4 (2026-09-16)
+
+Eleven bug-fix PRs (#91–#101) from the audit of the shipped gem, released as a
+patch: no new concerns, no new options, no migrations, no dependency changes.
+Two close fail-open holes (WebhookVerifiable, Encryptable); the rest are
+correctness fixes for behaviour the docs already promised. Every fix ships with
+a regression spec that fails on 1.28.3. 1460 examples, 0 failures.
+
+### Security
+- **Controllers::WebhookVerifiable**: verification could be skipped entirely,
+  leaving the action to run on an unverified — possibly forged — payload. Two
+  paths: `webhook_verification_failed` returned `nil` when there was no response
+  object to render into, which left the `before_action` chain unhalted; and
+  `webhook_rule_for_action` returned `nil` (read as "no rule applies, carry on")
+  when `action_name` was unresolvable or `""`. Both fail closed now — the first
+  raises, the second falls back to the catch-all rule, or to a lone declared
+  rule, and verifies. With several action-specific rules and no catch-all it
+  raises rather than verifying against an arbitrary provider's secret, which
+  would reject a valid delivery as "signature invalid". The render guard also
+  honours a `render_error` override on its own, so a controller supplying one
+  but no response object renders its rejection instead of raising. Mirrors the
+  fix Authorizable got in 1.22. A resolvable action simply not covered by any
+  rule still passes through untouched. (#92)
+- **Models::Encryptable**: `<field>_ciphertext` — documented for "asserting no
+  plaintext is at rest" — returned the caller's **plaintext** whenever the value
+  had not round-tripped through the database (a new record, or any pending
+  assignment: exactly the state inside a `before_save`, a validator, or an
+  error-reporting path), so `log.info(user.ssn_ciphertext)` wrote the SSN
+  straight to the log. It returns `nil` in that state now. `<field>_encrypted?`
+  used a bare `.present?`, true for plaintext too; it now checks that what is
+  stored really is an encryption envelope, via the new
+  `Support::Encryptor.envelope?`. (#97)
+
+### Fixed
+- **Models::Aliasable**: an aliased `belongs_to` carrying `counter_cache:`
+  double-counted. The alias copy kept the `:counter_cache` option, and because
+  the `#association` override maps the alias back to the same association
+  object, ActiveRecord's counter-cache pass fired once per name — the parent's
+  count came out doubled on create and doubled on destroy, drifting permanently
+  negative once rows predating the alias were removed. The copy no longer
+  carries the option; the source reflection still owns the counter. (#93)
+- **Controllers::Paginatable**: `?page=99999999999999999999` was an
+  unauthenticated 500 — `(page - 1) * per_page` produced an offset no backend
+  accepts (`StatementInvalid` on a relation, `RangeError` on an Array). `page`
+  is now clamped to `MAX_PAGE` (1,000,000) and comes back as an empty page past
+  the end; `per_page` is held under the matching `MAX_PER_PAGE`, since with
+  `max_per_page: 0` ("no cap") the identical value overflowed `LIMIT` instead.
+  `paginate_by` also validates `per_page` now: 0 and negatives raise
+  `ArgumentError` at class-load time instead of misbehaving on every request
+  (`per_page: -1` means `LIMIT -1`, i.e. NO LIMIT on SQLite and MySQL —
+  serialising the whole table; `per_page: 0` made every page permanently empty).
+  A negative `max_per_page` still means "no cap", as documented. (#94)
+- **Models::Taggable**: `all_tags` raised on PostgreSQL for any model that also
+  includes `Models::Sortable` — `SELECT DISTINCT` cannot be ordered by a column
+  outside the select list, and Sortable installs exactly such a `default_scope`.
+  The inherited `ORDER BY` is dropped with `reorder(nil)`; the result is sorted
+  in Ruby anyway. Passed on SQLite, which permits it. (#95)
+- **Models::Lockable, Models::Stateable**: `ActiveRecord::Rollback` raised from
+  an `after_lock` / `after_transition` hook did nothing when the call was nested
+  inside a caller's own transaction — a bare `transaction` joins the enclosing
+  one and Rails swallows `Rollback` without rolling anything back. Both open a
+  savepoint now (`requires_new: true`), so the documented abort works: Lockable
+  no longer leaves a row locked in the database while reporting `false` in
+  memory (with `lock_access!`'s idempotency guard then making every retry a
+  no-op), and Stateable no longer commits a state change its hook asked to
+  abort. Stateable's `<event>!` also took its return value from `update!`, which
+  runs *before* the hook, so an aborted transition reported success —
+  `raise unless ticket.archive!` never fired and `transition_all` counted a row
+  it had rolled back. It reports `false` now, which `transition_all` treats as
+  the documented failed-record signal. Note `transition_all` opens one savepoint
+  per record. (#96)
+- **Support::ErrorEnvelope**: the `render_error` lookup was public-only, but
+  `render_error` is very often declared under `private` — the idiomatic way to
+  keep a controller helper from becoming a routable action. Those overrides were
+  silently ignored and the gem's inline envelope rendered instead, so an app
+  rendering RFC 9457 problem+json got the wrong shape for every Authorizable
+  403, WebhookVerifiable 401, Throttleable 429 and CursorPaginatable 400, with
+  no error or warning. Now `respond_to?(:render_error, true)`, the spelling
+  Authorizable already used for `current_user`. Controllers::Deprecatable keeps
+  its own copy of that check before rendering a sunset 410, and it had the same
+  blind spot — a private `render_error` with no response object skipped the 410
+  and served the sunset action. (#98)
+- **Controllers::Deprecatable**: `deprecate_actions` mutated the caller's own
+  `Time`. `Time#utc` is an alias of `#gmtime` and converts the receiver IN
+  PLACE, so a host passing a frozen constant (`SUNSET = Time.new(...).freeze`)
+  got a `FrozenError` while the controller class body was still loading — the
+  app would not boot — and an unfrozen `Time` was silently rewritten to UTC
+  behind the caller's back. Now `getutc`. (#99)
+- **Controllers::Filterable**: a boolean `false` read as "filter not supplied",
+  so `filter_by :active` could never select the inactive rows — `false.blank?`
+  is true, the rule was skipped and the UNFILTERED relation came back. Only JSON
+  request bodies were affected; a query string carries the String `"false"`,
+  which is not blank. Everything genuinely empty — `nil`, `""`, `"   "`, `[]`,
+  `{}` — is still skipped, and in `scope:` mode (which discards the value) an
+  explicit `false` still means "do not apply this scope". (#100)
+- **Models::Stateable**: `transition_all` silently skipped rows whose state is
+  NULL. `where.not(state: to)` compiles to `NOT (state = 'x')`, which SQL
+  three-valued logic evaluates to NULL — never TRUE — for a NULL state, so those
+  rows were dropped from the batch and from the returned count even though they
+  ARE eligible (`may_<event>?` returns true for them and the per-record
+  `<event>!` succeeds). The predicate is NULL-safe now. (#101)
+
+### Internal
+- **Specs**: the Aliasable join-alias SQL assertion accepts both the Rails 8.1
+  `AS`-qualified table alias and the older unqualified form, so the suite passes
+  on Rails 8.1 — unblocking the pending Rails 8.1 dependency bumps. No library
+  change. (#91)
+
+## 1.28.3 (2026-09-16)
+
+Three merged PRs from the September loop (#41, #43, #52), shipped as a patch at
+the maintainer's request: a SoftDeletable bug fix (`restore_all` /
+`really_destroy_all` dropped the caller's own predicate on the soft-delete
+column), a ColumnGuard change (every missing column reported in one error with
+one migration command) and an additive SoftDeletable `cascade:` option for
+has_many / has_one dependents. No new migrations or runtime dependencies.
+1396 examples, 0 failures.
+
+### Fixed
+- **Models::SoftDeletable**: `restore_all` and `really_destroy_all` now honour a
+  caller's predicate on the soft-delete column. Both used to `unscope` the
+  column outright to peel off the default scope's `deleted_at IS NULL`, which
+  also dropped `deleted_within(1.hour)` / `where(deleted_at: range)` /
+  `only_deleted` — so `User.deleted_within(1.hour).restore_all` restored the
+  whole trash can and `only_deleted.really_destroy_all` widened to the whole
+  relation. Only the default scope's own predicate is peeled now; predicates on
+  other columns (a host model's own `default_scope` included) are untouched. The
+  scopes themselves still unscope the column: chain `soft_deleted.where(...)`,
+  not `where(...).soft_deleted`. (#41)
+- **Models::Anonymizable**: the stamp column's migration hint now carries its
+  type (`anonymized_at:datetime`). (#43)
+
+### Changed
+- **Support::ColumnGuard**: a macro that finds several missing columns now
+  reports them all in one `ArgumentError` — `'street', 'city' and 'zip' do not
+  exist …` — with a single combined migration command
+  (`bin/rails generate migration AddAddressableColumnsToUsers street:string
+  city:string zip:string`) instead of failing boot once per column. Single-
+  column wording and generator name are unchanged. (#43)
+
+### Added
+- **Models::SoftDeletable**: `soft_deletable_by … cascade: %i[comments cover]`
+  soft-deletes has_many / has_one dependents with the record (same
+  transaction, same timestamp, through their own `soft_delete!` so hooks and
+  nested cascades run) and restores exactly those on `restore!` — a dependent
+  deleted independently earlier stays deleted. New `soft_delete!(at:)` keyword.
+  With a cascade configured, `soft_delete_all` / `restore_all` take the
+  per-record path. `belongs_to`, HABTM and `:through` are rejected at class
+  load; the target model must include SoftDeletable (checked at class load when
+  it already resolves, otherwise on the first cascade). (#52)
+
+### Notes
+`cascade:` is off by default — models without it behave exactly as before.
+`restore!` matches cascaded dependents by the parent's exact `deleted_at`, so
+give the columns `precision: 6` (the Rails 7 default) if two parents may be
+deleted within one second. With a cascade configured the single-`UPDATE` fast
+paths of `soft_delete_all` / `restore_all` are disabled (a bulk `UPDATE` cannot
+follow associations). Anything matching `/does not exist/` on a one-column
+ColumnGuard failure still matches — only the several-columns wording and
+generator name changed. The README's "use instead" table no longer lists
+association-cascade soft delete as a reason to reach for paranoia / discard.
+
 ## 1.28.2 (2026-09-11)
 
 Six merged enhancement PRs from the September loop (#42, #84, #59 via #90, #80,

data/README.md

@@ -146,9 +146,9 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 - **Twenty-six model concerns + sixteen controller concerns**, all production-ready
 - **One include, one macro** — no boilerplate, no glue code
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable), and both load **lazily**: an app that never includes those concerns never loads them. Depends on `activerecord`/`actionpack`/`activesupport`, not the full `rails` meta-gem; controller concerns have zero extra deps
-- **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early — with a ready-to-paste `rails generate migration` hint when it doesn't
+- **Schema-validated configuration** — every macro checks that the configured columns exist and raises `ArgumentError` early — listing *every* missing column at once, with one ready-to-paste `rails generate migration` command that adds them all
 - **Composable** — concerns are independent; mix and match per model
-- **Tested like an app, not a snippet** — **1,360 RSpec examples** run against a real database on every CI build
+- **Tested like an app, not a snippet** — **1,460 RSpec examples** run against a real database on every CI build
 - **Documented twice** — everything in this README also lives as a per-concern page on the [docs site](https://vsn2015.github.io/concerns_on_rails), searchable and deep-linkable
 
 ---
@@ -467,13 +467,21 @@ User.soft_delete_all      # soft-deletes all matching records; returns the count
 User.destroy_all          # alias of soft_delete_all (kept for backwards compatibility; returns a count, not records)
 User.really_destroy_all   # hard-deletes the records matching the CURRENT relation (soft-deleted included)
 User.restore_all          # restores the matching soft-deleted records; returns the count
+
+User.deleted_within(1.hour).restore_all        # undo a bulk delete — only the last hour's trash
+User.deleted_within(30.days).really_destroy_all # purge recent trash; older rows untouched
+User.only_deleted.really_destroy_all           # empty the trash can, nothing else
 ```
 
 A record that fails to transition raises `ActiveRecord::RecordNotSaved` and rolls the whole
 batch back. With `touch: false` and no overridden hooks, `soft_delete_all` / `restore_all`
-collapse to a single `UPDATE`. Note that `really_destroy_all` peels the soft-delete
-predicate off the relation, so `only_deleted.really_destroy_all` widens to the whole
-relation — purge trash with `User.soft_deleted.delete_all` instead.
+collapse to a single `UPDATE`. Both `restore_all` and `really_destroy_all` peel off **only the
+default scope's own** `deleted_at IS NULL`: a predicate *you* put on the column — `deleted_within`,
+`where(deleted_at: range)`, `only_deleted` — survives, as does any other default scope the model
+declares. (Previously they unscoped the column outright, so `deleted_within(1.hour).restore_all`
+restored the whole trash can and `only_deleted.really_destroy_all` widened to the whole relation.)
+The *scopes* still unscope the column, so chain them first: `soft_deleted.where(...)`, not
+`where(...).soft_deleted`.
 
 **Scope-name collisions**
 
@@ -490,6 +498,30 @@ Expirable) without a collision. `prefix: true` uses the configured field name. W
 passed, scope names, the default scope, and the emitted SQL are unchanged. See the
 Publishable section above for how `prefix:`/`suffix:` differ across the gem.
 
+**Cascading to dependents**
+
+```ruby
+class Post < ApplicationRecord
+  include ConcernsOnRails::SoftDeletable
+  has_many :comments
+  has_one  :cover
+  soft_deletable_by :deleted_at, cascade: %i[comments cover]   # Comment and Cover include SoftDeletable too
+end
+
+post.soft_delete!        # comments + cover soft-deleted in the same transaction, with the post's exact timestamp
+post.restore!            # brings back the comments/cover the cascade deleted — NOT a comment someone trashed last week
+post.soft_delete!(at: 1.day.ago)   # new at: keyword — backdate, or hand a timestamp down a cascade
+```
+
+Dependents go through their own `soft_delete!` / `restore!` (hooks and nested cascades run). A dependent
+that fails — whether it raises or just fails validation — aborts the cascade with
+`ActiveRecord::RecordNotSaved` and rolls the parent back with it, so you never end up with a deleted
+parent and a live child. Declare the cascaded associations **above** `soft_deletable_by`; the macro
+resolves them at class load. Restore matches on the parent's timestamp, so independently
+deleted dependents keep their own. `cascade:` accepts `has_many` / `has_one` (no `belongs_to`, HABTM or
+`:through`) whose models include SoftDeletable; with a cascade configured `soft_delete_all` / `restore_all`
+take the per-record path (a bulk `UPDATE` cannot follow associations).
+
 **Lifecycle hooks** — override these methods on the model:
 
 ```ruby
@@ -1385,6 +1417,7 @@ Patient.where_email("a@b.com")       # chainable Relation (accepts arrays too)
 **Notes**
 - The declared column must be `text`/binary (it stores an opaque envelope, not the logical type); a blind-index column holds a 64-char hex digest — add an index on it.
 - Ciphertext is non-deterministic (random IV), so `where(ssn: ...)` matches nothing — query through a blind index. `nil` stays `nil`; presence checks work normally.
+- `ssn_ciphertext` is `nil` while the field has an unsaved change (so it can never return the plaintext you just assigned), and `ssn_encrypted?` asks whether what is stored really is an envelope.
 - Never `update_column(s)` an encrypted field — that bypasses the type and writes raw plaintext. Declaring a field with both `encryptable` and `auditable_by` raises (either order).
 - Wrong key / tampered ciphertext / malformed envelope raise `Encryption::DecryptionError`. Encrypted field names are auto-registered with Rails' `filter_parameters` (via the gem's railtie), so they're redacted from request logs.
 - Reach for [`lockbox`](https://github.com/ankane/lockbox) or Rails 7+ native `encrypts` when you need key rotation today or Rails-managed key infrastructure (rotation is planned — the envelope already reserves the `key_id` byte).
@@ -2183,7 +2216,7 @@ Both forms reference the same module, so you can freely mix them.
 | Need | Use instead |
 |------|-------------|
 | Complex state machines (callbacks, transition logging) | [`aasm`](https://github.com/aasm/aasm) |
-| Association-cascade soft delete / sentinel-aware unique indexes | [`paranoia`](https://github.com/rubysherpas/paranoia) or [`discard`](https://github.com/jhawthorn/discard) |
+| Sentinel-aware unique indexes on soft-deleted rows (`deleted_at` in the index) | [`paranoia`](https://github.com/rubysherpas/paranoia) or [`discard`](https://github.com/jhawthorn/discard) |
 | Tagging with contexts, ownership, or tag clouds | [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on) |
 | Full-text search with ranking / stemming | [`pg_search`](https://github.com/Casecommons/pg_search) / Elasticsearch |
 | Versioned audit trails with undo/reify, who-dunnit queries, or association tracking | [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) / [`audited`](https://github.com/collectiveidea/audited) |
@@ -2217,9 +2250,9 @@ Point your agent at `llms.txt` for an overview, or paste a single concern's `.md
 
 ```sh
 bundle install                                  # install dev dependencies
-bundle exec rspec                               # run the test suite (1,360 examples)
+bundle exec rspec                               # run the test suite (1,460 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.28.2.gem      # install locally
+gem install ./concerns_on_rails-1.28.4.gem      # install locally
 
 # Preview the docs site locally (GitHub Pages serves docs/ as-is):
 cd docs && python3 -m http.server 8000          # → http://localhost:8000

data/lib/concerns_on_rails/controllers/deprecatable.rb

@@ -141,8 +141,15 @@ module ConcernsOnRails
           # Module#=== checks the real ancestry, so `when Time` alone would
           # miss it — and Time.current / 1.month.from_now are exactly the
           # values Rails hosts pass.
-          when ActiveSupport::TimeWithZone, Time then value.utc
-          when DateTime then value.to_time.utc
+          # getutc, NOT utc: Time#utc is an alias of #gmtime, which converts the
+          # receiver IN PLACE and returns self. A host passing a frozen
+          # constant (SUNSET = Time.new(...).freeze) got a FrozenError while
+          # the controller class body was still loading — the app would not
+          # boot — and an unfrozen Time was silently rewritten to UTC behind
+          # the caller's back. TimeWithZone#utc is a harmless reader, but
+          # getutc is correct for both, so the branch stays single.
+          when ActiveSupport::TimeWithZone, Time then value.getutc
+          when DateTime then value.to_time.getutc
           when Date then Time.utc(value.year, value.month, value.day)
           when String then parse_deprecation_string(value)
           end
@@ -247,7 +254,12 @@ module ConcernsOnRails
         return unless deprecation_sunset_reached?(rule)
 
         message = "This endpoint was sunset on #{rule[:sunset_at].httpdate}."
-        return unless respond_to?(:render_error) || (respond_to?(:response) && response)
+        # respond_to?(..., true) for the same reason Support::ErrorEnvelope
+        # uses it: render_error is very often declared under `private`. The
+        # public-only check skipped the 410 for exactly those controllers and
+        # let the sunset action run — a fail-open on the branch whose job is to
+        # stop serving the endpoint.
+        return unless respond_to?(:render_error, true) || (respond_to?(:response) && response)
 
         ConcernsOnRails::Support::ErrorEnvelope.render(self, message: message, status: :gone, code: "endpoint_sunset")
       end

data/lib/concerns_on_rails/controllers/filterable.rb

@@ -42,12 +42,12 @@ module ConcernsOnRails
         end
       end
 
-      # Apply all declared filters to a relation based on params. Blank values
-      # are skipped so unset filters don't narrow the relation.
+      # Apply all declared filters to a relation based on params. Unset values
+      # are skipped so absent filters don't narrow the relation.
       def filtered(relation)
         self.class.filterable_rules.each do |field, options|
           value = params[field]
-          next if value.blank?
+          next if filterable_unset?(value)
 
           relation = apply_filter(relation, field, value, options)
         end
@@ -56,11 +56,29 @@ module ConcernsOnRails
 
       private
 
+      # NOT `value.blank?`: `false.blank?` is true, so a genuine boolean false
+      # read as "filter not supplied" and the relation came back UNFILTERED —
+      # `filter_by :active` could never select the inactive rows. Query strings
+      # were unaffected (they carry the String "false", which is not blank), so
+      # this only bit JSON request bodies, where the value really is `false`.
+      # Everything actually empty — nil, "", "   ", [], {} — is still skipped.
+      def filterable_unset?(value)
+        return false if value == false
+        return true if value.nil?
+
+        value.respond_to?(:blank?) ? value.blank? : false
+      end
+
       def apply_filter(relation, field, value, options)
         if options[:with]
           options[:with].call(relation, value)
         elsif options[:scope]
-          relation.public_send(options[:scope])
+          # Scope mode discards the value, so an explicit `false` can only mean
+          # "do not apply this scope" — applying it would hand the client the
+          # exact opposite of what it asked for. (A query string still carries
+          # the String "false", which has always triggered the scope; only a
+          # real boolean is read as a negation.)
+          value == false ? relation : relation.public_send(options[:scope])
         elsif filterable_scalar?(value)
           relation.where(field => value)
         else

data/lib/concerns_on_rails/controllers/paginatable.rb

@@ -36,6 +36,21 @@ module ConcernsOnRails
       LABEL = "ConcernsOnRails::Controllers::Paginatable".freeze
       DEFAULT_PER_PAGE = 25
       DEFAULT_MAX_PER_PAGE = 200
+      # Upper bound on the requested page. `page` is untrusted input and its
+      # only job is to become `(page - 1) * per_page`, so an unbounded value
+      # produced an offset no backend can take: the relation branch raised
+      # StatementInvalid and Array#[] raised RangeError ("bignum too big to
+      # convert into `long'") — a 500 from `?page=99999999999999999999`.
+      # Clamping keeps the request in range; the page is far past any real
+      # dataset, so it simply comes back empty. Deep pagination at this depth
+      # wants Controllers::CursorPaginatable instead.
+      MAX_PAGE = 1_000_000
+      # The same guard for per_page. `max_per_page: 0` is documented as "no
+      # cap", and with no cap the identical untrusted value overflowed LIMIT
+      # instead of OFFSET — the same unauthenticated 500, one option away. "No
+      # cap" means no CONFIGURED cap, not an unbounded LIMIT; a page of a
+      # million records is already far past what any client can render.
+      MAX_PER_PAGE = 1_000_000
 
       included do
         class_attribute :paginatable_per_page, default: DEFAULT_PER_PAGE
@@ -59,8 +74,8 @@ module ConcernsOnRails
         #   paginate_by per_page: 50, max_per_page: 500, link_header: false
         def paginate_by(per_page: DEFAULT_PER_PAGE, max_per_page: DEFAULT_MAX_PER_PAGE, link_header: true,
                         page_param: nil, per_page_param: nil, style: :flat, window: nil)
-          self.paginatable_per_page = per_page.to_i
-          self.paginatable_max_per_page = max_per_page.to_i
+          self.paginatable_per_page = paginatable_per_page!(per_page)
+          self.paginatable_max_per_page = paginatable_max_per_page!(max_per_page)
           self.paginatable_link_header = link_header ? true : false
           self.paginatable_window = paginatable_window!(window)
           defaults = paginatable_style_params!(style)
@@ -79,6 +94,29 @@ module ConcernsOnRails
           end
         end
 
+        # per_page must be positive. A bare `.to_i` let a negative through, and
+        # `LIMIT -1` means NO LIMIT on SQLite and MySQL — so `per_page: -1`
+        # silently serialized the entire table on every request, while
+        # `per_page: 0` made every page permanently empty. Both are broken
+        # configuration with no sane reading, so they raise at class-load time
+        # rather than misbehaving on every request.
+        def paginatable_per_page!(value)
+          size = value.to_i
+          return size if size.positive?
+
+          raise ArgumentError, "#{LABEL}: per_page: must be a positive integer (got #{value.inspect})"
+        end
+
+        # max_per_page does NOT raise: "0 or a negative integer disables the
+        # cap" is this option's documented contract, so rejecting a negative
+        # would fail the boot of an app that is configured exactly as written —
+        # and on a patch upgrade at that. Normalize to 0 instead; the reader's
+        # guard only asks whether the cap is positive.
+        def paginatable_max_per_page!(value)
+          size = value.to_i
+          size.negative? ? 0 : size
+        end
+
         # nil / false disable the window (no `pages:` key). `0` is meaningful:
         # first, current and last only.
         def paginatable_window!(value)
@@ -206,14 +244,18 @@ module ConcernsOnRails
       # Both readers route through ScalarParam: `?page[]=1` / `?page[x]=1`
       # arrive as Array/Parameters, and calling .to_i on those was a 500.
       def pagination_page
-        [ConcernsOnRails::Support::ScalarParam.to_i(pagination_param(self.class.paginatable_page_param), default: 0), 1].max
+        requested = ConcernsOnRails::Support::ScalarParam.to_i(pagination_param(self.class.paginatable_page_param), default: 0)
+        requested.clamp(1, MAX_PAGE)
       end
 
       def pagination_per_page
         requested = ConcernsOnRails::Support::ScalarParam.to_i(pagination_param(self.class.paginatable_per_page_param), default: 0)
         requested = self.class.paginatable_per_page if requested < 1
         cap = self.class.paginatable_max_per_page
-        cap.positive? ? [requested, cap].min : requested
+        requested = [requested, cap].min if cap.positive?
+        # Applied even when a cap IS configured: `max_per_page: 10**30` is its
+        # own way of asking for the overflow back.
+        [requested, MAX_PER_PAGE].min
       end
 
       # Dig the configured path out of params: `["page"]` → params[:page];

data/lib/concerns_on_rails/controllers/webhook_verifiable.rb

@@ -178,19 +178,68 @@ module ConcernsOnRails
       # Single funnel for all failure outcomes (override point). Uses
       # Respondable's render_error when available, otherwise the same inline
       # envelope as Throttleable / Idempotentable.
+      #
+      # Fails CLOSED, matching Authorizable#authorization_denied: when there is
+      # nothing to render the rejection into, raise. Returning nil here (the
+      # pre-1.29 behavior) left the before_action chain unhalted, so the action
+      # ran on an unverified — possibly forged — payload.
       def webhook_verification_failed(message:, status:, code:)
-        return unless respond_to?(:response) && response
+        unless webhook_can_render?
+          raise "ConcernsOnRails::Controllers::WebhookVerifiable: rejection for " \
+                "'#{webhook_action_name || '(unknown action)'}' could not be rendered " \
+                "(no response object) — refusing to fail open"
+        end
 
         ConcernsOnRails::Support::ErrorEnvelope.render(self, message: message, status: status, code: code)
       end
 
       private
 
+      # Mirrors the render path in Support::ErrorEnvelope: a render_error
+      # override is enough on its own, so a controller that supplies one but no
+      # response object still rejects properly instead of raising.
+      def webhook_can_render?
+        respond_to?(:render_error, true) || (respond_to?(:response) && response)
+      end
+
+      # nil when the action cannot be determined. `action_name` can also be ""
+      # (truthy), which a bare `unless action` guard would let through.
+      def webhook_action_name
+        return nil unless respond_to?(:action_name)
+
+        name = action_name.to_s
+        name.empty? ? nil : name
+      end
+
       def webhook_rule_for_action
-        action = respond_to?(:action_name) ? action_name.to_s : nil
-        return nil unless action
+        rules = self.class.webhook_rules
+        return nil if rules.empty?
+
+        action = webhook_action_name
+        # Fail closed: rules ARE declared but we cannot tell which action this
+        # is, so "no rule applies" is not a conclusion we may draw. Previously
+        # an unresolvable action_name skipped verification entirely and every
+        # webhook was accepted without a signature check.
+        return webhook_unresolvable_action_rule(rules) if action.nil?
+
+        rules.find { |rule| rule[:actions].empty? || rule[:actions].include?(action) }
+      end
 
-        self.class.webhook_rules.find { |rule| rule[:actions].empty? || rule[:actions].include?(action) }
+      # Which rule to verify against when the action cannot be resolved. A
+      # catch-all is well defined, and so is a lone rule. Several
+      # action-specific rules are NOT: each carries its own provider secret and
+      # scheme, so picking the first would reject a perfectly valid delivery
+      # with "signature invalid" — sending that provider chasing a signing bug
+      # that does not exist. Raise instead. Still fails closed either way; this
+      # one just says what actually went wrong.
+      def webhook_unresolvable_action_rule(rules)
+        catch_all = rules.find { |rule| rule[:actions].empty? }
+        return catch_all if catch_all
+        return rules.first if rules.one?
+
+        raise "ConcernsOnRails::Controllers::WebhookVerifiable: cannot tell which action this request is " \
+              "(no action_name) and #{rules.size} action-specific rules are declared with no catch-all — " \
+              "refusing to verify against an arbitrary rule's secret"
       end
 
       def webhook_render_outcome(rule, outcome)

data/lib/concerns_on_rails/models/aliasable.rb

@@ -274,6 +274,15 @@ module ConcernsOnRails
         #     polymorphic).
         def aliasable_copy_options(src)
           opts = src.options.dup
+          # The SOURCE reflection already owns the counter. Carrying the option
+          # onto the copy makes ActiveRecord::CounterCache count it twice: it
+          # iterates _reflections and calls association(name) for each
+          # counter-cached one, and the #association override below maps the
+          # alias back to the SAME association object, so increment_counters
+          # fires once per name with no dedup guard. The parent's count came
+          # out doubled on create and doubled on destroy — drifting
+          # permanently negative once rows predating the alias were removed.
+          opts.delete(:counter_cache)
           if opts[:through]
             opts[:source] ||= aliasable_through_source_name(src)
           else

data/lib/concerns_on_rails/models/anonymizable.rb

@@ -96,7 +96,7 @@ module ConcernsOnRails
           anonymizable_apply_options(stamp, clear_audit_trail)
 
           ensure_columns!(LABEL, fields)
-          ensure_columns!(LABEL, anonymizable_stamp) if anonymizable_stamp
+          ensure_columns!(LABEL, anonymizable_stamp, types: :datetime) if anonymizable_stamp
           self.anonymizable_rules = anonymizable_rules.merge(fields.to_h { |f| [f.to_sym, strategy] })
 
           anonymizable_define_scopes(prefix, suffix)

data/lib/concerns_on_rails/models/encryptable.rb

@@ -271,11 +271,34 @@ module ConcernsOnRails
         end
 
         def encryptable_define_helpers(field)
-          # Raw stored value: the DB ciphertext once persisted (before the type
-          # deserializes it). Useful for migrations, debugging, and asserting no
-          # plaintext is at rest.
-          define_method("#{field}_ciphertext") { read_attribute_before_type_cast(field) }
-          define_method("#{field}_encrypted?") { read_attribute_before_type_cast(field).present? }
+          # The value AT REST — the column's stored content, before the type
+          # deserializes it. Useful for migrations, debugging, and asserting no
+          # plaintext is at rest. nil while the field carries an unsaved change.
+          #
+          # That last clause is the fix: this used to return
+          # read_attribute_before_type_cast unconditionally, and for a column
+          # overridden with `attribute` that is the caller's PLAINTEXT whenever
+          # the value has not round-tripped through the database — a new record,
+          # or any record with a pending assignment (i.e. exactly the state
+          # inside a before_save, a validator, or an error-reporting path). A
+          # reader named `_ciphertext`, documented for "asserting no plaintext
+          # is at rest", handed back the SSN, so `log.info(user.ssn_ciphertext)`
+          # wrote it straight to the log.
+          define_method("#{field}_ciphertext") do
+            next nil if new_record? || public_send("#{field}_changed?")
+
+            read_attribute_before_type_cast(field)
+          end
+
+          # True only when what is stored really is an encryption envelope. The
+          # old `.present?` was true for plaintext too, so the natural guard
+          # `raise unless user.ssn_encrypted?` passed on a record whose column
+          # held the raw value. Note this is honestly false under
+          # `on_missing_key: :passthrough`, where plaintext at rest is the
+          # opted-into behavior.
+          define_method("#{field}_encrypted?") do
+            ConcernsOnRails::Support::Encryptor.envelope?(public_send("#{field}_ciphertext"))
+          end
         end
 
         # find_by_<field> / where_<field> / <field>_fingerprint for equality

data/lib/concerns_on_rails/models/lockable.rb

@@ -313,7 +313,15 @@ module ConcernsOnRails
       def lockable_write_with_hooks(previous_values)
         completed = false
         begin
-          transaction do
+          # requires_new: a bare `transaction` JOINS an enclosing one rather
+          # than opening a savepoint, and Rails then swallows
+          # ActiveRecord::Rollback without rolling anything back. Inside a
+          # caller's `ApplicationRecord.transaction { user.lock_access! }`,
+          # a hook raising Rollback left the row locked in the database while
+          # the ensure below restored locked_at = nil in memory and this
+          # method returned false — and the idempotency guard in
+          # lock_access! then made every retry a no-op.
+          transaction(requires_new: true) do
             yield
             completed = true
           end

data/lib/concerns_on_rails/models/soft_deletable.rb

@@ -22,6 +22,9 @@ module ConcernsOnRails
         class_attribute :soft_delete_scope_names, instance_accessor: false,
                                                   default: SCOPE_BASES.to_h { |b| [b, b] }.freeze
         class_attribute :soft_delete_captured_scopes, instance_accessor: false, default: {}.freeze
+        # has_many / has_one association names soft-deleted and restored along
+        # with this record (their models must include SoftDeletable too).
+        class_attribute :soft_delete_cascade, instance_accessor: false, default: [].freeze
 
         define_soft_delete_scopes(nil, nil)
         self.soft_delete_captured_scopes =
@@ -45,11 +48,23 @@ module ConcernsOnRails
         # Example:
         #   soft_deletable_by :deleted_at, touch: false
         #   soft_deletable_by :deleted_at, default_scope: false  # don't hide deleted rows from .all
-        def soft_deletable_by(field = nil, touch: true, default_scope: true, prefix: nil, suffix: nil)
+        #   soft_deletable_by :deleted_at, cascade: %i[comments attachments]
+        #
+        # `cascade:` names has_many / has_one associations whose records are
+        # soft-deleted with the parent (inside its transaction, with the
+        # parent's exact timestamp, through their own soft_delete! — hooks and
+        # nested cascades included) and restored with it. Restore only touches
+        # dependents carrying the parent's timestamp, so a comment someone
+        # deleted independently last week stays deleted when the post comes
+        # back. Every target model must include SoftDeletable. With a cascade
+        # configured the single-UPDATE batch fast paths are disabled, since a
+        # bulk UPDATE could not follow the associations.
+        def soft_deletable_by(field = nil, touch: true, default_scope: true, prefix: nil, suffix: nil, cascade: nil)
           self.soft_delete_field = field || :deleted_at
           self.soft_delete_touch = touch
           self.soft_delete_default_scope = default_scope
           ensure_columns!("ConcernsOnRails::Models::SoftDeletable", soft_delete_field, types: :datetime)
+          self.soft_delete_cascade = soft_delete_validate_cascade!(cascade)
           return unless prefix || suffix
 
           define_soft_delete_scopes(prefix, suffix)
@@ -82,22 +97,27 @@ module ConcernsOnRails
           soft_delete_all
         end
 
-        # Hard-delete every record matching the CURRENT relation — including
-        # soft-deleted rows (only the soft-delete column's predicates are
-        # peeled off). Note that `unscope` also drops a caller's own condition
-        # on that column, so `only_deleted.really_destroy_all` widens to the
-        # whole relation — use `soft_deleted.delete_all` to purge trash only.
+        # Hard-delete every record matching the CURRENT relation — soft-deleted
+        # rows included. Only the default scope's own `deleted_at IS NULL` is
+        # peeled off; a caller's predicate on the column survives, so
+        # `only_deleted.really_destroy_all` purges the trash and nothing else
+        # and `deleted_within(30.days).really_destroy_all` purges recent trash.
         # (Before 1.22 this ignored the relation entirely and hard-deleted the
-        # complete table.)
+        # complete table; until this fix it unscoped the column outright, which
+        # widened `only_deleted.really_destroy_all` to the whole relation.)
         def really_destroy_all
-          all.unscope(where: soft_delete_field).delete_all
+          soft_delete_without_default_scope.delete_all
         end
 
-        # Restore every soft-deleted record (mirror of soft_delete_all):
-        # Integer count, RecordNotSaved + rollback on failure, single UPDATE
-        # when the fast path applies.
+        # Restore every soft-deleted record in the relation (mirror of
+        # soft_delete_all): Integer count, RecordNotSaved + rollback on
+        # failure, single UPDATE when the fast path applies. Built against the
+        # current relation rather than routed through the `soft_deleted` scope,
+        # whose `unscope(where: deleted_at)` also stripped the CALLER's predicate
+        # on the column — `deleted_within(1.hour).restore_all` restored the
+        # whole trash can. (Same defect `publish_all` fixed in 1.27.)
         def restore_all
-          deleted = all.public_send(soft_delete_scope_names.fetch(:soft_deleted))
+          deleted = soft_delete_without_default_scope.where.not(soft_delete_field => nil)
           return deleted.update_all(soft_delete_field => nil) if soft_delete_batch_fast_path?(:restore)
 
           ConcernsOnRails::Support::BatchOps.run(
@@ -110,6 +130,27 @@ module ConcernsOnRails
 
         private
 
+        # The current relation with the DEFAULT SCOPE's soft-delete predicate
+        # peeled off — and nothing else. `unscope(where: field)` (what the
+        # scopes do) strips every predicate on the column, the caller's
+        # included; so unscope, then put back the predicates the caller added on
+        # that column. "Added by the caller" is the relation's where clause
+        # minus the default scope's own, using the same structural WhereClause
+        # arithmetic Rails' `merge`/`except` rely on. Predicates on OTHER
+        # columns — a host model's own `default_scope { where(tenant_id:) }`
+        # included — are never touched. With `default_scope: false` there is
+        # nothing to peel.
+        def soft_delete_without_default_scope
+          relation = all
+          return relation unless soft_delete_default_scope
+
+          callers = relation.where_clause - default_scoped.where_clause
+          callers_on_column = callers - callers.except(soft_delete_field.to_s)
+          peeled = relation.unscope(where: soft_delete_field)
+          peeled.where_clause += callers_on_column unless callers_on_column.empty?
+          peeled
+        end
+
         # Built here rather than inline in `included do` so the names can be
         # affixed. Every scope that references another scope resolves it
         # through soft_delete_scope_names — a hard-coded symbol would break
@@ -152,7 +193,7 @@ module ConcernsOnRails
         # reason: under `touch: false` both paths skip validations already, so
         # only the ownership half (`unoverridden?`) applies.
         def soft_delete_batch_fast_path?(kind)
-          return false if soft_delete_touch
+          return false if soft_delete_touch || soft_delete_cascade.any?
 
           methods = if kind == :restore
                       %i[before_restore after_restore restore!]
@@ -161,6 +202,47 @@ module ConcernsOnRails
                     end
           ConcernsOnRails::Support::BatchOps.unoverridden?(self, ConcernsOnRails::Models::SoftDeletable, *methods)
         end
+
+        # Each cascade target must be a has_many / has_one (not through) whose
+        # model includes SoftDeletable. The association shape is checked at
+        # class load; the target model is checked here when it already
+        # resolves, and otherwise on first cascade (a not-yet-loaded or
+        # anonymous class cannot be resolved from inside a class body).
+        def soft_delete_validate_cascade!(cascade)
+          names = Array(cascade).map(&:to_sym)
+          names.each do |name|
+            reflection = reflect_on_association(name)
+            raise ArgumentError, "#{soft_delete_label}: cascade: '#{name}' is not an association of #{self.name}" unless reflection
+            unless %i[has_many has_one].include?(reflection.macro)
+              raise ArgumentError,
+                    "#{soft_delete_label}: cascade: '#{name}' must be a has_many or has_one (got #{reflection.macro})"
+            end
+            if reflection.is_a?(ActiveRecord::Reflection::ThroughReflection)
+              raise ArgumentError, "#{soft_delete_label}: cascade: '#{name}' is a :through association; cascade to the source instead"
+            end
+
+            soft_delete_check_cascade_target!(name, reflection) if soft_delete_cascade_resolvable?(reflection)
+          end
+          names.freeze
+        end
+
+        def soft_delete_cascade_resolvable?(reflection)
+          reflection.klass
+          true
+        rescue NameError # NoMethodError (anonymous class: nil name) is a NameError
+          false
+        end
+
+        def soft_delete_check_cascade_target!(name, reflection)
+          return if reflection.klass.respond_to?(:soft_delete_field)
+
+          raise ArgumentError,
+                "#{soft_delete_label}: cascade: '#{name}' targets #{reflection.klass.name}, which does not include SoftDeletable"
+        end
+
+        def soft_delete_label
+          "ConcernsOnRails::Models::SoftDeletable"
+        end
       end
 
       # Soft delete hooks
@@ -169,7 +251,9 @@ module ConcernsOnRails
       def before_restore; end
       def after_restore; end
 
-      def soft_delete!
+      # `at:` sets the timestamp (default now) — it is what the cascade uses to
+      # hand the parent's exact timestamp down, and lets callers backdate.
+      def soft_delete!(at: Time.zone.now)
         return true if deleted?
 
         result = false
@@ -178,10 +262,11 @@ module ConcernsOnRails
         transaction do
           before_soft_delete
           result = if self.class.soft_delete_touch
-                     update(self.class.soft_delete_field => Time.zone.now)
+                     update(self.class.soft_delete_field => at)
                    else
-                     update_column(self.class.soft_delete_field, Time.zone.now)
+                     update_column(self.class.soft_delete_field, at)
                    end
+          soft_delete_cascade_dependents!(at) if result
           after_soft_delete if result
         end
         result
@@ -190,6 +275,7 @@ module ConcernsOnRails
       def restore!
         return true unless deleted?
 
+        stamp = self[self.class.soft_delete_field]
         result = false
         transaction do
           before_restore
@@ -198,6 +284,7 @@ module ConcernsOnRails
                    else
                      update_column(self.class.soft_delete_field, nil)
                    end
+          restore_cascaded_dependents!(stamp) if result
           after_restore if result
         end
         result
@@ -221,6 +308,54 @@ module ConcernsOnRails
       def is_really_deleted?
         !self.class.unscoped.exists?(id)
       end
+
+      private
+
+      # Soft-delete every not-yet-deleted dependent with the parent's timestamp.
+      # Goes through each record's own soft_delete! so its hooks and its own
+      # cascade run; a dependent deleted earlier keeps its own timestamp.
+      def soft_delete_cascade_dependents!(at)
+        soft_delete_each_dependent(deleted: false) do |dependent|
+          soft_delete_cascade_check!(dependent, dependent.soft_delete!(at: at), "soft-delete")
+        end
+      end
+
+      # Restore only the dependents that carry the parent's timestamp — the
+      # ones this cascade deleted — and let them restore their own dependents.
+      def restore_cascaded_dependents!(stamp)
+        soft_delete_each_dependent(deleted: stamp) do |dependent|
+          soft_delete_cascade_check!(dependent, dependent.restore!, "restore")
+        end
+      end
+
+      # A dependent that fails to save must not be skipped silently: with the
+      # default `touch: true` the write goes through `update`, which returns
+      # false on a validation failure instead of raising. Mirror the batch
+      # contract (Support::BatchOps) and raise RecordNotSaved, which rolls the
+      # whole cascade — and the parent's own change — back.
+      def soft_delete_cascade_check!(dependent, result, verb)
+        return if result
+
+        raise ActiveRecord::RecordNotSaved.new(
+          "#{self.class.send(:soft_delete_label)}: failed to cascade #{verb} to " \
+          "#{dependent.class.name}(id: #{dependent.id.inspect})", dependent
+        )
+      end
+
+      # Yields the records of every cascade association matching `deleted:`
+      # (false → not deleted, a timestamp → deleted at exactly that time).
+      # The association's default scope is peeled off so deleted rows are
+      # reachable; has_one is handled through the same relation.
+      def soft_delete_each_dependent(deleted:, &block)
+        self.class.soft_delete_cascade.each do |name|
+          reflection = self.class.reflect_on_association(name)
+          self.class.send(:soft_delete_check_cascade_target!, name, reflection)
+          field = reflection.klass.soft_delete_field
+          relation = association(name).scope.unscope(where: field)
+          relation = deleted ? relation.where(field => deleted) : relation.where(field => nil)
+          relation.find_each(&block)
+        end
+      end
     end
   end
 end

data/lib/concerns_on_rails/models/stateable.rb

@@ -113,7 +113,15 @@ module ConcernsOnRails
           method_base = stateable_method_name(name)
 
           eligible = from.empty? ? all : all.where(field => from)
-          eligible = eligible.where.not(field => to)
+          # NULL-safe: `where.not(field => to)` compiles to `NOT (state = 'x')`,
+          # which SQL three-valued logic evaluates to NULL — never TRUE — for a
+          # NULL state, so those rows were silently dropped from the batch and
+          # from the returned count. They ARE eligible: a transition with no
+          # `from:` is documented as allowed from any state, `may_<event>?`
+          # returns true for them, and `record.<event>!` on the same row
+          # succeeds. A NULL state is reachable through an imported row,
+          # insert_all, or the documented `create!(status: nil)`.
+          eligible = eligible.where(arel_table[field].not_eq(to).or(arel_table[field].eq(nil)))
 
           ConcernsOnRails::Support::BatchOps.run(
             eligible,
@@ -225,10 +233,23 @@ module ConcernsOnRails
         raise InvalidTransition, "#{self.class.name}: cannot #{event} from '#{self[field]}'" unless from.empty? || from.include?(current)
 
         result = false
-        transaction do
+        # requires_new: a bare `transaction` JOINS an enclosing one instead of
+        # opening a savepoint, so under a caller's transaction Rails swallowed
+        # an ActiveRecord::Rollback from after_transition and rolled nothing
+        # back — the state change committed and this returned true, exactly
+        # opposite to the documented contract above.
+        # Set AFTER after_transition, never from update! — the same reason
+        # Lockable's lockable_write_with_hooks flips `completed` only once the
+        # block has run to the end. Rails swallows ActiveRecord::Rollback at
+        # the savepoint boundary, so taking the return value from update!
+        # reported a fake success for a transition the hook had just aborted:
+        # `raise unless ticket.archive!` never fired, and transition_all
+        # counted a row it had rolled back.
+        transaction(requires_new: true) do
           before_transition(event, current, to)
-          result = update!(field => to)
+          update!(field => to)
           after_transition(event, current, to)
+          result = true
         end
         result
       end

data/lib/concerns_on_rails/models/taggable.rb

@@ -75,8 +75,17 @@ module ConcernsOnRails
         # All distinct tags currently stored across the table, sorted.
         # distinct + NULL filter dedupe DB-side, so identical tag strings ship
         # over the wire once instead of once per row.
+        #
+        # reorder(nil) drops any inherited ORDER BY: PostgreSQL rejects
+        # SELECT DISTINCT ordered by a column outside the select list ("for
+        # SELECT DISTINCT, ORDER BY expressions must appear in select list"),
+        # and Models::Sortable installs exactly such a default_scope — so
+        # Taggable + Sortable raised on Postgres while passing on SQLite,
+        # which permits it. The ordering is meaningless here anyway: the
+        # result is sorted in Ruby below.
         def all_tags
           where.not(taggable_field => nil)
+               .reorder(nil)
                .distinct
                .pluck(taggable_field)
                .flat_map { |raw| taggable_split(raw) }

data/lib/concerns_on_rails/support/column_guard.rb

@@ -39,29 +39,52 @@ module ConcernsOnRails
       end
 
       # Same contract, validated against another class (e.g. CounterCacheable
-      # checks the counter column on the *parent* model).
+      # checks the counter column on the *parent* model). Every missing column
+      # is reported in ONE error — a fresh model with five absent columns is one
+      # migration away, not five boot failures.
       def ensure_columns_on!(concern, klass, *fields, types: nil)
         return false unless schema_reachable?(klass)
 
-        fields.flatten.compact.each do |field|
-          next if klass.column_names.include?(field.to_s)
+        missing = fields.flatten.compact.map(&:to_sym).uniq.reject { |field| klass.column_names.include?(field.to_s) }
+        return true if missing.empty?
 
-          raise ArgumentError,
-                "#{concern}: '#{field}' does not exist in the database (table: #{klass.table_name})." \
-                "#{column_migration_hint(klass, field, types)}"
-        end
-        true
+        raise ArgumentError, missing_columns_message(concern, klass, missing, types)
+      end
+
+      # "Concern: 'a' does not exist in the database (table: t). Add it with: …"
+      # for one column; "'a', 'b' and 'c' do not exist … Add them with: …" for
+      # several. The singular wording is unchanged from earlier releases.
+      def missing_columns_message(concern, klass, missing, types)
+        quoted = missing.map { |field| "'#{field}'" }
+        subject = if quoted.size == 1
+                    "#{quoted.first} does not exist"
+                  else
+                    "#{quoted[0..-2].join(', ')} and #{quoted.last} do not exist"
+                  end
+        "#{concern}: #{subject} in the database (table: #{klass.table_name})." \
+          "#{column_migration_hint(klass, missing, types, concern: concern)}"
       end
 
       # " Add it with: bin/rails generate migration AddDeletedAtToArticles
       # deleted_at:datetime" — every missing-column failure becomes a
-      # copy-paste fix. Without a known type the column name goes out bare
-      # (the generator defaults to string).
-      def column_migration_hint(klass, field, types)
-        type = types.is_a?(Hash) ? types[field.to_sym] : types
-        column = [field, type].compact.join(":")
-        " Add it with: bin/rails generate migration " \
-          "Add#{field.to_s.camelize}To#{klass.table_name.to_s.camelize} #{column}"
+      # copy-paste fix. Several columns get ONE command, named after the
+      # concern (AddAddressableColumnsToUsers street:string city:string) since
+      # AddStreetAndCityAndZipAndCountryTo… stops being readable. Without a
+      # known type the column name goes out bare (the generator defaults to
+      # string). Accepts a single field or a list.
+      def column_migration_hint(klass, fields, types, concern: nil)
+        fields = Array(fields)
+        columns = fields.map do |field|
+          type = types.is_a?(Hash) ? types[field.to_sym] : types
+          [field, type].compact.join(":")
+        end
+        table = klass.table_name.to_s.camelize
+        if fields.size == 1
+          " Add it with: bin/rails generate migration Add#{fields.first.to_s.camelize}To#{table} #{columns.first}"
+        else
+          " Add them with: bin/rails generate migration " \
+            "Add#{concern.to_s.demodulize}ColumnsTo#{table} #{columns.join(' ')}"
+        end
       end
 
       # True when the class's table can actually be inspected. Connection

data/lib/concerns_on_rails/support/encryptor.rb

@@ -85,6 +85,29 @@ module ConcernsOnRails
               "could not decrypt value (wrong key or tampered ciphertext)"
       end
 
+      # True when `value` really is an envelope produced by #encrypt: strict
+      # Base64 decoding to at least header + IV + tag, carrying a version byte
+      # we recognize. Deliberately does NOT check the algorithm byte, so a
+      # future alg (0x11, deterministic) still reads as an envelope.
+      #
+      # Backs Encryptable#<field>_encrypted?, which used a bare `.present?` —
+      # true for plaintext too. Cheap: no key material, no crypto, no KDF.
+      def envelope?(value)
+        return false unless value.is_a?(String)
+
+        # "" for non-Base64 input, which then fails the length check below.
+        raw =
+          begin
+            value.unpack1("m0").to_s
+          rescue ArgumentError
+            ""
+          end
+        return false if raw.bytesize < MIN_ENVELOPE_BYTES
+
+        version, = raw.byteslice(0, HEADER_LEN).unpack(HEADER_FORMAT)
+        version == VERSION_BYTE
+      end
+
       # Deterministic keyed fingerprint (lowercase hex) for equality lookups — a
       # "blind index". The HMAC key is domain-separated from the AES key via
       # BLIND_INDEX_INFO, so the two are cryptographically independent. The same

data/lib/concerns_on_rails/support/error_envelope.rb

@@ -10,13 +10,22 @@ module ConcernsOnRails
       module_function
 
       def render(controller, message:, status:, code: nil, details: nil)
-        if controller.respond_to?(:render_error)
+        # respond_to?(..., true) because render_error is very often declared
+        # under `private` — the idiomatic way to keep a controller helper from
+        # becoming a routable action — or exposed as a helper_method. The
+        # public-only check silently missed those and fell through to the
+        # inline body below, so an app rendering RFC 9457 problem+json got the
+        # gem's non-conforming shape for every Authorizable 403,
+        # WebhookVerifiable 401, Throttleable 429 and CursorPaginatable 400,
+        # with no error or warning. Authorizable already uses this spelling for
+        # current_user (`respond_to?(via, true)`) for exactly the same reason.
+        if controller.respond_to?(:render_error, true)
           # errors: only when there are details — several concerns document the
           # override contract as `render_error(message:, status:, code:)`, and
           # an unconditional errors: kwarg would break those implementations.
           kwargs = { message: message, code: code, status: status }
           kwargs[:errors] = details if details
-          controller.render_error(**kwargs)
+          controller.send(:render_error, **kwargs)
         else
           error = { message: message }
           error[:code] = code if code

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.28.2".freeze
+  VERSION = "1.28.4".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.28.2
+  version: 1.28.4
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-11 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack