concerns_on_rails 1.28.1 → 1.28.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00337457f7ea35fd2e02bb74bcb4031208109536946b448706104a9e031bd9ea
-  data.tar.gz: 3bfc8749303d212e51d98d8dd7fa4323888e3d984444c768695d5c290df311a3
+  metadata.gz: d3f06aad189272886038354ad98dfd58a84642d64e1313c4aac5d88e7d1ec90a
+  data.tar.gz: b38acca4cb5cd6a48496d0d4909da90782c14b6b71748af88b72df482a02ef62
 SHA512:
-  metadata.gz: 50ea50c59f6b15978fe3f1cc86f03266998249bd4b17dc84b36ff6a717e9a57d0efba37f2e5648c58009761aeb2198f14368b2c20715c0bc40c246c1e7b5ee25
-  data.tar.gz: f6b8c7784e26ac3f5c8f14217e07cbe6d846ecab216fad6c61fb192bf06a18aa4484d80efb32fd82d625c683d917d9fb8c9b88724adcf2a11878fb0ea6a1f7e9
+  metadata.gz: 98d77a84da148195bdd1c013054b12bd3b8c4f6ce2bf5b7ae8ee7e91c0a24b4d5d45e6540c139456e1d51b91afbfaed5cf68d9faf9859399cb4ec2b76ccdd90b
+  data.tar.gz: 6852cb66a64150139c9625d765cd3f724881a6b35a9e5920140713c21b69f148c956353d587765f3ad1eca6018b38de70b98aa8aa9c40006ad0a6919242607c8

data/CHANGELOG.md

@@ -1,5 +1,115 @@
 <!-- CHANGELOG.md -->
 
