concerns_on_rails 1.28.7 → 1.28.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b713f3fd8cd14e5f3a12db7b3c390111118df1fa143d5d833dee009544a8a64
-  data.tar.gz: 16f6d5447ac1d44c5be3dc1cdb0113d9a9e64457de14b87d4199bb95993189d8
+  metadata.gz: f292a3f1cf7d1fae3b1e47be9daa416ae0b6c8b69ce0d4fd2efd583496f2d9aa
+  data.tar.gz: 661ffce3f3fa4fb305957b239fbb560752ea22f369da3268d03575efb35701da
 SHA512:
-  metadata.gz: 7afa091b97fe9359b7294f965593af629d5d66d797e77a7c3ebde396eddc7fcdf627937fae2c90c2ee0c034c23e91f3713ac3827ab201ee8edda0438094ad89c
-  data.tar.gz: 683d74ea9d1b258e1c79bcdcd7243bcbcd22b10ba5c862946267e5baab118c3753c69baf7af496436a7424286cbd33be9f5e6bfba889928f6f212b190d9ed3ca
+  metadata.gz: a49931859e637327e55313e7473236a4ceca6a5f61c01f7f701a7d7acba317c8fe6a83ec05ec2dafa5d7e61da45d8d2623a26f15a876d9e7d12036cd9c40c451
+  data.tar.gz: 625395f36729c2d789b303cfeec6537dfa173364b70c0a6c971707616a0fb3161d5eef083417aadcc9586a7b99c89d9a7617355e08284cdb76d210a62a3df82f

data/CHANGELOG.md

@@ -1,5 +1,185 @@
 <!-- CHANGELOG.md -->
 
