concerns_on_rails 1.31.0 → 1.32.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 493ce0d913905625ffaabf033052a0ccc631aa22fe3c9a06a04c776ad4a80f67
-  data.tar.gz: 022bb7a0230e1c9c8ebc210c43245cf458c9248f3810f24f02c731695c0c046d
+  metadata.gz: 3e44cfe4621a22897c4d3f6e2ade5b1485d7c686f10dd72fb0dd582a50eadd73
+  data.tar.gz: 478bc126777b1627ffba7275f1f81421c0ce112b01e3348c30b4010a023af75c
 SHA512:
-  metadata.gz: 55cd86cfb3b04af3972060c2d4455dca7fe2ee7abfdccfa029c75ee6a9caee4b6700eeb128dd3f15aec5c52460af7ca5936935185593788d02df9c050044e3fa
-  data.tar.gz: 750dda120eb24d9e3d121a8e4ec1828e2d26303677f5758bc415f138fa4497845e1b67219203dc593ad5fe55a1a406e77d544b292f1639d4aa56546bb855010a
+  metadata.gz: bf067b1d2068e59ed7007bddfc41e2b70a287a57e6e3727e0fba8653ef4d4c1f892e158d6e012b96fbfb862eb1a2a8e48c17d60acc0891c2b85fc43f9c8bb17f
+  data.tar.gz: 71db79d7dd7e673b111d20a89a99d2ea7a95cd41c13ff3ededd017f27ef10a4351d7689b7aebcf04a2c8aedebbc0cee5bb8d8f57e1ac96bec1aaf5f838852171

data/CHANGELOG.md

@@ -1,5 +1,134 @@
 <!-- CHANGELOG.md -->
 