+## 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,
+#81, #82), all additive and column-free: ErrorHandleable rescues 14 exceptions
+instead of 3 and instruments every handled error, CursorPaginatable cursors can
+be HMAC-signed, Sortable applies a drag-and-drop order in one UPDATE, Sluggable
+gains slug candidates / word-boundary truncation / forced regeneration, and
+Sequenceable can defer numbering until an invoice is finalized. No new
+migrations or runtime dependencies. 1360 examples, 0 failures.
+
+### Added
+- **Controllers::ErrorHandleable**: the exception map grows from 3 to 14 —
+  `ActiveModel::ValidationError`, `RecordNotSaved`, `RecordNotDestroyed` (422),
+  `StaleObjectError`, `RecordNotUnique`, `InvalidForeignKey` (409),
+  `UnpermittedParameters`, `BadRequest`, `ParseError` (400),
+  `InvalidAuthenticityToken` (422) and `UnknownFormat` (406). Statuses follow
+  Rails' `rescue_responses`; database/parser-level errors render generic
+  messages so SQL, schema names and request input never leak. New
+  `handle_errors only:/except:` macro trims the map without touching a host
+  `rescue_from`; `error_handleable_keys` lists the active keys. (#42)
+- **Controllers::ErrorHandleable**: every handled error instruments
+  `handled_error.concerns_on_rails` (controller, action, code, status, message,
+  exception) via the public `on_handled_error(key, error, status:, message:)`
+  override point — report some codes to the error tracker, let the rest stay
+  quiet. (#84)
+- **Controllers::CursorPaginatable**: `cursor_paginate_by … signed: true` (or a
+  String key / callable) appends a URL-safe HMAC-SHA256 to every cursor and
+  rejects tampered, mis-signed or unsigned tokens with the usual 400, so
+  clients can no longer hand-craft page positions. Unsigned stays the default.
+  (#59, merged via #90)
+- **Sortable (model)**: `Model.reposition!(ids, missing: :append | :raise)`
+  applies a drag-and-drop id order as positions in one `UPDATE … CASE` inside
+  the current relation (unlisted rows appended or raised, foreign/duplicate ids
+  rejected, String ids cast, `:desc` lists inverted). Returns the count. (#80)
+- **Sluggable**: `candidates:` (friendly_id slug candidates tried in order
+  before the uuid fallback; regeneration still keyed to the primary field),
+  `max_length:` (word-boundary truncation, suffix appended after) and
+  `regenerate_slug!` (rebuild from the current source even over a
+  hand-assigned slug). (#81)
+- **Sequenceable**: `assign: :manual` defers numbering until `assign_<field>!`
+  (idempotent — `true` when assigned, `false` when already numbered; `save!`s
+  persisted records, leaves new ones for the caller's save), plus
+  `<field>_assigned?` and a `pending_<field>` scope. Numbering then follows
+  finalization order; `reset:` periods still come from `created_at`. (#82)
+
+### Notes
+Apps that include ErrorHandleable now get 11 more exceptions rescued into JSON
+4xx responses. One that relied on, say, `StaleObjectError` propagating to its
+error tracker should add `handle_errors except: :stale_object` (or `only:` the
+original trio) — or override `on_handled_error` to report the codes it cares
+about. Exceptions are registered by name, so a class a given Rails version
+lacks is simply never matched. Turning on `signed:` invalidates in-flight
+unsigned cursors (there is no mixed mode by design), so clients restart from
+the first page. `reposition!` writes positions with `update_all` and therefore
+bypasses acts_as_list's per-row callbacks by design.
+
 ## 1.28.1 (2026-09-07)
 
 One additive Paginatable option (#89): `pagination_meta` can now publish the

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,314 RSpec examples** run against a real database on every CI build
+- **Tested like an app, not a snippet** — **1,396 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
 
 ---
@@ -275,6 +275,10 @@ sluggable_by :title, reserved_words: %w[new edit admin]
 
 # Let Model.find accept a slug directly (not just the id)
 sluggable_by :title, finders: true
+sluggable_by :title, candidates: [:title, %i[title city]]   # try "title", then "title-city", then friendly_id's uuid suffix on the first candidate
+sluggable_by :title, max_length: 60                        # truncate at a word boundary (uniqueness suffix added after)
+
+page.regenerate_slug!   # rebuild from the current source — even over a hand-assigned slug
 Post.find("hello-world")   # resolves by slug
 ```
 
@@ -282,6 +286,9 @@ Post.find("hello-world")   # resolves by slug
 - Schema must have a `slug` column (string).
 - `history: true` requires a `friendly_id_slugs` table — generate with `rails generate friendly_id` or add a manual migration.
 - `scope: :col` requires `col` to exist in the same table.
+- `candidates:` takes friendly_id's shapes — a Symbol/String method, a Proc, or an Array of those joined with `-` — tried in order until one is free (all taken → the first candidate plus a uuid); the slug still regenerates only when the **primary** field changes (a candidate-only change doesn't churn the URL), and a NULL slug backfills through the candidates.
+- `max_length:` truncates each candidate at the last `-` inside the limit (a single long word is hard-cut); friendly_id's conflict suffix is appended afterwards, so a colliding slug may exceed the limit — unlike friendly_id's own `slug_limit`, which squeezes the uuid inside it.
+- `regenerate_slug!` is the escape hatch for the explicit-slug rule: it forces regeneration and saves (`save!`), keeping uniqueness handling.
 - Falls back to `to_s` if the configured source field doesn't respond.
 - Uses friendly_id's `:slugged` (+ optionally `:history`, `:scoped`) strategies under the hood.
 
@@ -301,6 +308,10 @@ end
 Task.create!(name: "A")
 Task.create!(name: "B")
 Task.last.move_higher
+
+# Save a drag-and-drop order in ONE UPDATE (CASE id WHEN …): the ids' order becomes their positions
+Task.reposition!(params[:ids])                    # => 12 — rows not listed are pushed after, in their current order
+Task.where(list_id: 1).reposition!(ids, missing: :raise)   # scoped; a partial list is an error
 ```
 
 **Configuration**
@@ -314,8 +325,8 @@ sortable_by :position, add_new_at: :top          # new rows insert at the top (a
 ```
 
 **Notes**
-- The configured field must exist as a column.
-- Direction values other than `:asc` / `:desc` silently fall back to `:asc`.
+- The configured field must exist as a column; a direction other than `:asc` / `:desc` raises at declaration.
+- `reposition!` runs inside the current relation (`Task.where(list_id: 1)` — the same set acts_as_list's `scope:` would use), rejects ids outside it and duplicates before writing anything, coerces String ids from params, and on a descending list gives the first id the highest value. It bypasses acts_as_list callbacks by design (one `update_all`, no per-row shifting).
 
 ---
 
@@ -456,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**
 
@@ -479,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
@@ -854,6 +897,7 @@ Invoice.next_sequence(account_id: 1)   # => 4  (peek the next value, without cre
 | `scope:`             | `nil`       | Column (or array of columns) the counter is scoped to — e.g. one sequence per `account_id`. |
 | `reset:`             | `:never`    | `:never` / `:year` / `:month` / `:day` — restart numbering each period (needs `created_at`). |
 | `template:`          | `nil`       | `->(seq, record) { ... }` full custom formatter; overrides `prefix` / `padding` / period. |
+| `assign:`            | `:create`   | `:create` numbers every record in `before_create`; `:manual` leaves the column NULL until `assign_<field>!` is called — for invoices that get their number when finalized, not when drafted. |
 
 **Default format**
 
@@ -870,10 +914,14 @@ Invoice.next_sequence(account_id: 1)   # => 4  (peek the next value, without cre
 |-----------------------------------|---------------------------------------------------------------------------------------|
 | `formatted_<field>`               | The formatted string — the persisted `into:` value when set, otherwise computed.      |
 | `Model.next_<field>(scope_attrs)` | Peek the next integer for a scope without creating a record.                           |
+| `assign_<field>!`                 | Number the record now (`assign: :manual`, or any row still blank): next value + `into:` string, `save!`d when persisted, left for your save when new. `true` when assigned, `false` when already numbered. |
+| `<field>_assigned?`               | Whether the record has its number.                                                    |
+| `Model.pending_<field>`           | Scope: rows still awaiting a number (`WHERE <field> IS NULL`).                          |
 
 **Notes**
 - The next value is `MAX(<field>) + 1` within the scope (and period), so numbering is dense and ordered — not random.
 - Caller-supplied values are respected: `Invoice.create!(sequence: 100)` is not overwritten (and its `into:` string is still formatted from `100`).
+- With `assign: :manual`, numbering follows **assignment** order (the first invoice finalized is #1, whenever it was drafted); with `reset:` the period is still taken from the row's `created_at`, exactly as on create.
 - Generation reads `MAX` then inserts, so two concurrent inserts can race. It's **best-effort** — add a **scoped unique index** on `<field>` (and on `into:`) for a real guarantee, the same way you would for any `MAX`-based numbering.
 - `reset:` requires a `created_at` column; the period is taken from each row's creation time.
 - For fixed-width display (`00042`), make the `into:` column a **string** — integer columns drop leading zeros.
@@ -1565,7 +1613,7 @@ end
 
 **Notes**
 - The primary key is always appended as a tiebreaker, so duplicate values never skip or repeat rows; ordering columns are chosen **in code** (never from params) and should be `NOT NULL` (a NULL boundary value raises rather than silently dropping rows).
-- Cursors are opaque, table/order-pinned tokens — a malformed, cross-endpoint, or stale-config cursor renders a 400 (`invalid_cursor`; override `render_invalid_cursor` to customize, delegates to Respondable's `render_error` when present). They are **not signed**: a client can mint different boundary values, but values are cast through the model's attribute types and bound by Arel (no injection) and the relation's own scoping still applies — treat a cursor as a page position, never an authorization boundary.
+- Cursors are opaque, table/order-pinned tokens — a malformed, cross-endpoint, or stale-config cursor renders a 400 (`invalid_cursor`; override `render_invalid_cursor` to customize, delegates to Respondable's `render_error` when present). Unsigned by default: a client can mint different boundary values, but values are cast through the model's attribute types and bound by Arel (no injection) and the relation's own scoping still applies — treat a cursor as a page position, never an authorization boundary. **`signed: true`** (or a String key, or a callable for rotating keys) appends a URL-safe HMAC-SHA256 to every cursor and rejects tampered or unsigned tokens with the same 400, so clients can no longer hand-craft positions at all; `true` uses `Rails.application.secret_key_base`. Turning it on invalidates in-flight cursors (clients restart from page one).
 - `cursor_paginated` uses `reorder` (replaces any `default_scope` ORDER BY) and returns a loaded Array. Don't wrap it with the controller Sortable's `sorted` — pass `order:` per call instead.
 - Forward-only by default — `bidirectional: true` (macro or per call) adds prev cursors and `X-Has-Prev`/`X-Prev-Cursor`; direction is pinned in the token, so prev tokens replayed on forward-only endpoints 400 and old direction-less tokens stay valid. `order_presets: { newest: {...}, top: {...} }` (+ `default_preset:`, `order_param:`) lets clients pick a **named** ordering from an allow-list. `predicate: :auto` upgrades the keyset WHERE to a row-value tuple `(a, b, id) > (x, y, z)` on PostgreSQL/MySQL/SQLite when directions are uniform — composite-index friendly — falling back to the portable OR-expansion (`:row`/`:or` force a strategy).
 - Use Paginatable when you need page numbers and totals.
@@ -1681,22 +1729,42 @@ end
 
 ## 🛟 ErrorHandleable
 
-Install `rescue_from` handlers for the three most common controller exceptions and render them as the same JSON envelope used by Respondable.
+Install `rescue_from` handlers for the controller exceptions a JSON API meets in practice and render them as the same JSON envelope used by Respondable.
 
 ```ruby
 class Api::BaseController < ApplicationController
   include ConcernsOnRails::Controllers::Respondable       # recommended
   include ConcernsOnRails::Controllers::ErrorHandleable
+
+  handle_errors except: :stale_object                     # optional — let some propagate
 end
 ```
 
 **Handled exceptions**
 
-| Exception                              | Status | `code`                |
-|----------------------------------------|--------|-----------------------|
-| `ActiveRecord::RecordNotFound`         | 404    | `"not_found"`         |
-| `ActionController::ParameterMissing`   | 400    | `"parameter_missing"` |
-| `ActiveRecord::RecordInvalid`          | 422    | `"record_invalid"`    |
+| Key (= `code`)               | Exception                                      | Status | `details`                    |
+|------------------------------|------------------------------------------------|--------|------------------------------|
+| `not_found`                  | `ActiveRecord::RecordNotFound`                 | 404    | —                            |
+| `parameter_missing`          | `ActionController::ParameterMissing`           | 400    | —                            |
+| `record_invalid`             | `ActiveRecord::RecordInvalid`                  | 422    | `errors.full_messages`       |
+| `validation_error`           | `ActiveModel::ValidationError`                 | 422    | `model.errors.full_messages` |
+| `record_not_saved`           | `ActiveRecord::RecordNotSaved`                 | 422    | record errors, if any        |
+| `record_not_destroyed`       | `ActiveRecord::RecordNotDestroyed`             | 422    | record errors, if any        |
+| `stale_object`               | `ActiveRecord::StaleObjectError`               | 409    | —                            |
+| `record_not_unique`          | `ActiveRecord::RecordNotUnique`                | 409    | —                            |
+| `foreign_key_violation`      | `ActiveRecord::InvalidForeignKey`              | 409    | —                            |
+| `unpermitted_parameters`     | `ActionController::UnpermittedParameters`      | 400    | the parameter names          |
+| `invalid_authenticity_token` | `ActionController::InvalidAuthenticityToken`   | 422    | —                            |
+| `bad_request`                | `ActionController::BadRequest`                 | 400    | —                            |
+| `parse_error`                | `ActionDispatch::Http::Parameters::ParseError` | 400    | —                            |
+| `unknown_format`             | `ActionController::UnknownFormat`              | 406    | —                            |
+
+Statuses follow Rails' own `rescue_responses` wherever Rails has an opinion; the two database-constraint
+races Rails leaves as 500s (`RecordNotUnique`, `InvalidForeignKey`) get the REST-conventional 409. Messages
+for database- and parser-level errors are deliberately generic (`"Resource already exists"`,
+`"Malformed request body"`, …): the raw messages carry SQL fragments, table/column names, model class
+names or the offending input, none of which belongs in an API response. `details` is present only when
+there is something to list.
 
 Response shape (matches `Respondable#render_error`):
 
@@ -1718,8 +1786,32 @@ class Api::BaseController < ApplicationController
 end
 ```
 
+**Trimming the map**
+
+```ruby
+handle_errors except: :stale_object                               # let optimistic-lock conflicts reach the error tracker
+handle_errors except: %i[record_not_unique foreign_key_violation]  # calls accumulate
+handle_errors only: %i[not_found parameter_missing record_invalid] # just the original trio
+```
+
+`handle_errors` removes only the concern's own registrations (matched on exception *and* handler), so a
+`rescue_from` you declared yourself for the same exception is untouched, and it never re-adds — your later
+declarations keep precedence. Unknown keys raise `ArgumentError` listing the valid ones;
+`error_handleable_keys` returns the keys still active on a controller.
+
+**Reporting** — every handled error instruments `handled_error.concerns_on_rails` (`controller`, `action`, `code`, `status`, `message`, `exception`, `exception_class`) via the public `on_handled_error(key, error, status:, message:)` override point, so the 409s reach your error tracker while the 404s stay quiet:
+
+```ruby
+def on_handled_error(key, error, **)
+  Sentry.capture_exception(error) if %i[record_not_unique foreign_key_violation stale_object].include?(key)
+  super   # keep the event
+end
+```
+
 **Notes**
 - When `Respondable` is also included, the handlers delegate to `render_error` so the envelope shape stays in one place. Otherwise they render the same envelope inline.
+- Exceptions are registered by name (string), so a class your Rails version lacks is simply never matched.
+- `ActionController::UnpermittedParameters` is only raised with `config.action_controller.action_on_unpermitted_parameters = :raise`.
 - `RecordInvalid.details` are populated from `error.record.errors.full_messages`.
 
 ---
@@ -2123,7 +2215,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) |
@@ -2157,9 +2249,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,314 examples)
+bundle exec rspec                               # run the test suite (1,396 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.28.1.gem      # install locally
+gem install ./concerns_on_rails-1.28.3.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/cursor_paginatable.rb

@@ -3,6 +3,8 @@ require "concerns_on_rails/support/error_envelope"
 require "concerns_on_rails/support/scalar_param"
 require "json"
 require "concerns_on_rails/support/link_header"
+require "openssl"
+require "active_support/security_utils"
 require "time" # Time#iso8601(fraction_digits) lives in the stdlib time library
 
 module ConcernsOnRails
@@ -143,6 +145,9 @@ module ConcernsOnRails
         class_attribute :cursor_paginatable_bidirectional, default: false
         class_attribute :cursor_paginatable_predicate, default: :auto
         class_attribute :cursor_paginatable_link_header, default: true
+        # false (unsigned), true (Rails.application.secret_key_base), a String
+        # key, or a callable returning the key — see cursor_paginate_by.
+        class_attribute :cursor_paginatable_signed, default: false
 
         # Real controllers (anything with ActiveSupport::Rescuable) get the 400
         # handlers automatically; bare objects let the errors propagate.
@@ -163,7 +168,7 @@ module ConcernsOnRails
         # max_per_page: 0 (or negative) disables the per_page cap.
         def cursor_paginate_by(order: nil, order_presets: nil, default_preset: nil, order_param: :order,
                                per_page: DEFAULT_PER_PAGE, max_per_page: DEFAULT_MAX_PER_PAGE,
-                               bidirectional: false, predicate: :auto, link_header: true)
+                               bidirectional: false, predicate: :auto, link_header: true, signed: false)
           self.cursor_paginatable_order = order && CursorPaginatable.normalize_order!(order)
           self.cursor_paginatable_order_presets = order_presets && CursorPaginatable.normalize_presets!(order_presets)
           self.cursor_paginatable_default_preset =
@@ -174,9 +179,19 @@ module ConcernsOnRails
           self.cursor_paginatable_bidirectional = bidirectional ? true : false
           self.cursor_paginatable_predicate = CursorPaginatable.validate_predicate!(predicate)
           self.cursor_paginatable_link_header = link_header ? true : false
+          self.cursor_paginatable_signed = CursorPaginatable.validate_signed!(signed)
         end
       end
 
+      # `signed:` — false, true (the app's secret_key_base), a non-blank String,
+      # or a callable (resolved per request, so keys can rotate).
+      def self.validate_signed!(signed)
+        return signed if [true, false].include?(signed) || signed.respond_to?(:call)
+        return signed if signed.is_a?(String) && !signed.strip.empty?
+
+        raise ArgumentError, "#{name}: signed: must be true, false, a String or a callable"
+      end
+
       # Run the keyset query (limit + 1 to detect has_more), set the standard
       # response headers, and return the page as a loaded Array (laziness is
       # impossible here: has_more detection materializes limit + 1 rows).
@@ -339,7 +354,55 @@ module ConcernsOnRails
           "d" => direction,
           "v" => pairs.map { |col, _dir| serialize_cursor_value(cursor_boundary_value!(record, col)) }
         }
-        cursor_base64_encode(JSON.generate(payload))
+        token = cursor_base64_encode(JSON.generate(payload))
+        cursor_signing_key ? "#{token}.#{cursor_signature(token)}" : token
+      end
+
+      # Signed cursors are `<url-safe base64 payload>.<hex HMAC-SHA256>` — the
+      # dot never appears in the payload alphabet, so the split is unambiguous
+      # and the whole token stays URL-safe. Verification is constant-time and
+      # happens BEFORE the payload is parsed; an unsigned or mis-signed token
+      # on a signed endpoint is rejected (fail closed). Turning signing on
+      # therefore invalidates in-flight cursors: clients restart from page one.
+      def cursor_signature(payload_token)
+        OpenSSL::HMAC.hexdigest("SHA256", cursor_signing_key, payload_token)
+      end
+
+      # nil when unsigned; the key otherwise. `true` reads
+      # Rails.application.secret_key_base (raising a setup hint outside Rails).
+      def cursor_signing_key
+        configured = self.class.cursor_paginatable_signed
+        return nil if configured == false || configured.nil?
+        return cursor_rails_secret_key_base if configured == true
+
+        key = configured.respond_to?(:call) ? configured.call : configured
+        raise ArgumentError, "#{self.class.name}: signed: resolved to a blank key" if key.to_s.strip.empty?
+
+        key.to_s
+      end
+
+      def cursor_rails_secret_key_base
+        app = defined?(Rails) && Rails.respond_to?(:application) ? Rails.application : nil
+        key = app.respond_to?(:secret_key_base) ? app.secret_key_base : nil
+        return key.to_s unless key.to_s.strip.empty?
+
+        raise ArgumentError,
+              "ConcernsOnRails::Controllers::CursorPaginatable: signed: true needs Rails.application.secret_key_base; " \
+              "outside a Rails app pass signed: -> { ... } (a callable returning the key) or a String."
+      end
+
+      # Splits and verifies a signed token, returning the payload half; raises
+      # InvalidCursor when the endpoint is signed and the token is not (or its
+      # signature does not match).
+      def verify_cursor_signature!(raw)
+        return raw unless cursor_signing_key
+
+        payload, signature, extra = raw.split(".", 3)
+        valid = extra.nil? && !payload.to_s.empty? && signature.to_s.match?(/\A[0-9a-f]{64}\z/) &&
+                ActiveSupport::SecurityUtils.secure_compare(signature, cursor_signature(payload))
+        raise InvalidCursor, "Invalid pagination cursor." unless valid
+
+        payload
       end
 
       # A NULL boundary value would emit `col > NULL` — never TRUE in SQL
@@ -375,7 +438,7 @@ module ConcernsOnRails
       def decode_cursor(raw, pairs, model, bidirectional:)
         return nil if raw.nil? || raw.to_s.strip.empty?
 
-        payload = parse_cursor_payload(raw.to_s)
+        payload = parse_cursor_payload(verify_cursor_signature!(raw.to_s))
         raise InvalidCursor, "Invalid pagination cursor." unless payload
 
         verify_cursor_scope!(payload, pairs, model)