+## 1.28.9 (2026-09-19)
+
+CI now runs the matrix the gemspec actually claims: Rails 7.0–8.0 across Ruby 3.2/3.3/3.4,
+plus **PostgreSQL and MySQL** alongside SQLite. The suite had only ever run on SQLite, which
+is the most permissive of the three, and the first green-on-SQLite run of the new matrix
+failed 29 examples on MySQL and 7 on PostgreSQL.
+
+Almost all of those were specs asserting SQLite's own SQL rather than the gem misbehaving —
+but one was a real bug, and it is the reason this is a release and not just a CI change.
+
+### Fixed
+- **Models::Taggable**: `tagged_with` was broken on MySQL and inconsistent on PostgreSQL.
+  - On **MySQL** every `tagged_with` query was a **syntax error**. The clause inlined
+    `ESCAPE '\'` into hand-written SQL, and MySQL treats backslash as an escape character
+    inside string literals, so the escape consumed its own closing quote. SQLite and
+    PostgreSQL (with `standard_conforming_strings`) read it as a literal backslash, which is
+    why this was invisible for so long. The clause is now built with Arel `matches`, so the
+    adapter quotes the escape character itself — one code path, no per-adapter branching.
+  - On **PostgreSQL** `tagged_with` was case-SENSITIVE, while on SQLite and MySQL it folded
+    case: the same query returned different rows depending on the database. It is now
+    case-insensitive on all three (`ILIKE` on PostgreSQL).
+
+  ⚠️ **PostgreSQL users: this widens `tagged_with`.** A lookup that was case-sensitive before
+  now also matches differently-cased tags. That is the documented intent of the concern and
+  it makes the three adapters agree, but it is a behaviour change on upgrade. If you relied
+  on case-sensitive matching, declare `taggable_by :tags, downcase: true` and fold on write.
+  SQLite and MySQL users see no change. Note the Ruby-side helpers (`tagged_with?`,
+  `all_tags`, `tag_counts`) still compare exactly — `downcase: true` is what makes the scope
+  and the helpers agree.
+
+### Internal
+- **CI**: `.github/workflows/ci.yml` gains a Rails-version axis (7.0, 7.1, 7.2, 8.0 × Ruby
+  3.2/3.3/3.4, via `gemfiles/*.gemfile`) and an adapter axis (PostgreSQL and MySQL service
+  containers). `DB=postgresql` / `DB=mysql2` selects the adapter locally; SQLite stays the
+  default so a plain checkout still needs no services. (#102)
+- **Specs**: examples that asserted SQL now build the expected fragment from the
+  connection's own quoting, via new `TestDatabase.quoted_table` / `quoted_column` /
+  `qualified` helpers and `sqlite?` / `postgresql?` / `mysql?` predicates — so an assertion
+  means the same thing on every adapter instead of encoding SQLite's. Several examples got
+  *stronger* in the process: the Sortable NULL-ordering pair now asserts the PostgreSQL
+  native-`NULLS` branch and the portable-`CASE` branch separately, each also asserting the
+  other is absent.
+- Three examples depended on SQLite-only tolerance rather than on the gem: a grouped
+  relation selecting `*` (rejected by PostgreSQL, and by MySQL under `only_full_group_by`),
+  a non-finite Float written to a float column (SQLite's adapter overrides `quote` for
+  those; MySQL emits a bare `NaN`), and a NULL page-boundary fixture that assumed SQLite's
+  NULLs-first ordering (PostgreSQL sorts NULLs last ascending).
+
+### Known gap
+- `Models::Storable` guards its JSON extraction with `json_valid` on SQLite only. MySQL has
+  `JSON_VALID()` (5.7.8+) and could have the same guard; it was left alone deliberately
+  rather than shipped unverified, since a wrong guess there would break every
+  `where_<key>` query on that adapter. PostgreSQL has no equivalent before PG 16's
+  `IS JSON`. Now that the MySQL leg runs, this is a small follow-up.
+
+## 1.28.8 (2026-09-19)
+
+The last six open feature PRs, released as a patch by request. These had never been
+reviewed — they were excluded from the previous two waves because they would not merge —
+so each was rebased onto master, reviewed adversarially, and fixed. **Five of the six
+carried a CRITICAL defect**, two of which could destroy data. The `### Fixed` section is
+the important one; several entries describe behaviour that never worked as documented.
+
+Also fixes a live defect in `Support::ErrorEnvelope` found during the review, which
+affected eight concerns on 1.28.7 and earlier. 1828 examples, 0 failures.
+
+### Added
+- **Models::Encryptable**: key rotation. `ConcernsOnRails.configure_encryption { |c|
+  c.key_id = 1; c.previous_keys = { 0 => old } }` — new writes stamp `key_id`, reads
+  decrypt with whichever configured key the envelope names (unknown id → `DecryptionError`
+  naming it), and blind-index lookups match current + previous digests.
+  `Model.needs_reencryption(*fields)`, `Model.reencrypt_all!(*fields)` /
+  `record.reencrypt!`, and `<field>_key_id`. Per-field `key:` fields sit outside rotation.
+  The envelope format is unchanged: 1.28.x already wrote and authenticated a `key_id` byte,
+  so every existing row is a key-id-0 envelope and decrypts untouched after upgrading. (#77)
+- **Models::Lockable**: `lockable_by … unlock_token:` mints a URL-safe token in the same
+  write as the lock, for self-service unlock links without Devise.
+  `User.unlock_by_token(token)` consumes it once — constant-time compare, one conditional
+  UPDATE decides the winner, hooks fire — and the token lives exactly as long as the lock.
+  Cleared on every unlock path, reset by Duplicable, and registered with the
+  filter_parameters registry. (#61)
+- **Models::Stateable**: `stateable_by … timestamps: true` (or a list of states) stamps
+  `<state>_at` in the same write as the state change, for guarded events, direct setters,
+  `transition_to!` and `transition_all`. Per-event `before_<event>` / `after_<event>` hooks
+  fire inside the generic `before_transition` / `after_transition` pair and the same
+  transaction, and may be declared `private`. (#49)
+- **Controllers::Filterable**: `filter_by … operators: true` (or a subset) adds `not`,
+  `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `null`, `contains` and `starts_with` to
+  direct-where filters, read as a suffix (`?price_gte=10`) or in bracket form
+  (`?price[gte]=10`). Every operator comes from a frozen allow-list mapped to a fixed Arel
+  node, so no param string reaches SQL. Values are cast through the column's type or the
+  new `type:` option, which also pre-casts what a `with:` lambda receives. Opt-in per
+  filter; existing filters are unchanged. (#46)
+- **Controllers::WebhookVerifiable**: `verify_webhook … replay:` / `replay_ttl:` rejects a
+  redelivery with 409 `webhook_replayed` — replay protection for the schemes that carry no
+  timestamp (GitHub, Shopify, plain HMAC). The check runs only after the signature
+  verifies. A short claim is taken before the action and promoted on completion, and
+  released on a 5xx so a transient failure does not burn the delivery id. (#60)
+- **Controllers::Respondable**: `render_success` accepts `location:` and `headers:`, and
+  gains `render_created(data:, location:)` (201 + `Location`) and `render_invalid(record)`
+  (422 + the record's `full_messages`). Header names and values are stripped of bytes a
+  header line cannot carry, and a `Link` value is appended to an existing one — matched
+  case-insensitively — rather than replacing it. Works in both the envelope and the
+  problem-details format. (#105, replacing #74)
+
+### Changed
+- **Controllers::Filterable**: an uncastable comparison value (`?price_gte=abc`) returns
+  `none` rather than matching. Fail-closed was chosen because ignoring the filter would
+  return the very rows the client tried to exclude; it matches what plain `where` already
+  does with the same input, and is scoped to the four new comparison operators so no
+  pre-existing filter changes on upgrade. `contains` / `starts_with` are case-INsensitive
+  on every adapter — there is no `case_sensitive:` option. (#46)
+- **Models::Stateable**: `timestamps:` refuses to derive a stamp column from a state named
+  `created` or `updated`, which would otherwise target Rails' own `created_at`/`updated_at`.
+  Stamp columns are NOT affixed by `prefix:`/`suffix:`, so a state named `published` or
+  `deleted` collides with Publishable's and SoftDeletable's columns — rename the state or
+  leave it out of `timestamps:`. (#49)
+- **Models::Encryptable**: `record.reencrypt!` rewrites through a guarded `UPDATE` that
+  matches the ciphertext read at load, then reloads. A row written by someone else in the
+  meantime is left alone instead of being reverted, and a field with unsaved changes is
+  skipped rather than silently committed. (#77)
+
+### Fixed
+- **Support::ErrorEnvelope**: the `errors:` keyword was passed to a host app's
+  `render_error` whenever details were present, but several concerns document the override
+  contract as `render_error(message:, status:, code:)`. Such an app got `ArgumentError:
+  unknown keyword: :errors` at request time — a 500 instead of the 4xx, on exactly the path
+  that has something to report. The previous guard tested `details` alone, so it covered
+  only the empty case, i.e. the one that was never broken. This reached every concern that
+  funnels through the envelope, most commonly ErrorHandleable's rescued `RecordInvalid`.
+- **Models::Encryptable**: `previous_keys=` printed the offending hash's keys on a bad
+  shape, so an inverted `{ ENV["KEY_V1"] => 0 }` raised **with the live key in the exception
+  message** — into logs, backtraces and error trackers. Only the value's class is reported
+  now. (#77)
+- **Models::Encryptable**: `needs_reencryption` detected MySQL by adapter name, so Trilogy
+  (Rails 7.1+) and MariaDB fell through to a case-folding comparison and returned **zero
+  rows**. `reencrypt_all!` then reported 0, an operator would conclude the rotation was
+  complete and drop the old key, and every pre-rotation row would become permanently
+  undecryptable. (#77)
+- **Models::Lockable**: a `before_unlock` / `after_unlock` hook that vetoed the unlock
+  permanently burned the token while leaving the account locked — the claim ran in a bare
+  transaction that joined the enclosing one, so `unlock_access!`'s savepoint rolled back
+  while the claim committed. The user's emailed link was dead with no way back. The claim
+  now takes its own savepoint and is rolled back with the unlock. (#61)
+- **Models::Lockable**: `unlock_by_token` no longer honours a token once the lock has
+  lapsed, and no longer uses `unscoped` — a mailed link could otherwise reach a row hidden
+  behind a `default_scope` (a soft-deleted or deactivated account). (#61)
+- **Controllers::WebhookVerifiable**: a store answering `#write` but not `#read` passed
+  declaration-time validation and then provided **no replay protection at all**, silently —
+  the endpoint looked protected and accepted every redelivery. Both methods are now
+  required. (#60)
+- **Controllers::WebhookVerifiable**: the Stripe replay key hashed the raw
+  `Stripe-Signature` header, which is *parsed* rather than compared — appending an unknown
+  `v0=…` pair or re-spacing the commas produced a still-valid header with a fresh key,
+  defeating the protection. Stripe now keys off the signed `"<timestamp>.<body>"` payload.
+  (#60)
+- **Controllers::WebhookVerifiable**: `replay: false` raised at class load, so
+  `replay: Rails.env.production?` broke controller loading in development and test. It is
+  now a synonym for "off". (#60)
+- **Controllers::Respondable**: caller-supplied header **names** reached the response
+  unsanitized, so a CR/LF in an interpolated name was response splitting. Names now go
+  through the same filter as values, widened from CR/LF to the full illegal-byte range.
+  (#105)
+- **Controllers::Filterable**: a bracket-form operator with a blank value
+  (`?price[gte]=`) became `price > NULL` and returned **nothing**, while the documented
+  equivalent `?price_gte=` correctly returned everything — an empty min/max box silently
+  emptied the result set. Both forms now skip blanks, and both honour a boolean `false`.
+  (#46)
+- **Controllers::Filterable**: `?stock_gt=twelve` silently became `stock > 0` and returned
+  the stocked rows (`ActiveModel::Type::Integer#cast("twelve")` is `0`, not `nil`), while
+  the same typo on a datetime column returned none — one malformed request answered two
+  opposite ways. (#46)
+- **Controllers::Filterable**: LIKE escaping no longer relies on `sanitize_sql_like`, which
+  is not public before Rails 5.1 while the gemspec claims `>= 5.0`. (#46)
+
+### Internal
+- Docs corrected: "Never `update_column(s)` an encrypted field — those bypass the type and
+  write raw plaintext" was **false** (`update_columns` serializes through the attribute
+  type), and `reencrypt_all!` is built on it. (#77)
+
 ## 1.28.7 (2026-09-19)
 
 The eight PRs held back from 1.28.6, released as a patch by request. Each carried a

data/README.md

@@ -148,7 +148,7 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 - **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 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,730 RSpec examples** run against a real database on every CI build
+- **Tested like an app, not a snippet** — **1,830 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
 
 ---
@@ -1035,6 +1035,26 @@ guard rejects are skipped (not errors). Unlike every other batch verb in this ge
 the guarded `<event>!` method, because that path runs validations via `update!` while a bulk
 `update_all` would silently skip them.
 
+**Timestamps and per-event hooks**
+
+```ruby
+stateable_by :status, states: %i[draft review published archived], default: :draft,
+             timestamps: true,                  # or %i[published archived] — stamps <state>_at
+             transitions: { publish: { from: %i[draft review], to: :published }, archive: { to: :archived } }
+
+article.publish!          # status = "published" AND published_at = Time.current, in ONE update!
+article.archived!         # direct setters and transition_to! stamp too; the default state on create does not
+
+def before_publish  = check_embargo!          # per-event hooks, fired inside the generic pair and the
+def after_publish   = notify_subscribers      # same transaction: before_transition → before_publish →
+                                              # write → after_publish → after_transition
+```
+
+`timestamps:` requires the `<state>_at` columns (checked at class load, one typed migration hint); the column is
+**not** affixed, and one Rails owns (`created_at` / `updated_at`) is refused. Per-event hooks follow the affixed
+event name (`before_status_publish` with `prefix: true`), may be private, and — like the generic hooks — fire only
+for guarded `<event>!` transitions. `Model.stateable_timestamps` lists the stamped states.
+
 **Prefix / suffix** — avoid clashes when the state names overlap with other concerns or scopes:
 
 ```ruby
@@ -1180,6 +1200,7 @@ Article.published.tag_counts(limit: 20)        # => { "ruby" => 12, "rails" => 7
 
 **Notes**
 - Matching is **boundary-safe** — searching `rail` does not match `rails`. An explicit SQL `ESCAPE` clause makes tags containing `_` / `%` match literally on every adapter.
+- `tagged_with` matches **case-insensitively on every adapter** — `LIKE` on SQLite and MySQL, `ILIKE` on PostgreSQL — so one call means one thing everywhere (how non-ASCII characters fold is still the database collation's business). The Ruby-side helpers (`tagged_with?`, `all_tags`, `tag_counts`) compare exactly, so `downcase: true` — which folds on write — is what makes the scope and the helpers agree.
 - Tags are normalized in `before_validation`, so a direct `record.tags = "a, b"` assignment is cleaned too. An empty list stores `NULL`.
 - `tag_counts` runs one `GROUP BY` on the raw column — identical tag strings ship once with their row count and are split in Ruby — so it scales with distinct tag strings, not rows; ordered by count desc then name, `limit:` keeps the top N.
 - Reach for [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on) when you need tag contexts, ownership, or polymorphic tags shared across models.
@@ -1360,7 +1381,7 @@ One entry is recorded **per changed field per save** (creates record `"from" =>
 
 ## 🔐 Lockable
 
-Failed-attempt tracking + **account lockout** ("Devise lockable-lite") for apps rolling their own authentication (Rails 8 auth generator / `has_secure_password`) — which ships **no brute-force protection** out of the box. Two columns on the model's own table; no tokens, no mailers.
+Failed-attempt tracking + **account lockout** ("Devise lockable-lite") for apps rolling their own authentication (Rails 8 auth generator / `has_secure_password`) — which ships **no brute-force protection** out of the box. Two columns on the model's own table (plus an optional unlock-token column for self-service unlock links); no mailers.
 
 ```ruby
 class User < ApplicationRecord
@@ -1380,9 +1401,14 @@ user.unlock_access!             # manual unlock   (hooks: before/after_unlock)
 User.locked / User.unlocked     # expiry-aware scopes
 
 User.unlock_expired              # => 3 — unlocks every row whose unlock_in window has elapsed
+
+# Self-service unlock (Devise's :email strategy, minus the mailer) — needs a string column:
+#   lockable_by max_attempts: 5, unlock_token: :unlock_token
+user.lock_access!; user.unlock_token   # minted in the same write as the lock — mail it as a link
+User.unlock_by_token(params[:token])   # constant-time lookup; unlocks once (hooks fire), returns the user or nil
 ```
 
-**Options**: `attempts:` (`:failed_attempts`, must be an integer column), `locked_at:` (`:locked_at`, datetime column), `max_attempts:` (`5`; `nil` = count but never auto-lock), `unlock_in:` (`nil` = locked until manual unlock; a duration makes the lock lapse by itself), `prefix:` / `suffix:` (affix the scope names).
+**Options**: `attempts:` (`:failed_attempts`, must be an integer column), `locked_at:` (`:locked_at`, datetime column), `max_attempts:` (`5`; `nil` = count but never auto-lock), `unlock_in:` (`nil` = locked until manual unlock; a duration makes the lock lapse by itself), `unlock_token:` (`nil`; a string column that receives a 43-char URL-safe token on lock, is cleared by every unlock path, and is honoured only while the lock is live — so `unlock_in:` doubles as the link's TTL), `prefix:` / `suffix:` (affix the scope names).
 
 **Bulk operations**
 
@@ -1532,13 +1558,31 @@ Patient.where_email("a@b.com")       # chainable Relation (accepts arrays too)
 
 **Options** (`encryptable *fields, …`, repeatable): `type:` (cast the decrypted value — `:string` default, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`), `key:` (per-field override; a String or lazy Proc), `blind_index:` (`true`, or `{ column:, expression: }` — maintains a deterministic keyed-HMAC companion column, default `<field>_bidx`, for equality lookups; `expression:` normalizes symmetrically on write and query).
 
+**Key rotation** — bump the key id, keep the old key for decrypting, re-encrypt, drop the old key:
+
+```ruby
+ConcernsOnRails.configure_encryption do |c|
+  c.key           = ENV["ENCRYPTION_KEY_V2"]          # encrypts every new write
+  c.key_id        = 1                                 # stamped into the envelope header (any id 0..255)
+  c.previous_keys = { 0 => ENV["ENCRYPTION_KEY_V1"] } # still DECRYPTS rows written before the rotation
+end
+
+Patient.needs_reencryption.count        # rows still under an old key — a prefix compare on the envelope, no decryption
+Patient.reencrypt_all!                  # rewrite them (and their blind indexes) under the current key → count
+patient.ssn_key_id                      # => 1
+# then remove `0 =>` from previous_keys
+```
+
+Reads pick the key by the envelope's id, so old and new rows coexist; `find_by_<field>` / `where_<field>` match blind-index digests under the current **and** previous keys during the window. Per-field `key:` fields sit outside rotation.
+
 **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).
+- `update_column(s)` on an encrypted field DOES encrypt (the value still serializes through the attribute type), but it skips validations, callbacks, dirty tracking and the blind-index refresh — so a value written that way is unsearchable until the row is saved normally. 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).
+- Rotation is gem-level (`key_id` / `previous_keys`); `reencrypt_all!` streams with `find_each` and rewrites each row with one UPDATE — no validations/callbacks (only the ciphertext changes), guarded on the ciphertext it read so a concurrent write is never reverted, and skipping any field with an unsaved change. A row whose key id is no longer configured raises `DecryptionError` naming the id.
+- Reach for [`lockbox`](https://github.com/ankane/lockbox) or Rails 7+ native `encrypts` when you need Rails-managed key infrastructure (KMS, per-record keys) or deterministic encryption.
 
 ---
 
@@ -1753,6 +1797,8 @@ class ArticlesController < ApplicationController
   filter_by :status, :category                                       # ?status=draft → .where(status: 'draft')
   filter_by :published, scope: :published                            # ?published=1 → Article.published
   filter_by :q, with: ->(rel, v) { rel.where("title ILIKE ?", "%#{v}%") }
+  filter_by :price, :created_at, operators: true                     # ?price_gte=10&created_at_lt=2026-01-01
+  filter_by :min_stock, type: :integer, with: ->(rel, v) { rel.where(rel.model.arel_table[:stock].gteq(v)) }
 
   def index
     render json: filtered(Article.all)
@@ -1760,6 +1806,24 @@ class ArticlesController < ApplicationController
 end
 ```
 
+**Operators** (opt-in per filter, direct-where mode only — `operators: true` or a subset like `%i[gte lte]`),
+accepted as a suffix `?price_gte=10` or in bracket form `?price[gte]=10&price[lte]=50`:
+
+| Operator | Param                              | SQL                                   |
+|----------|------------------------------------|---------------------------------------|
+| `not`    | `?status_not=draft`                | `status != 'draft'`                   |
+| `gt` `gte` `lt` `lte` | `?price_gte=10`       | `price >= 10` (cast through the column type) |
+| `in` `not_in` | `?status_in=a,b` or `?status_in[]=a` | `status IN ('a','b')`         |
+| `null`   | `?deleted_at_null=true`            | `deleted_at IS NULL` (`false` → `IS NOT NULL`) |
+| `contains` `starts_with` | `?title_contains=rails` | `title LIKE '%rails%'` (wildcards escaped; ILIKE on PostgreSQL) |
+
+Comparison values are cast the way ActiveRecord casts them (the column's own type), or through `type:`
+(any ActiveModel type name); `type:` also pre-casts the value handed to a `with:` lambda. Blank values
+are skipped and unknown operators / non-scalar values ignored. A `gt`/`gte`/`lt`/`lte` value the type
+cannot represent (`?price_gte=abc`) matches **nothing** rather than silently comparing against `0` —
+nothing raises at request time. `contains`/`starts_with` are case-insensitive on PostgreSQL, MySQL and
+SQLite alike. For strict, validated contracts reach for `Permittable`.
+
 **Modes**
 
 | Mode        | Declaration                          | What it does                                    |
@@ -1770,7 +1834,7 @@ end
 
 **Notes**
 - Blank params are skipped — unset filters don't narrow the relation.
-- Passing both `:scope` and `:with` raises `ArgumentError`.
+- Passing both `:scope` and `:with` raises `ArgumentError`; so do `operators:` on a `scope:`/`with:` filter, an unknown operator name, or an unknown `type:` — all at class load.
 - Scope mode pairs naturally with `Publishable.published`, `SoftDeletable.active`, `Expirable.active`, etc.
 
 ---
@@ -1825,9 +1889,9 @@ class Api::ArticlesController < ApplicationController
   def create
     article = Article.new(article_params)
     if article.save
-      render_success(data: article, status: :created)
+      render_created(data: article, location: article_url(article))   # 201 + Location
     else
-      render_error(message: "Invalid", errors: article.errors.full_messages)
+      render_invalid(article)                                          # 422 record_invalid + full_messages
     end
   end
 end
@@ -1861,7 +1925,9 @@ respondable_by error_format: :problem_details, problem_type_base: "https://api.e
 
 | Method            | Signature                                                                                  |
 |-------------------|--------------------------------------------------------------------------------------------|
-| `render_success`  | `render_success(data: nil, status: :ok, meta: {})`                                         |
+| `render_success`  | `render_success(data: nil, status: :ok, meta: {}, location: nil, headers: {})` — `location:` sets the `Location` header (a String, or anything `url_for` resolves); `headers:` sets extra response headers (names and values are coerced to String and stripped of CR/LF, so caller data cannot split the response) |
+| `render_created`  | `render_created(data: nil, location: nil, meta: {}, headers: {})` — `render_success` with `status: :created` |
+| `render_invalid`  | `render_invalid(record_or_errors, message: "Validation failed", status: :unprocessable_entity, code: "record_invalid")` — `render_error` with `errors.full_messages` as `details` (omitted when empty, and when an app's `render_error` override cannot take an `errors:` keyword); same shape as ErrorHandleable's `RecordInvalid` handler, problem-details aware |
 | `render_error`    | `render_error(message:, status: :unprocessable_entity, code: nil, errors: nil)`            |
 | `respondable_by`  | `respondable_by(error_format: :envelope, problem_type_base: nil)` — class-level; `error_format:` is `:envelope` (default) or `:problem_details` |
 
@@ -2229,12 +2295,13 @@ end
 | `:stripe` | `Stripe-Signature` | `t=<unix>,v1=<hex>[,v1=…]` — signs `"#{t}.#{body}"`, every `v1` tried, `tolerance:` rejects stale **and** future timestamps |
 | `:hex` / `:base64` | — (`header:` required) | plain hex / strict Base64 HMAC of the body |
 
-**Options**: `*actions` (none = catch-all; the first matching rule wins), `secret:` (String, callable `instance_exec`'d per request, or Array for rotation — any match passes), `scheme:` (`:hex`), `header:` (overrides the preset), `tolerance:` (Stripe only, `300`s default), `digest:` (`:sha256`; `:sha1`/`:sha512` for `:hex`/`:base64` only).
+**Options**: `*actions` (none = catch-all; the first matching rule wins), `secret:` (String, callable `instance_exec`'d per request, or Array for rotation — any match passes), `scheme:` (`:hex`), `header:` (overrides the preset), `tolerance:` (Stripe only, `300`s default), `digest:` (`:sha256`; `:sha1`/`:sha512` for `:hex`/`:base64` only), `replay:` (`true` = the gem-wide `cache_store`, a store object, or `false`/`nil` for off) + `replay_ttl:` (`24.hours`) — replay protection for the schemes that carry no timestamp.
 
 **Notes**
 - Comparison is constant-time and the attacker-controlled header is **never decoded** — garbage (including invalid UTF-8 bytes) just fails with 401, it cannot raise.
 - A secret that resolves **blank at request time raises `ArgumentError`** — a misconfigured endpoint should page you, not 401 into the provider's silent retry loop.
-- Failure codes: `webhook_signature_missing` / `webhook_signature_invalid` / `webhook_timestamp_stale` → 401; `webhook_signature_malformed` (unparseable Stripe header) → 400. With `Respondable`, bodies delegate to `render_error`; override `webhook_verification_failed` to customize.
+- **Replay protection** (`replay:`): GitHub, Shopify and plain-HMAC signatures carry no timestamp, so a captured delivery verifies forever. After a signature verifies, a SHA256 of what identifies the delivery — the signature header, or for Stripe the signed `"#{t}.#{body}"` payload, since unknown `v0=` keys and stray whitespace let a captured Stripe header be mutated without invalidating it — is written to the store with `unless_exist:` (atomic — memcached `add` / Redis `SET NX` via `Rails.cache`); a second delivery with the same signature within `replay_ttl:` is rejected with **409 `webhook_replayed`**. Forged traffic never consumes a slot; the key is scoped per controller action. The store must answer `#write(key, value, expires_in:, unless_exist:)` and `#read(key)` (`#delete(key)` is optional but recommended) — `Rails.cache` does. The marker is a short 60-second claim until the action finishes, then promoted to `replay_ttl:` — so a handler that 500s releases it at once, and one that raises (or a filter that halts after verification) leaves only the 60-second claim to expire, either way the provider's retry (identical body, identical signature) gets through. If the store is unreachable the check fails **open**: Rails' Redis and memcached stores return false from `#write` on a connection error, and rejecting every inbound delivery during a cache blip would be worse than accepting a rare duplicate. A per-process `MemoryStore` gives no protection across workers. Stripe's own retries re-sign with a new `t=`, so they pass; a manual GitHub redelivery has the identical signature and is treated as a replay — override `webhook_verification_failed` if you'd rather answer 200.
+- Failure codes: `webhook_signature_missing` / `webhook_signature_invalid` / `webhook_timestamp_stale` → 401; `webhook_signature_malformed` (unparseable Stripe header) → 400; `webhook_replayed` → 409. With `Respondable`, bodies delegate to `render_error`; override `webhook_verification_failed` to customize.
 - Declare **before** `Idempotentable` (a 401 cached by its around filter would be replayed) and before `Throttleable` (forged traffic shouldn't burn rate budget). Webhook endpoints also need `skip_before_action :verify_authenticity_token`.
 - In tests: `skip_before_action :verify_webhook_signature!`, or sign payloads for real with `OpenSSL::HMAC`. After a pass, `webhook_verified?` is true.
 
@@ -2401,12 +2468,12 @@ 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) |
+| Complex state machines — guard clauses, multi-state events, a full transition audit log (`Stateable` has per-event hooks and `<state>_at` stamps, but records no transition history) | [`aasm`](https://github.com/aasm/aasm) |
 | 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) |
 | Indexed full-text search — stemming, tsvector/GIN, typo tolerance (`Searchable` ranks LIKE matches, but never builds an index) | [`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) |
-| Field encryption with managed key rotation / Rails-native key infrastructure | [`lockbox`](https://github.com/ankane/lockbox) / Rails 7+ native `encrypts` |
+| Field encryption with KMS-backed / per-record keys or Rails-native key infrastructure | [`lockbox`](https://github.com/ankane/lockbox) / Rails 7+ native `encrypts` |
 | Deep clone with per-attribute regex/prepend rules or belongs_to graph copying | [`amoeba`](https://github.com/amoeba-rb/amoeba) |
 
 `Sluggable` wraps [`friendly_id`](https://github.com/norman/friendly_id) and `Sortable` wraps [`acts_as_list`](https://github.com/brendon/acts_as_list), so you get those leaders' engines behind the declarative macro.
@@ -2436,9 +2503,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,730 examples)
+bundle exec rspec                               # run the test suite (1,830 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.28.7.gem      # install locally
+gem install ./concerns_on_rails-1.28.9.gem      # install locally
 
 # Preview the docs site locally (GitHub Pages serves docs/ as-is):
 cd docs && python3 -m http.server 8000          # → http://localhost:8000