+## 1.32.1 (2026-10-08)
+
+A bug-fix release from a six-angle audit of 1.32.0 — data and encryption, state and counters,
+scopes and batch verbs, field transforms, request params, HTTP policy. Every finding was
+reproduced by a failing spec before it was fixed, and every fix ships with a regression spec;
+the batch then went through an adversarial review round. No new concerns, no new options and
+no migrations. A few fixes now raise where the gem used to misbehave silently — read
+**Changed** first. 2827 examples, 0 failures (2795 on Rails 6.0).
+
+### Changed
+- **Encryptable: Lockable's `unlock_token:` cannot be `encryptable`** (`ArgumentError` at
+  declaration, either order). The token is minted, claimed and cleared by callback-skipping
+  SQL keyed on the column value, so an encrypted token was never found: every unlock link was
+  dead. Keep it a plain column — it is random, single-use and cleared with the lock.
+- **Monetizable: an `encryptable` cents column is refused** (`ArgumentError`, either order):
+  `sum_`/`average_`/`minimum_`/`maximum_` ran SQL aggregates over ciphertext.
+- **Auditable: `audited_changes_since` reads its argument in `Time.zone`** — a `Date` is
+  midnight in `Time.zone`, a zone-less String is read in `Time.zone` (not the server's system
+  zone), and a String that names no time raises `ArgumentError` (`"junk"` used to mean June 1).
+- **Encryptable: blind indexes refresh in `before_create`/`before_update`**, after every
+  `before_save`, instead of in an include-time `before_save`. An app `before_save` that rewrites
+  the field (`self.email = email.downcase`) is now fingerprinted as stored, and a new row always
+  refreshes every indexed field, so a copy (`dup`, Duplicable's `reset:`) no longer keeps its
+  original's digest. Rows written by such a callback before this release keep a stale digest
+  until re-saved with a change.
+
+### Fixed
+- **Encryptable**: decrypted text reads back as UTF-8 (binary only when the bytes are not valid
+  UTF-8). Non-ASCII values compared unequal to what was written after a reload, were dirty on
+  every reassignment, and `reencrypt!` fingerprinted different bytes under a `downcase`
+  `expression:`, so rotated rows could no longer be found.
+- **Encryptable**: an empty-String column default (`text null: false, default: ""`) reads as
+  `""` instead of raising `DecryptionError` on every new record.
+- **Encryptable**: `find_by_<field>` / `where_<field>` / `<field>_fingerprint` run the lookup
+  value through the field's Normalizable rule and its Rails 7.1+ `normalizes`, as Rails' own
+  finders do.
+- **Storable**: a `:float` key given `"Infinity"`/`"NaN"` casts to nil instead of raising
+  `JSON::GeneratorError` (a 500 from a form field).
+- **SoftDeletable**: `without_deleted.really_destroy_all` (and any relation repeating the
+  default `deleted_at IS NULL`) no longer hard-deletes the trash, and `without_deleted.restore_all`
+  no longer restores it: only the default scope's own predicate is peeled off.
+- **`*_all` batch verbs** (`Support::BatchOps`) roll the whole batch back inside a caller's
+  transaction too: the batch runs in its own savepoint, so a caller rescuing the
+  `RecordNotSaved` no longer commits the records written before the failing one.
+- **Sluggable**: a record moved to another `scope:` value whose slug that scope already holds
+  rebuilds it against the new scope instead of duplicating it; a slug that is free there is kept.
+- **Sortable**: the position acts_as_list assigns in `before_create` is reported through
+  `Support::GeneratedValues`, so an Auditable model tracking it records it on create.
+- **CounterCacheable**: a save that changes a row's STI type (`becomes!`, `update!(type:)`)
+  judges the old state under the old type's rule and the new state under the new type's, and
+  destroy uses the persisted type's rule — the live counter no longer drifts from
+  `recount_counter_caches!`.
+- **Stateable `lock: true` / Activatable `toggle_active!`**: the reload under the row lock keeps
+  a loaded `belongs_to` parent whose foreign key it didn't change, so CounterCacheable's mirror
+  reaches the caller's parent instead of leaving it to raise `StaleObjectError`.
+- **Stateable**: `transition_all` no longer skips rows already in the target state when the
+  event's `from:` lists that state (a declared self-transition).
+- **Lockable**: `attempts_remaining` returns the full `max_attempts` once a lock has lapsed
+  (`unlock_in`), instead of 0 on an unlocked account.
+- **Sanitizable** `on: :write`, **Taggable** and **Addressable** also normalize in a prepended
+  `before_save` backstop (Normalizable's pattern), so `update_attribute` / `save(validate: false)`
+  no longer store raw markup, un-normalized tags or un-normalized address parts. A validated
+  save stores exactly what it stored before (the backstop never re-runs a rule on a value
+  validation already accepted).
+- **Maskable / Sanitizable**: `as_json(masked: true)` / `as_json(sanitized: true)` carry the flag
+  through every nested `include:` level, so a grandchild reached through a model without the
+  concern is no longer serialized raw.
+- **Masker `:email`** fails closed (full mask) unless the value is exactly one address, so a
+  second address in a list is no longer revealed.
+- **Monetizable**: a `Rational` amount converts (`Rational(1999, 100)` → 1999 cents) instead of
+  being stored as nil.
+- **Searchable / Taggable**: queries and tags are trimmed (and `mode: :all` split) on Unicode
+  whitespace — a no-break or ideographic space no longer becomes part of the LIKE pattern or a
+  distinct tag.
+- **Filterable**: a nested-array param (`?name[][]=a&name[][]=b`) is ignored instead of raising
+  a `TypeError` 500; a JSON-body number on a date/datetime column — compared, in equality,
+  `in`/`not_in`, or handed to a `type: :date` lambda — matches nothing instead of being bound raw
+  (a 500 on PostgreSQL); a date/time operand longer than 128 characters no longer raises
+  `Date._parse`'s `ArgumentError` (a 500) on Rails 6.0–7.0 and is answered as 7.1+ answers it.
+- **Paginatable**: a number where a nested page Hash belongs (`{"page": 2}` under
+  `style: :jsonapi`) falls back to the defaults instead of a `TypeError` 500.
+- **CursorPaginatable**: a page ending on a stored ±Infinity/NaN float no longer raises
+  `JSON::GeneratorError` on every request — the boundary is minted as a string and walked
+  correctly on PostgreSQL and SQLite; a tampered number/boolean for a date/time boundary, or an
+  over-long date String on Rails 6.0–7.0, is an `InvalidCursor` (400), not a decoded position
+  or a 500.
+- **Paginatable / CursorPaginatable**: `Link` header URLs are percent-encoded inside `<…>`, so a
+  crafted request path can no longer inject extra Link entries.
+- **Throttleable**: the first-hit seed is written `raw: true` (to any store whose `write` takes
+  options), so a memcached `Rails.cache` on Rails 6.0–7.0 enforces the limit again (every later
+  `increment` returned nil and the 429 never fired).
+- **Timezoneable**: a `Time-Zone` header or `time_zone` cookie that is not valid UTF-8 is ignored
+  instead of raising a 500 (persistently, for the cookie); the `available:` allow-list matches by
+  zone, not spelling, so `America/New_York` matches an allow-listed `Eastern Time (US & Canada)`.
+- **Cacheable**: per-call `stale_resource?(r, extras: [...])` downgrades `Cache-Control` to
+  `private`, like a Vary-less `etag_with` source, so a CDN no longer serves one caller's
+  representation to the next.
+- **Localizable**: `Accept-Language: pt-BR` (and `?locale=pt-br`) selects an available `:pt_BR`;
+  `-` and `_` are one separator (an exact spelling still wins).
+
+### Known issues (not fixed in this release)
+- CounterCacheable: a parent destroyed inside the same rolled-back transaction keeps the
+  mirrored counter/lock_version in memory.
+- Aliasable: eager-loading an alias together with its source in one query loads each child twice.
+- Encryptable: on the pre-7.1 Marshal format, a record whose field has a per-field Proc `key:`
+  cannot be `Marshal.dump`ed (`Rails.cache`).
+- CursorPaginatable: on PostgreSQL, a page ending on a timestamp stored as `'infinity'` now mints
+  its cursor (it used to be a 500), but the next page answers 400 — the walk cannot step past it.
+
+## 1.32.0 (2026-10-07)
+
+A dependency release (#127): the `permittable` floor rises to `>= 0.8`, and the Permittable docs
+are rewritten against permittable 0.10. It is a minor release because hosts still on permittable
+0.1–0.7 must upgrade it (the same rule as the Rails floor raise in 1.29.0). No code change, no
+new concerns and no migrations. 2723 examples, 0 failures, green on PostgreSQL, MySQL and every
+Rails line from 6.0 to 8.1.
+
+### Changed
+- **`permittable` dependency floor raised from `~> 0.1` to `>= 0.8, < 1`.** The Permittable
+  documentation (README section and docs page) was rewritten against permittable 0.10 — monitor
+  mode, `:json` fields, `nullable:`, `message:`/I18n copy, `format:` presets, field groups,
+  RFC 9457 output, the type-checking drift guard, the `permittable:generate`/`:audit`/`:openapi`
+  tasks, RSpec matchers and standalone contracts — and the old pin let a host resolve a 0.x that
+  had none of it. 0.8 is the floor because it is the newest line that still supports Rails 6.0
+  (0.9+ requires ActiveSupport >= 6.1), so the 6.0 CI line keeps resolving; the docs carry a
+  heads-up listing what a 0.8 host lacks and how Respondable's `:problem_details` and the gem's
+  own `Permittable.error_format = :problem` interact. No code change; the gem README stays the
+  canonical Permittable reference.
+
 ## 1.31.0 (2026-10-05)
 
 The fixes from two audits, each fix put through adversarial review rounds until a reviewer

data/README.md

@@ -101,7 +101,7 @@ Every concern below links to its section in this README **and** to its standalon
 | [🪝 WebhookVerifiable](#-webhookverifiable) | HMAC verification for inbound webhooks | [📖](https://vsn2015.github.io/concerns_on_rails/#/c/webhook-verifiable) |
 | [🌅 Deprecatable](#-deprecatable) | RFC `Deprecation` / `Sunset` headers + 410 | [📖](https://vsn2015.github.io/concerns_on_rails/#/c/deprecatable) |
 | [🗄️ Cacheable](#-cacheable) | HTTP conditional GET (ETag / 304) + `Cache-Control` | [📖](https://vsn2015.github.io/concerns_on_rails/#/c/cacheable) |
-| [🛂 Permittable](#-permittable) | Typed, validated params contracts + schema-drift guard | [📖](https://vsn2015.github.io/concerns_on_rails/#/c/permittable) |
+| [🛂 Permittable](#-permittable) | Typed, validated params contracts, schema-drift guard, OpenAPI export | [📖](https://vsn2015.github.io/concerns_on_rails/#/c/permittable) |
 
 ---
 
@@ -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** — **2,483 RSpec examples** run against a real database on every CI build
+- **Tested like an app, not a snippet** — **2,827 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
 
 ---
@@ -158,7 +158,7 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 Add to your application's `Gemfile`:
 
 ```ruby
-gem "concerns_on_rails", "~> 1.31"
+gem "concerns_on_rails", "~> 1.32"
 ```
 
 Or pull the latest from GitHub:
@@ -203,8 +203,22 @@ still wins over the gem-wide fallback.
 - **Rails**: 6.0 through 8.1
 
 Every one of those lines runs the full suite on every push — Rails 6.0, 6.1, 7.0, 7.1, 7.2,
-8.0 and 8.1 on SQLite, plus PostgreSQL and MySQL, and Ruby 3.3/3.4 against the current
-lines. See [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+8.0 and 8.1 on SQLite, plus PostgreSQL and MySQL. Ruby 3.2, 3.3, 3.4 and 4.0 each run
+against every one of those Rails lines, and a non-blocking ruby-head job gives early
+warning of the next Ruby. See [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+
+**Rails 6.0/6.1 on Ruby 3.4+** needs a few Gemfile lines that Rails 6.x itself never
+declared. Ruby 3.4 and 4.0 moved these libraries out of the default gems, and without them
+`require "active_record"` fails with `LoadError: cannot load such file -- mutex_m`:
+
+```ruby
+gem "base64"
+gem "bigdecimal"
+gem "drb"
+gem "mutex_m"
+gem "benchmark" # Ruby 4.0+
+gem "logger"    # Ruby 4.0+
+```
 
 **Rails 5.x is not supported**, despite what older versions of this gem declared. Rails 5
 cannot run on any Ruby this gem supports: Ruby 3 separated keyword arguments, which breaks
@@ -1257,7 +1271,7 @@ end
 | `fingerprint:`    | `nil`                                | A `string` column to store `address_fingerprint` in (stamped in `before_validation`, after normalization) so duplicates are one indexed query away: `Location.with_address(record)`. |
 | `if:` / `unless:` | `nil`                                | Standard Rails validation conditions (Symbol, Proc, or Array) gating the address **validations** — e.g. `if: :on_addresses?`. Normalization still runs unconditionally. Per class: a later `addressable_by` (or a subclass's) replaces the condition. Procs get Rails' callback arguments for their arity (`-> {}`, `->(record) {}`, `->(record, _) {}`). |
 
-**What it normalizes** (in `before_validation`)
+**What it normalizes** (in `before_validation`, plus a `before_save` backstop for saves that skip validation)
 - Text parts: `strip` + `squish`.
 - `postal_code`: squish + upcase, with canonical spacing for CA (`A1A1A1` → `A1A 1A1`).
 - `country` / `state`: upcased when they look like a 2-letter code (full names left alone). With `normalize_country: true`, a recognized ISO country name or alpha-3 code is canonicalized to its alpha-2 (`"Canada"`/`"CAN"` → `"CA"`); unrecognized values are left as-is.
@@ -1335,7 +1349,7 @@ Article.normalize_tags!                        # repair rows written around the
 **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`.
+- Tags are normalized in `before_validation` (plus a `before_save` backstop for saves that skip validation), so a direct `record.tags = "a, b"` assignment is cleaned too. An empty list stores `NULL`.
 - An [Encryptable](#-encryptable) tag column holds ciphertext, which `tagged_with`'s `LIKE` never matches — declaring it raises `ArgumentError` at declaration, in either order (an undeclared default `:tags` column is refused when `tagged_with` is called).
 - `tagged_with` matches the **normalized** column form (`"ruby,rails"`) — which every write through the model produces. A row written around the callbacks (`update_column`, `update_all`, raw SQL, an import) as `"ruby, rails"` is found by `tagged_with?` but not by `tagged_with`; run `Model.normalize_tags!` (relation-aware, one `update_columns` per changed row in a transaction, no validations/callbacks, returns the count; `unscoped` to include default-scoped-away rows) to rewrite such rows.
 - `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.
@@ -1394,7 +1408,7 @@ Article.where(legacy: true).sanitize_all!(:body)   # scope-aware, subset of fiel
 
 **Notes**
 - `on: :read` (default) is **non-destructive**: it adds a `sanitized_<field>` reader and leaves the stored column untouched.
-- `on: :write` overwrites the column in `before_validation` — **lossy and irreversible** (never use it on code, Markdown, math, or prices), and bypassed by `update_column` / `update_all` / raw SQL.
+- `on: :write` overwrites the column in `before_validation` (plus a `before_save` backstop for `update_attribute` / `save(validate: false)`) — **lossy and irreversible** (never use it on code, Markdown, math, or prices), and bypassed only by `update_column` / `update_all` / raw SQL.
 - `with: :strip, on: :write` stores **plain text**, not HTML-escaped text: `"<b>Tom</b> & Jerry"` is stored as `"Tom & Jerry"` (so `<%= %>` shows it once, not as `Tom &amp;amp; Jerry`). `&lt;` / `&gt;` are deliberately kept encoded — the stored value can never become markup, even rendered with `raw` — so a typed `a < b` is stored as `a &lt; b`. An `&amp;` that would read back as a character reference (a literal `&amp;copy;`) also stays encoded (a static, linear-time rule: `&` followed by `#`, a `name;`, or an HTML5 semicolon-less legacy name), so re-saving and `sanitize_all!` are idempotent. `sanitize_all!` uses the same plain-text form, and repairs rows stored double-escaped by earlier versions. The `on: :read` reader and `sanitized:` serialization still return HTML-escaped text.
 - `sanitize_all!` is the repair tool for that bypass (and for rows written before the concern was added): one `update_columns` per row that actually changes, skipping validations/callbacks on purpose, inside a transaction. A bare call repairs the `on: :write` fields only — with none declared it returns `0` without a query.
 - `sanitized:` sanitizes the **serialized** value, so it composes with [Maskable](#-maskable) in either include order: `as_json(masked: true, sanitized: true)` never falls back to the raw column.
@@ -2583,7 +2597,12 @@ etag_with { current_user&.role }             # => Cache-Control: private, max-ag
 
 ## 🛂 Permittable
 
-Declarative, **typed params contracts** — what strong parameters would be if it also knew types, bounds, defaults, and *why* a request was bad. `params.permit` (and Rails 8's `params.expect`) only answer "which keys may pass"; a Permittable contract additionally **casts** each field, **validates** it, applies **defaults**, and turns every failure into a machine-readable 422. Because the contract is class-level data (not code inside the action), it is introspectable — and can be checked against a model's schema at boot.
+Declarative, **typed params contracts** — what strong parameters would be if it also knew types, bounds, defaults, and *why* a request was bad. `params.permit` (and Rails 8's `params.expect`) only answer "which keys may pass"; a Permittable contract additionally **casts** each field, **validates** it, applies **defaults**, optionally **reshapes** the output, and turns every failure into a machine-readable 422. Because the contract is class-level data (not code inside the action), it has readers beyond the validator: a boot-time **schema-drift guard**, an **OpenAPI 3.1** exporter, **RSpec matchers**, a route-set **coverage audit**, a **draft generator**, and a standalone `Contract` for any Hash.
+
+> **Heads up — two things to know before relying on this section**
+>
+> 1. **Your lockfile, not this page, decides which features you have.** The pin is `>= 0.8, < 1`, so everything up to 0.8 (monitor mode, `:json`, `nullable:`, `message:`, field groups, matchers, generator, OpenAPI) is guaranteed, and an app that locked 0.8 keeps it until `bundle update permittable`. permittable 0.9+ requires ActiveSupport >= 6.1, so on Rails 6.0 Bundler stops at permittable **0.8**. That version lacks `format:` presets, `Permittable.check_column_types` and the enum rule, `Permittable.error_format = :problem`, `permittable:audit`, `params.expect` scanning in the generator, and the 0.10 canonical-numeric tightening (`"1_8"` and `" 99 "` still cast there). Everything else here applies. To make the newer surface a hard requirement, pin `gem "permittable", ">= 0.10"` in the app's Gemfile.
+> 2. **Two RFC 9457 switches exist — use one.** With [Respondable](#-respondable) included, Permittable's 422s render through `render_error`, so `respondable_by error_format: :problem_details` turns them into problem documents together with every other concern. The gem's own `Permittable.error_format = :problem` also renders RFC 9457 but deliberately **bypasses** `render_error`, so a controller with both set follows the gem's setting and ignores Respondable's envelope customisations.
 
 ```ruby
 class UsersController < ApplicationController
@@ -2591,10 +2610,12 @@ class UsersController < ApplicationController
 
   permit_params :create, :update, root: :user, model: User do
     required :name,  :string,  length: 1..80, normalize: :squish
-    required :email, :string,  format: URI::MailTo::EMAIL_REGEXP, normalize: :email
+    required :email, :string,  format: :email, normalize: :email
     optional :age,   :integer, in: 18..120
     optional :ssn,   :string,  sensitive: true          # auto-redacted from logs
     optional :plan,  :string,  in: %w[free pro], default: "free"
+    optional :nickname, :string, nullable: true         # explicit null clears the column
+    optional :metadata, :json, max_depth: 3, length: 0..32
     array    :tag_names, of: :string, length: 0..10
     optional :address do
       required :city, :string
@@ -2615,19 +2636,23 @@ end
 #                            { param: "user.age",  code: "inclusion" }] } }
 ```
 
-**The schema-drift guard** is the headline: with `model:` (a class, or `true` to infer from the controller name), every non-`virtual:` scalar field is checked against the model's columns **at controller class load** through the same `ColumnGuard` all model concerns use. A column dropped by a migration fails the deploy (production eager-loads controllers) with a teaching error — the missing-column message plus a ready-to-paste migration command plus the `virtual: true` escape hatch. Nested/array fields are implicitly virtual; the check skips gracefully when the schema is unreachable (`db:create`, `assets:precompile`). In CI, one `Rails.application.eager_load!` spec exercises every contract in the app.
+**The schema-drift guard** is the headline: with `model:` (a class, or `true` to infer from the controller name), every non-`virtual:` scalar field is checked against the model's columns **at controller class load**. A column dropped by a migration fails the deploy (production eager-loads controllers) with a teaching error — the missing-column message plus a ready-to-paste migration command plus the `virtual: true` escape hatch. Nested/array fields are implicitly virtual; the check skips gracefully when the schema is unreachable (`db:create`, `assets:precompile`). Opt into the type half with `Permittable.check_column_types = true` (families: text / numeric incl. boolean / temporal; a Rails `enum` must be declared `:string, in: Model.statuses.keys`). In CI, one `Rails.application.eager_load!` spec exercises every contract in the app.
+
+**Options** (`permit_params *actions, …`, repeatable; no actions = catch-all; **last matching rule wins**, subclasses inherit copy-on-write): `root:` (key to unwrap, `require(:user)`-style; missing root → **400**; default `false` = top-level params), `model:` (schema-drift guard), `unknown:` (`:ignore` default / `:log` / `:error` — undeclared keys at every nesting level; Rails' router/form/CSRF keys, the route's path params and ParamsWrapper's copy are exempt at the top level), `enforce:` (`false` = validate lazily on first `permitted_params` call, memoized per action; `true` = validate in a `before_action`), `mode:` (`:monitor` reports instead of rejecting — see below), `desc:` (OpenAPI operation description).
+
+**Field DSL**: `required`/`optional` `name, type` (`:string` default, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`, and `:json` — a free-form hash for `jsonb` columns, bounded by `length:` keys and `max_depth:`) with `in:` (Range, or a list snapshotted and cast at load — `in: Post.statuses` works), `format:` (Regexp or a preset: `:email`/`:uuid`/`:url`/`:slug`/`:hostname`), `length:`/`normalize:` (`:squish`/`:strip`/`:downcase`/`:upcase`/`:email` or a Proc; string fields only), `default:` (validated against the field's own contract at load time), `nullable:` (an explicit `null`/`""` yields `nil` instead of counting as absent — the one way to clear a column; wins over `default:`), `message:` (per-field copy, String or code → String; app-wide copy via I18n `permittable.errors.<code>`), `validate:` (Proc — falsy fails as `"invalid"`, a returned Symbol becomes the violation code), `transform:` (see below), `virtual:`, `sensitive:` (registers with the gem-wide filter_parameters registry, same pipe as Encryptable; cascades into nested blocks, `sensitive: false` opts a sub-field out), `desc:`/`example:` (docs). Nested hashes via a block; `array :name, of: :type` (or a block for arrays of hashes) with `length:` as element count — short-circuiting, and there is no default cap — and per-index violation paths (`items[1]`). Reusable **field groups**: `Permittable.fields { … }` + `use Group` (`optional: true` turns a create contract into a PATCH contract; `only:`/`except:`).
 
-**Options** (`permit_params *actions, …`, repeatable; no actions = catch-all; **last matching rule wins**, subclasses inherit copy-on-write): `root:` (key to unwrap, `require(:user)`-style; missing root → **400**; default `false` = top-level params), `model:` (schema-drift guard), `unknown:` (`:ignore` default / `:log` / `:error` — undeclared keys at every nesting level; Rails' `controller`/`action`/`format` keys are exempt at the top level), `enforce:` (`false` = validate lazily on first `permitted_params` call; `true` = validate in a `before_action` so the action body never runs on bad input).
+**Output reshaping** — the safe replacement for params-mutating before_actions, operating on the validated copy only (the request's `params` is never touched). `transform:` applies a callable **after** cast + validation to reshape that field's output — `transform: ->(v) { v.split(",") }` turns a validated delimited String into an Array (absent fields stay absent, a `default:` on a transformed field is handed out as authored, a partially-invalid array is never transformed). `finalize do |p| … end` (once per contract, top level only) runs after every field validated cleanly, receives the result hash, and returns the final shape — zip parallel fields into value objects, drop scaffolding keys. It executes on a bare runner, **not** the controller, so contracts stay pure; its one extra verb, `violate!(param, code, message: nil)`, records a violation and halts the block immediately — doubling as the cross-field validation seam ("ends_at after starts_at").
 
-**Field DSL**: `required`/`optional` `name, type` (`:string` default, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`) with `in:` (Range/Array), `format:`/`length:`/`normalize:` (`:squish`/`:strip`/`:downcase`/`:upcase`/`:email` or a Proc; string fields only), `default:` (validated against the field's own contract at load time), `validate:` (Proc — falsy fails as `"invalid"`, a returned Symbol becomes the violation code), `transform:` (see below), `virtual:`, `sensitive:` (registers with the gem-wide filter_parameters registry, same pipe as Encryptable). Nested hashes via a block; `array :name, of: :type` (or a block for arrays of hashes) with `length:` as element count and per-index violation paths (`items[1]`).
+**Coercion is strict** — deliberately not `ActiveModel::Type` ("abc".to_i == 0 and `Boolean.cast("abc") == true` silently corrupt untrusted input): a value the type can't faithfully represent is an `invalid_type` violation, numeric strings must be canonical (`"1_8"` and `" 99 "` are refused), dates must be complete (never filled in from today), booleans accept only `true/false/"true"/"false"/"1"/"0"/1/0`, and array/hash type-confusion (`?age[]=1`) is rejected instead of 500ing. `nil` and `""` are both **absent**: absent optional fields are *omitted* from the result (partial updates never nil-out columns), absent required fields violate, `default:` fills absence.
 
-**Output reshaping** — the safe replacement for params-mutating before_actions, operating on the validated copy only (the request's `params` is never touched). `transform:` (scalar/array fields) applies a callable **after** cast + validation to reshape that field's output — `transform: ->(v) { v.split(",") }` turns a validated delimited String into an Array (absent fields and `default:` values are untouched; a partially-invalid array is never transformed). `finalize do |p| … end` (once per contract, top level only) runs after every field validated cleanly, receives the result hash, and returns the final shape — zip parallel fields into value objects, drop scaffolding keys. It executes on a bare runner, **not** the controller, so contracts stay pure; its one extra verb, `violate!(param, code)`, records a violation and halts the block immediately — doubling as the cross-field validation seam ("ends_at after starts_at").
+**Adopting on a live API**: `bin/rails permittable:generate` drafts a contract per controller from the model's columns and the `params.permit`/`params.expect` calls already in the source (in monitor mode, every guess a visible TODO); `mode: :monitor` / `Permittable.mode = :monitor` runs the pipeline but **reports instead of rejecting** (notification with `mode: :monitor`, raw params passed through, `permittable_violations` for the action to branch on); `bin/rails permittable:audit` lists every routed action with its effective mode and flags write actions that accept a body with no contract (`audit[strict]` exits 1 — a CI gate); then flip to enforce controller by controller.
 
-**Coercion is strict** — deliberately not `ActiveModel::Type` ("abc".to_i == 0 and `Boolean.cast("abc") == true` silently corrupt untrusted input): a value the type can't faithfully represent is an `invalid_type` violation, booleans accept only `true/false/"true"/"false"/"1"/"0"/1/0`, and array/hash type-confusion (`?age[]=1`) is rejected instead of 500ing. `nil` and `""` are both **absent**: absent optional fields are *omitted* from the result (partial updates never nil-out columns), absent required fields violate, `default:` fills absence.
+**Beyond the controller**: `require "permittable/rspec"` gives `permit_param(:age).for_action(:create).as(:integer).within(18..120)` (the declaration) and `accept_params(payload).returning(hash)` / `reject_params(payload).with_violation("user.age", :inclusion)` (the behaviour) without dispatching a request; `Permittable::Contract.define(root: :user) { … }` runs the same DSL on any Hash (`call` → a `Result`, `call!` raises); `bin/rails permittable:openapi[path]` exports an **OpenAPI 3.1** document from the same frozen data the server enforces — anything JSON Schema can't express stays visible as an `x-permittable-*` extension instead of being mistranslated, and the output is deterministic so it can be committed.
 
-**Failure surface**: violations raise `Permittable::InvalidParameters` (carries `details` + `status`), auto-`rescue_from`d into the shared error envelope (`Respondable#render_error` when included, the identical inline JSON otherwise) and instrumented as `invalid_parameters.permittable` for dashboards. Introspect contracts via `permittable_contracts` / `permit_rule_for(action)`. Naming note: legacy InheritedResources controllers also define `permitted_params` — don't mix the two on one controller.
+**Failure surface**: violations raise `Permittable::InvalidParameters` (carries `details` + `status`; a missing/malformed `root:` is **400**, field violations **422**), auto-`rescue_from`d into the shared error envelope — `Respondable#render_error` when included (so `respondable_by error_format: :problem_details` makes them RFC 9457 along with the rest of the app), the identical inline JSON otherwise; the gem's own `Permittable.error_format = :problem` renders RFC 9457 too but bypasses `render_error`, so pick one switch. Instrumented as `invalid_parameters.permittable` (`controller`, `action`, `mode`, `details`), exactly once per action per request. Introspect contracts via `permittable_contracts` / `permit_rule_for(action)`. Naming note: legacy InheritedResources controllers also define `permitted_params` — don't mix the two on one controller.
 
-> Permittable ships as the standalone [`permittable` gem](https://github.com/VSN2015/permittable) (a runtime dependency of concerns_on_rails); `ConcernsOnRails::Controllers::Permittable` is an alias for `::Permittable`, with `sensitive:` registrations pooled into this gem's shared filter_parameters registry.
+> Permittable ships as the standalone [`permittable` gem](https://github.com/VSN2015/permittable) (a runtime dependency, `>= 0.8, < 1`; this section describes 0.10); `ConcernsOnRails::Controllers::Permittable` is an alias for `::Permittable`, with `sensitive:` registrations pooled into this gem's shared filter_parameters registry. Full reference: [the gem README](https://github.com/VSN2015/permittable#readme) · [docs page](https://vsn2015.github.io/concerns_on_rails/#/c/permittable).
 
 ---
 
@@ -2697,9 +2722,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 (2,723 examples)
+bundle exec rspec                               # run the test suite (2,827 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.31.0.gem      # install locally
+gem install ./concerns_on_rails-1.32.1.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/cacheable.rb

@@ -64,7 +64,8 @@ module ConcernsOnRails
     #     method, a block, or a preset with `vary: false` — makes the response
     #     unshareable, so `Cache-Control` is emitted as `private` however the
     #     rule declared its `visibility:`. `:query` is exempt: the URL already
-    #     carries it.
+    #     carries it. Per-call `extras:` are such a source too (they carry no
+    #     Vary), so a request that passes any is `private` as well.
     #
     # Notes:
     #   * `no_store: true` overrides everything (emits the lone `no-store`),
@@ -279,10 +280,13 @@ module ConcernsOnRails
       # the computed { etag:, last_modified: } pair. Class-level `etag_with`
       # values and per-call `extras:` are folded into the ETag (an explicit
       # `etag:` stays verbatim only when there are none), and the sources' Vary
-      # headers are merged into the response.
+      # headers are merged into the response. Per-call extras advertise no Vary,
+      # so — exactly like a Vary-less etag_with source — they make this
+      # response `private` (see http_cache_visibility_for).
       def set_cache_validators(resource = nil, etag: nil, last_modified: nil, extras: nil)
         etag ||= cache_etag_for(resource) unless resource.nil?
         last_modified ||= cache_last_modified_for(resource) unless resource.nil?
+        http_cache_note_request_extras(extras)
         context = cache_etag_extras(extras)
         etag = http_cache_combine_etag(etag, context) if etag && context.any?
         http_cache_write_validators(etag, last_modified)
@@ -378,7 +382,10 @@ module ConcernsOnRails
       # `vary: false` — is a dimension no cache can key on (`Vary` has no way to
       # say "who is asking"), so the representation is simply not shareable and
       # the declared `visibility:` is downgraded rather than trusted. `:query`
-      # is exempt: the query string is already part of the cache key.
+      # is exempt: the query string is already part of the cache key. Per-call
+      # `extras:` (`stale_resource?(r, extras: [current_user.role])`) are the
+      # same kind of dimension and used to keep `public`, so a CDN keyed on the
+      # URL handed one caller's representation to the next.
       def http_cache_visibility_for(rule)
         return "private" if http_cache_unshareable_etag?
 
@@ -386,9 +393,17 @@ module ConcernsOnRails
       end
 
       def http_cache_unshareable_etag?
+        return true if @http_cache_request_extras
+
         self.class.cacheable_etag_extras.any? { |entry| entry[:vary].empty? && entry[:source] != :query }
       end
 
+      # Any per-call extra counts, a nil one included — just as a block source
+      # downgrades whatever it returns: the dimension exists either way.
+      def http_cache_note_request_extras(extras)
+        @http_cache_request_extras = true unless Array(extras).empty?
+      end
+
       # Previously a hand-rolled, case-SENSITIVE merge that also appended to
       # `Vary: *` — and, run from set_cache_validators before render, it left
       # the header non-blank so Rails skipped its own `Vary: Accept`.

data/lib/concerns_on_rails/controllers/cursor_paginatable.rb

@@ -558,11 +558,15 @@ module ConcernsOnRails
       # redefined #is_a? returns true for Time). iso8601(6) keeps microsecond
       # precision so boundary equality survives the round trip. The UTC form is
       # a copy: `to_time.utc` converted the boundary record's own attribute in
-      # place (TimeWithZone#to_time is memoized).
+      # place (TimeWithZone#to_time is memoized). A non-finite Float — a
+      # stored ±Infinity or NaN (see cursor_non_finite_minted?) — is written
+      # as the String ActiveModel's Float type casts back ("Infinity",
+      # "-Infinity", "NaN"): JSON has no such number, and JSON.generate raised
+      # on it, so one such row on a page boundary made that page a 500.
       def serialize_cursor_value(value)
         return ConcernsOnRails::Support::TimeValue.utc(value).iso8601(6) if value.is_a?(Time) || value.is_a?(DateTime)
         return value.iso8601 if value.is_a?(Date)
-        return value.to_s if value.is_a?(BigDecimal)
+        return value.to_s if value.is_a?(BigDecimal) || (value.is_a?(Float) && !value.finite?)
 
         value
       end
@@ -596,24 +600,38 @@ module ConcernsOnRails
       # drops unboundable values to 1=0) and a RangeError 500 on 6.0. A
       # timestamp outside years 0001..9999 casts fine too, then raised
       # DatetimeFieldOverflow on PostgreSQL (a 500) and compared as text on
-      # SQLite. We never mint any of them, so each is tampering and gets the
+      # SQLite. So did a number or `true` for a datetime boundary: the date
+      # and time casts hand a non-String back unchanged, and
+      # `(created_at, id) > (12345, 3)` restarted the walk on SQLite (it sorts
+      # any number before a date's text) and was a 500 on PostgreSQL. We
+      # never mint any of them, so each is tampering and gets the
       # InvalidCursor 400.
       def cast_cursor_value!(model, col, raw)
         return nil if raw.nil? # a NULL boundary; valid_cursor_values? only admits it on a nullable column
 
         type = model.type_for_attribute(col.to_s)
-        value = type.cast(raw)
-        raise InvalidCursor, "Invalid pagination cursor." unless cursor_bindable?(type, value)
+        value = cursor_type_cast(type, raw)
+        raise InvalidCursor, "Invalid pagination cursor." unless cursor_bindable?(model, type, value)
 
         value
       end
 
+      # Rails 6.0–7.0's date and time casts raise Date._parse's ArgumentError
+      # for a String over 128 characters (7.1 casts it to nil): a tampered
+      # date boundary was a 500 instead of the 400 below. Any other type's
+      # ArgumentError is left alone.
+      def cursor_type_cast(type, raw)
+        type.cast(raw)
+      rescue ArgumentError
+        raise unless ConcernsOnRails::Support::TimeValue.temporal_type?(type)
+
+        raise InvalidCursor, "Invalid pagination cursor."
+      end
+
       # `serializable?` is the Rails 6.1+ range probe; on 6.0 only serialize
-      # itself knows, raising ActiveModel::RangeError (a ::RangeError). A
-      # non-finite Float/BigDecimal is refused outright: it is never minted
-      # and adapters disagree on how (or whether) to quote it.
-      def cursor_bindable?(type, value)
-        return false if cursor_never_minted?(value)
+      # itself knows, raising ActiveModel::RangeError (a ::RangeError).
+      def cursor_bindable?(model, type, value)
+        return false if cursor_never_minted?(model, type, value)
         return type.serializable?(value) if type.respond_to?(:serializable?)
 
         type.serialize(value)
@@ -622,12 +640,37 @@ module ConcernsOnRails
         false
       end
 
-      # nil, a non-finite Float/BigDecimal, or a date/time outside
-      # Support::TimeValue::YEARS: none of them is ever minted.
-      def cursor_never_minted?(value)
-        value.nil? ||
-          ((value.is_a?(Float) || value.is_a?(BigDecimal)) && !value.finite?) ||
-          !ConcernsOnRails::Support::TimeValue.representable?(value)
+      # nil, a non-finite Float/BigDecimal (except where one is minted, see
+      # cursor_non_finite_minted?), anything but a date or time on a date/time
+      # column, or a date/time outside Support::TimeValue::YEARS: none of them
+      # is ever minted.
+      def cursor_never_minted?(model, type, value)
+        return true if value.nil?
+        return !cursor_non_finite_minted?(model, type, value) if value.is_a?(Float) && !value.finite?
+        return true if value.is_a?(BigDecimal) && !value.finite?
+
+        !cursor_time_minted?(type, value)
+      end
+
+      # A date/time column's boundary is a date or time, and any date or time
+      # lies within Support::TimeValue::YEARS.
+      def cursor_time_minted?(type, value)
+        time_value = ConcernsOnRails::Support::TimeValue
+        return false if time_value.temporal_type?(type) && !time_value.temporal?(value)
+
+        time_value.representable?(value)
+      end
+
+      # A float column can hold a non-finite boundary on PostgreSQL (±Infinity
+      # and NaN) and SQLite (±Infinity; it stores NaN as NULL). Anywhere else
+      # — another column type, NaN on SQLite, MySQL, which stores none — it is
+      # tampering, and refused outright: adapters disagree on how (or
+      # whether) to quote one.
+      def cursor_non_finite_minted?(model, type, value)
+        return false unless type.type == :float
+
+        adapter = model.connection.adapter_name
+        adapter.match?(/postgres/i) || (adapter.match?(/sqlite/i) && !value.nan?)
       end
 
       # Pre-bidirectional cursors carry no "d" — they are forward cursors and
@@ -702,6 +745,7 @@ module ConcernsOnRails
       # tuple cannot say "NULLs last" (`(c, id) > (v, x)` is never TRUE for a
       # NULL c), so :auto AND an explicit :row fall back to it.
       def cursor_predicate(model, pairs, values, nullable: [], backward: false)
+        values = values.map { |value| cursor_sql_value(model, value) }
         if nullable.empty? && cursor_row_predicate?(model, pairs)
           cursor_row_predicate(model, pairs, values)
         else
@@ -709,6 +753,19 @@ module ConcernsOnRails
         end
       end
 
+      # A boundary as the WHERE binds it. Only an infinite float on SQLite
+      # differs: SQLite reads no quoted literal as infinity — Rails before 7.2
+      # quote Float::INFINITY as the bare word Infinity (no such column, a
+      # 500), later ones as the TEXT 'Infinity', which SQLite sorts after
+      # every number, so the boundary row matched again and the walk never
+      # ended — but it reads a literal past the largest double as one.
+      # PostgreSQL reads its quoted 'Infinity' / 'NaN' as float8.
+      def cursor_sql_value(model, value)
+        return value unless value.is_a?(Float) && value.infinite? && model.connection.adapter_name.match?(/sqlite/i)
+
+        Arel.sql(value.positive? ? "9e999" : "-9e999")
+      end
+
       # :auto picks :row when it is expressible (>= 2 uniform-direction
       # columns) and the adapter supports tuples, silently falling back
       # otherwise; an explicit :row raises on mixed directions instead of