concerns_on_rails 1.33.0 → 1.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dd550c226626fbbe5d8c542b5e139296be95977722dd1e78560f81ed91c63b1
-  data.tar.gz: f8770b8fe33e57b5323a76a469e8cd2cac66401a6e20a3b12a800b99776c80f4
+  metadata.gz: 9acfbd10f8e27c5a4535a3486fec52255d7d5e997e3b7654547e864802bdcf58
+  data.tar.gz: 31701400ec820ac47a7cd26e8b68579dab0fba3d43bd1d8cea87b63c60f244ce
 SHA512:
-  metadata.gz: aeec3000adc45a218468a6be90ed35ed8022f9319f3c41a222dcdeb0e048eb95f634c5e9d4a4613ad0cbdde7558d9e24d94f132c6c664622fd48393e26ff78ad
-  data.tar.gz: eca60a294934ecb578df643c92108a0b86ed62c1f0bd5f63c376ae12691d51ce3e6e7bce37438c896f9872c228de077950982a9c3ae53f674f83a4b10fa1ba22
+  metadata.gz: 0fc6561854bcdb26fbbae74b6f9b623bd9af28b240b313f56dcaa5c40da9c03726db39908e2b6ddb6af67d326fdd1f597c4ec81d31fc951711753320f44cf533
+  data.tar.gz: 4471742ad951b6b0dfd9998c93c43ba2e6627d44e5d6b94c0e48c366dcd5732f0c51b5df7886d3d88f0c6a71cf63a33f1a6695adfa1bf8292b8d51eb91d49609

data/CHANGELOG.md

@@ -1,5 +1,278 @@
 <!-- CHANGELOG.md -->
 
+## 1.34.0 (2026-10-29)
+
+A correctness release: it fixes the 43 bugs proven by the 2026-10-29 audit of 1.33.0. Some fixes change behaviour,
+and five configurations that used to be silently broken now raise at class load. Read **Upgrading** first.
+
+### Upgrading
+
+**Class-load (boot) raises for configurations that were silently broken.**
+
+- [ ] **CounterCacheable, composite keys:** `counter_cacheable_by` raises `ArgumentError` for a `belongs_to` with a
+  composite `foreign_key:` (`[:shop_id, :order_id]`), a composite association primary key or `query_constraints:`
+  (Rails 7.1+), as it does for a polymorphic one. It was accepted, never counted the children and made
+  `recount_counter_caches!` raise invalid SQL. Count on a single-column key instead. A model-level
+  `query_constraints` must be declared before `counter_cacheable_by`. (GRAPH-2)
+- [ ] **CursorPaginatable, `predicate: :row`:** `predicate: :row` with a mixed-direction `order:` or `order_presets:`
+  entry raises `ArgumentError` at class load (also when a later re-declaration combines with an inherited one), and a
+  per-call `cursor_paginated(order:)` with mixed directions raises before page 1. This includes a nullable ordering
+  column, which used to fall back to the OR-expansion silently. Switch to `predicate: :auto` (it falls back to the
+  OR-expansion for mixed directions) or make the directions uniform. (PARAMS-4)
+- [ ] **Stateable, event named `transition`:** a transition event whose (affixed) name is `transition` raises
+  `ArgumentError` at the macro. It generated a `transition!` that always raised from the generic
+  `before_/after_transition` hooks. Rename the event or use `prefix:`/`suffix:`. (STATE-6)
+- [ ] **Authorizable, `require_role`:** `require_role` with an empty list (`require_role []`, `[[]]`) or a nil/blank
+  role (`require_role ENV["ADMIN_ROLE"]&.to_sym` unset) raises `ArgumentError` at class load; a blank role used to
+  admit actors whose role is `""` or nil. (HTTP-2)
+- [ ] **Encryptable, per-field `key:`:** a DECLARED per-field `key:` that resolves to nil or `""` (a Proc over a
+  credential that is not there yet, an explicit `key: nil`, an eagerly nil `ENV["X"]` / credential) is a missing key:
+  it raises `MissingKeyError` naming the field on write, read and blind-index lookup (or leaves the value plaintext
+  under `on_missing_key: :passthrough`) instead of silently encrypting under the global key. Only an OMITTED `key:`
+  uses the gem-level key. `key:` must be a String or respond to `call`; `key: false`, `key: 123` or `key: :sym` raises
+  `ArgumentError` at the macro. Rows already written under the global key are NOT repaired by `reencrypt_all!`
+  (it skips per-field fields); they fail to decrypt under the field key. For each such row, decrypt the raw column
+  value with the global key (`ConcernsOnRails::Support::Encryptor.decrypt(raw, key: <global key material>,
+  salt: ConcernsOnRails.encryption.key_derivation_salt)`; read `raw` with `<field>_ciphertext`, since the model's
+  reader raises for such rows), then write the plaintext back through the model while the field key resolves, so it
+  is re-sealed under the field key.
+  Rows left plaintext under `:passthrough` only need a plain re-save once the key resolves. (DATA-2)
+
+**Behaviour changes.**
+
+- [ ] **Normalizable / Sanitizable / Taggable / Addressable:** Normalizable no longer re-normalizes a later transform's
+  output at `before_save`, so with Normalizable included BEFORE a Sanitizable/Taggable/Addressable rule on the same
+  column its rule no longer gets "the last word" (`squish` then `strip` on: :write stores `" a  b"` where it stored
+  `"a b"`). Include Normalizable AFTER the other transform to normalize its output. (TRANS-2)
+- [ ] **Taggable:** with a self-overlapping delimiter (`"--"`, `"||"`, `" | "`) a tag is trimmed of a trailing part
+  that is the start of the delimiter, and of a leading part that is the end of it: `"a-"` becomes `"a"` and `"-b"`
+  becomes `"b"` under `"--"`. Delimiters that do not overlap themselves are unaffected. Stored tags with a leading
+  straddling part are not migrated; `Model.normalize_tags!` repairs them. (TRANS-4)
+- [ ] **Paginatable / Includable:** re-declaring `paginate_by` or `includable` in a subclass changes only what it
+  passes; every omitted option now keeps its inherited value (before it reset to the gem default, for example a
+  parent `max_per_page: 20` became 200). A subclass that relied on the reset must pass the option explicitly.
+  For `includable` the association list still replaces the parent's, and an inherited `default:` path the new list no
+  longer contains is dropped with a stderr warning at class load. (PARAMS-2)
+- [ ] **Filterable, `_null`:** `?<field>_null=` and `?field[null]=` read only `true/false/1/0/t/f/yes/no`
+  (case-insensitive) or a real boolean; any other NON-BLANK value (`maybe`, `on`, `off`, `nope`) matches nothing
+  instead of being read as `IS NULL` (`off` used to be `IS NOT NULL`). A blank value is skipped as before, and
+  surrounding whitespace is ignored. (PARAMS-6)
+- [ ] **Filterable, encrypted columns:** on an `encryptable` column equality and `in` go through the blind index and every
+  other operator (`not`, `not_in`, `gt`, `gte`, `lt`, `lte`, `contains`, `starts_with`) fails closed (`none`); a field
+  without a blind index fails closed for every operator but `null`. Add `blind_index: true` to filter an encrypted
+  field by equality. (PARAMS-1)
+- [ ] **Filterable, `with:` lambdas:** a lambda declared with a `type:` receives no Array/Hash/Parameters value; such a
+  value fails the filter closed (`none`) for every `type:`. (PARAMS-S4)
+- [ ] **Filterable, float columns:** a decimal literal that a double does not read back as (more digits than a Float
+  keeps, e.g. `0.1000000000000000000001`) equals nothing and compares as the largest double at or below it. (PARAMS-8)
+- [ ] **Paginatable / CursorPaginatable, `page` / `per_page`:** read as exact whole numbers (`1e3` is 1000, `2e0` is 2);
+  a fractional (`2.9`), trailing-garbage (`10abc`) or unreadable value falls back to the default instead of its
+  leading digits, and a value beyond 100 digits falls back to the default instead of clamping. (PARAMS-7)
+- [ ] **CursorPaginatable, SQLite:** a hand-made cursor whose String boundary carries a NUL byte is accepted on SQLite
+  (it cannot be told from a minted one) instead of answering `InvalidCursor`. (PARAMS-5)
+- [ ] **Publishable:** `unpublish!` on a stored draft (blank saved column; false/NULL on a boolean) is a no-op like
+  `publish!`: it returns `true`, writes nothing and fires no `before/after_unpublish`. A scheduled row is still
+  cleared with the hooks. (STATE-5)
+- [ ] **SoftDeletable:** `soft_delete!`/`restore!` decide "already done" from the SAVED stamp. Assigning the stamp
+  without saving no longer makes the verb return `true` while writing nothing: it writes, fires the hooks and cascades.
+  A no-op verb now saves OTHER pending changes (previously dropped; a validation can make it return `false`). (STATE-12)
+- [ ] **Expirable:** `expire_in!(nil)` and `extend_expiry!(by: nil)` (anything but an `ActiveSupport::Duration` or a
+  `Numeric`) raise the concern's `ArgumentError` instead of a bare `TypeError`; an object that merely responds to
+  `to_i` is refused too. (STATE-10)
+- [ ] **Expirable, `date` columns:** `expire_in!(15.minutes)` on a `date` column writes today's date, so it now fires the
+  hooks, because the record is `expired?` (unchanged for UTC process zones). (STATE-2)
+- [ ] **Anonymizable:** `anonymize!` returns `false` (no `after_anonymize`) when its UPDATE reached no row, and
+  `anonymize_all!` no longer counts such a row. (STATE-9)
+- [ ] **Lockable:** `register_failed_attempt!` on a `readonly!` or destroyed record raises before incrementing, so
+  nothing is written; an already-locked record still just answers the count. (DATA-4)
+- [ ] **Monetizable:** the writer casts an amount the cents column cannot hold to `nil`, like other oversized input
+  (a 4-byte integer column overflows at about 21.4 million units). (TRANS-S3)
+- [ ] **Authorizable:** the default denial `message:` follows the status: 404 renders ErrorHandleable's exact
+  "Resource not found", 401 "Unauthorized", anything else "Forbidden". A `status: :not_found` / `:unauthorized` rule
+  without `message:` changes its body message and the `authorization_denied` payload's `message`; an explicit
+  `message:` still wins. (HTTP-1)
+- [ ] **Authorizable, `require_role`:** Array arguments are flattened, so `require_role %i[admin editor]` and
+  `require_role ADMIN_ROLES` work (they used to deny everyone). (HTTP-2)
+- [ ] **Timezoneable:** responses gain `Vary: Time-Zone` whenever the `Time-Zone` header source is on (default; no longer
+  only with `response_header:`) and `Vary: Cookie` whenever the cookie source is on. New `vary:` option (default
+  true; `vary: false` opts out). `response_header:` now controls only `X-Time-Zone`. (HTTP-3)
+- [ ] **ErrorHandleable:** the RecordNotDestroyed 422 renders "Resource could not be deleted" instead of Rails'
+  "Failed to destroy <Model> with id=<id>"; the record's `errors.full_messages` still ride as `details`. The
+  `message` of that 422 and of the `handled_error` payload changed. (HTTP-4)
+- [ ] **Respondable / ErrorEnvelope, status symbols:** on Rack >= 3.1 without Rails 8.1's own rewrite (Rails
+  7.1/7.2/8.0) the gem renders the renamed symbol (`:unprocessable_content`, ...), so `rendered[:status]` is Rack
+  dependent; specs asserting `:unprocessable_entity` should compare to `ErrorEnvelope.renderable_status(:unprocessable_entity)`.
+  An app's OWN `render_error` override still receives the raw `:unprocessable_entity`; one that calls `render` with
+  it logs Rack's deprecation on Rack >= 3.1. (HTTP-5)
+- [ ] **SecureHeadable, `:hsts`:** the `:hsts` preset is skipped when `Rails.application.config.force_ssl` is on (read
+  per request), so Rails' own HSTS (`config.ssl_options[:hsts]`) is no longer overridden by the preset's one-year
+  value. A custom `"Strict-Transport-Security"` pair with a different value is still sent. (HTTP-6)
+- [ ] **SecureHeadable, header names:** names compare case-insensitively: a lower-case custom
+  `"strict-transport-security"` is withheld over plain HTTP, and a lower-case pair beside a preset
+  (`"x-frame-options"` + `:deny_frame`) is ONE header (later value wins, first-registered spelling kept), written
+  under the spelling the response already carries. (HTTP-7)
+- [ ] **SoftDeletable:** after an association `destroy_all` the association cache is reset rather than marked
+  loaded-and-empty, so a `default_scope: false` / `-> { with_deleted }` association still shows its soft-deleted rows
+  on the next read (and `size`); one extra query on the next read. (STATE-4)
+- [ ] **Batch verbs, partial `select`:** every `*_all` verb and a SoftDeletable relation `destroy_all` over a relation
+  with a partial `select` load whole rows (`table.*` is added; computed aliases a HAVING/ORDER reads stay; joins and
+  wheres kept) instead of raising `MissingAttributeError`. Accepted limits: a joined-table column, a Rails 7.1+ Hash
+  select or a comma-joined String repeating a column beside the star can still repeat `id` in the DISTINCT key
+  subquery on PostgreSQL/MySQL; a direct `BatchOps.each_record` caller selecting without the primary key still
+  gets nil ids. (STATE-7)
+- [ ] **Stateable, `transition_all`:** a record failing validation raises `ActiveRecord::RecordNotSaved` (carrying the
+  record; batch rolled back as before) instead of `RecordInvalid`; rescue `RecordNotSaved`. Another record's failed
+  `save!` inside a hook still propagates as `RecordInvalid`. The single `<event>!` still raises `RecordInvalid`.
+  (STATE-8)
+- [ ] **Sequenceable, `period_column:`:** a row numbered before a switch to a custom `period_column:` (NULL there)
+  formats (`formatted_<field>`, `sequenceable_period_time`) in its `created_at` period instead of today's. (GRAPH-1)
+- [ ] **Sluggable, `history: true` + `scope:`:** moving a record into a scope where another record's friendly_id history
+  holds its slug regenerates the slug (it raised `RecordNotUnique` or took over the old URL). (GRAPH-5)
+- [ ] **Duplicable:** a child or has_one target marked for destruction (`_destroy`, `mark_for_destruction`) is no longer
+  copied. (GRAPH-6)
+- [ ] **Legacy aliases:** a racing first reference to a top-level alias (`ConcernsOnRails::Sluggable`) no longer prints
+  "already initialized constant". (GRAPH-4)
+
+
+### Fixed
+
+- **Lockable**: `register_failed_attempt!`, `lock_access!`, `unlock_by_token`, the lapsed-lock clear and the lost-claim
+  adoption read no longer raise `ArgumentError` on a composite primary key (Rails 7.1+); every site addresses its row
+  through `Support::PrimaryKey`. (DATA-1)
+- **Tokenizable**: `consume_<field>` no longer raises `ArgumentError` on a composite primary key. (DATA-1)
+- **Lockable**: `register_failed_attempt!` on a `readonly!` (or destroyed) record raises `ReadOnlyRecord` /
+  `ActiveRecordError` before incrementing; it used to increment in SQL and then raise from `lock_access!`, leaving the
+  row at max attempts and unlocked. (DATA-4)
+- **Tokenizable / Lockable**: `authenticate_by_<field>` / `consume_<field>` and `unlock_by_token` answer `nil`, without
+  a query, for a token holding a NUL byte (`?token=%00`); on PostgreSQL they raised (the driver refuses NUL in a bound
+  parameter). Uses `Support::ScalarParam.nul_free?` like Filterable. (DATA-3)
+- **Encryptable**: a per-field `key:` that resolves to nil or `""` (a Proc over a missing credential, an explicit
+  `key: nil`, an eagerly nil `ENV[...]`) no longer falls back to the global key. It raises `MissingKeyError` naming
+  the field on write, read and blind-index lookup/refresh, or stays plaintext under `on_missing_key: :passthrough`;
+  `key:` must be a String or callable (`ArgumentError` otherwise). It used to seal a key_id-0 envelope under the
+  global key that the field key could not decrypt later. (DATA-2)
+- **Authorizable**: the default denial `message:` follows the status (404 "Resource not found", 401 "Unauthorized",
+  else "Forbidden"), so a 404 denial is no longer distinguishable from ErrorHandleable's own 404. (HTTP-1)
+- **Authorizable**: `require_role` flattens Array arguments (`require_role %i[admin editor]` used to deny everyone) and
+  refuses an empty list or a nil/blank role at class load. (HTTP-2)
+- **SecureHeadable**: the `:hsts` preset is skipped under `config.force_ssl`, so it no longer overrides Rails' own HSTS
+  header. (HTTP-6)
+- **SecureHeadable**: header names compare case-insensitively, so a lower-case custom pair beside a preset (or Rails'
+  default `X-Frame-Options` on Rails < 7.1) is one header, not two conflicting ones. (HTTP-7)
+- **SoftDeletable**: `really_delete!`, `is_really_deleted?` and the trashed-row purge guard no longer raise on a
+  composite primary key. (STATE-3)
+- **SoftDeletable**: `soft_delete!`/`restore!` read the SAVED stamp instead of the unsaved in-memory one; they used to
+  return `true` while writing nothing (no hooks, no cascade) after the stamp was assigned unsaved. `restore!` cascades
+  by the saved stamp. (STATE-12)
+- **Sortable**: `reposition!` works on a composite primary key (Rails 7.1+). Ids are `[shop_id, id]` tuples (a record
+  is accepted too), cast per column and written one UPDATE each inside the transaction; a malformed tuple raises
+  `ArgumentError` before any write. A simple key keeps the single CASE UPDATE. It raised `TypeError: can't quote
+  Array`. (GRAPH-3)
+- **CounterCacheable**: a composite-key `belongs_to` is refused at the macro (see Upgrading); it was accepted and never
+  counted. (GRAPH-2)
+- **Expirable**: `time_until_expiry` no longer raises `TypeError` on a `date` column with a future date. It agrees with
+  `expired?` (0 when expired, today counts, in `Time.zone`), otherwise measures to the start of the date in
+  `Time.zone`, and is clamped at 0. Also fixes today's date in a zone ahead of UTC answering a positive duration
+  while `expired?` was true. (STATE-1)
+- **Expirable**: `expire!` / `expire_in!` on a `date` column fire `before/after_expire` exactly when the written value
+  makes the record `expired?`, whatever the process TZ (`Date#to_time` used `ENV["TZ"]` and skipped the hooks for
+  hours a day). A blank time (`nil`, `""`, `false`) for `expire!`/`expire_all` is cast through the column like a given
+  time (today's `Date` on a `date` column; `expire_all(nil)` writes it). (STATE-2)
+- **Expirable**: `expire_in!(nil)` and `extend_expiry!(by: nil)` raise the concern's `ArgumentError`
+  (shared `expirable_check_duration!`). (STATE-10)
+- **Publishable**: `unpublish!` on a draft is idempotent like `publish!`; `unpublish_all` already skipped such rows, so
+  verb and batch now agree. (STATE-5)
+- **Anonymizable**: the erasing UPDATE's result is honoured; a row deleted (or unwritable under optimistic locking)
+  between load and UPDATE is not counted, and `anonymize!` returns `false` instead of raising from the reload.
+  (STATE-9)
+- **HookedWrite** (every hooked verb: `publish!`, `activate!`, `expire!`, `soft_delete!`, Stateable `<event>!`, ...): a
+  veto on a NEW record inside a caller's transaction left it `persisted?` with no id; the next `save` ran
+  `UPDATE ... WHERE id IS NULL`, returned `true` and wrote no row (`StaleObjectError` with `lock_version`). The
+  identity (`new_record?`, `destroyed?`, `previously_new_record?`, id) is now snapshotted and restored for new records
+  too. Rails 6.0 never showed the bug; 6.1 through 8.1 did. (STATE-11)
+- **Storable / Auditable**: a PostgreSQL `jsonb` column and an `attribute :x, :json` override over a text column are
+  handed the Hash/Array instead of a JSON string scalar, so `where_<key>(v)` matches and `where_<key>(nil)` no longer
+  matches every row. One shared `Support::NativeJson.column?` backs both. (TRANS-1)
+- **Normalizable**: no longer re-normalizes a later transform's output at `before_save`: `normalizable :title, with:
+  :titleize` plus `sanitizable :title, with: :strip, on: :write` stored `"A &Lt; B"` for a validated `"A &lt; B"`, and
+  an entity-decoding rule could store live markup in a `:strip` column. Every transform records what it wrote
+  (`Support::TransformBackstop.wrote`) and the settle step skips a field still holding it. (TRANS-2)
+- **Normalizable / Sanitizable**: a save halted by a later `before_save` (or rolled back by `RecordNotUnique`), then
+  retried on the same record, no longer re-runs a non-idempotent rule on its own output (`"a!"` no longer becomes
+  `"a!!"`, `"Tom &amp; Jerry"` no longer `"Tom &amp;amp; Jerry"`), `update_attribute` saves included. The per-save
+  records are dropped after a successful save, kept across a rollback, and dup/clone no longer share them. (TRANS-3)
+- **Taggable**: a tag ending with the start of a self-overlapping delimiter, or starting with its end (`["a-", "b"]`
+  under `"--"` read back as `["a", "-b"]`), is trimmed when cleaned; `tag_list=`/`add_tags` clean an Array item by item instead of joining and
+  re-splitting. (TRANS-4)
+- **Monetizable**: `price = "1e18"` on an integer cents column casts to `nil` (checked against the column type's own
+  range) instead of a value whose save raised `ActiveModel::RangeError`. (TRANS-S3)
+- **Paginatable / Includable**: `paginate_by` and `includable` re-declared in a subclass keep every omitted option
+  (an UNSET sentinel, as `cursor_paginate_by`); `paginate_by style:` re-derives both param paths, explicit
+  `page_param:`/`per_page_param:` still win; `includable` `fields:`/`default:`/`strategy:` inherit when omitted
+  (`default: nil` / `fields: {}` clear them). (PARAMS-2)
+- **Paginatable**: a grouped relation with a `HAVING` on a select alias no longer raises `StatementInvalid`
+  (SQLite/MySQL); it is counted as a subquery that keeps its select list. A grouped relation with no `HAVING` or no
+  select list keeps the plain `COUNT ... GROUP BY`. (PARAMS-3)
+- **CursorPaginatable**: `predicate: :row` with mixed directions is refused at the macro (see Upgrading); page 1
+  minted a cursor and every page-2 request answered 500. (PARAMS-4)
+- **CursorPaginatable**: on SQLite a row whose String ordering value holds a NUL byte no longer ends the walk with a
+  400 on its own cursor; the boundary goes into the keyset WHERE as `CAST(X'<hex>' AS TEXT)`, which assumes a UTF-8
+  SQLite database (Rails' default). MySQL already accepted it; PostgreSQL still answers `InvalidCursor`. (PARAMS-5)
+- **Paginatable / CursorPaginatable**: `page` / `per_page` are read as exact whole numbers through
+  `Support::NumericOperand` instead of `String#to_i` (`?per_page=1e3` was 1, `?per_page=10abc` was 10); a non-whole
+  JSON Float falls back too. (PARAMS-7)
+- **Filterable**: `?<field>_null=` reads only an explicit true/false spelling; any other non-blank value matches
+  nothing (see Upgrading). (PARAMS-6)
+- **Filterable**: Encryptable-aware (`Support::EncryptedLookup.rule`), `alias_attribute` followed: equality and `in` use
+  the blind index, `not`/`not_in`/`gt`/`gte`/`lt`/`lte`/`contains`/`starts_with` fail closed. `?ssn_not=123` used to
+  return the excluded row and `=`/`in`/`contains` silently matched nothing. `null` keeps working on an encrypted
+  column. A nil member of an Array operand is dropped. (PARAMS-1)
+- **Filterable**: a Float-column operand is no longer rounded to the nearest double and treated as exact;
+  `?score_gt=0.1000000000000000000001` keeps a stored 0.1. A literal the double keeps (`0.1`) stays exact. (PARAMS-8)
+- **Filterable**: a `with:` lambda declared with a `type:` fails closed on an Array/Hash/Parameters value instead of
+  receiving a cast one (`?flag[]=0` was `true`). (PARAMS-S4)
+- **Authorizable**: the default `message:` follows the denial status (404 "Resource not found", the shared
+  `Support::ErrorEnvelope::NOT_FOUND_MESSAGE`; 401 "Unauthorized"; else "Forbidden"), stored resolved at declaration so
+  the instrumentation payload carries it. `require_role` flattens its arguments and raises on an empty, nil or blank
+  role. (HTTP-1, HTTP-2)
+- **ErrorHandleable**: the RecordNotDestroyed 422 no longer leaks the model class name and primary key. (HTTP-4)
+- **Timezoneable**: `Vary: Time-Zone` / `Vary: Cookie` are appended (via `Support::VaryHeader`; `Vary: *` left alone)
+  even when the request carries no `Time-Zone` header; `vary: false` opts out. (HTTP-3)
+- **Respondable / ErrorEnvelope**: the envelope and inline branches no longer log "Status code :unprocessable_entity is
+  deprecated" on Rack >= 3.1; `ErrorEnvelope.renderable_status` renames only when the running Rack dropped the old
+  name (Rack < 3.1 keeps it). (HTTP-5)
+- **SecureHeadable**: `:hsts` yields to `force_ssl`; header names merge case-insensitively through
+  `SecureHeadable.merge_headers` (no more two conflicting `X-Frame-Options` lines on Rails < 7.1). (HTTP-6, HTTP-7)
+- **SoftDeletable**: association `destroy_all` resets the association cache instead of `loaded!`-empty. (STATE-4)
+- **BatchOps / SoftDeletable**: `BatchOps.full_rows(relation)` (used by `BatchOps.run` and the relation `destroy_all`)
+  adds the model's own star to a partial select; `limited_keys` keeps the own-table star first and drops only plain
+  own-table columns from a DISTINCT key subquery. (STATE-7)
+- **Stateable**: an event named `transition` is refused at the macro (STATE-6); `transition_all` raises
+  `RecordNotSaved` for its own invalid record and propagates another record's `RecordInvalid` (STATE-8).
+- **Sequenceable**: legacy rows (NULL custom `period_column:`) format in their `created_at` period; `period_time` /
+  `base_time` take the field. (GRAPH-1)
+- **Sluggable**: a `history: true` + `scope:` move treats another record's history slug in the new scope as taken.
+  (GRAPH-5)
+- **Duplicable**: records marked for destruction are skipped, loaded or not, has_one included. (GRAPH-6)
+- **Legacy aliases**: `const_missing` resolution is serialized by a reentrant Monitor. (GRAPH-4)
+
+
+### 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.
+- Normalizable / Sanitizable: on an unvalidated (`update_attribute`) save that is halted and retried, with TWO
+  transforms on one column where the SECOND (not Normalizable) rewrites the first's output, Sanitizable's own record
+  holds only the first's output, so a validated retry re-sanitizes.
+- Sluggable `history: true` + `scope:`: friendly_id's history finder ignores scope, so after a record moves scope its
+  stale history slug can still match `Model.where(scope).friendly.find(old_slug)`. This is stock friendly_id
+  behaviour; the gem does not change it. (GRAPH-5)
+
+
 ## 1.33.0 (2026-10-18)
 
 A correctness release: it fixes the 66 bugs proven by the 2026-10 audit of 1.32.1. Some fixes change

data/README.md

@@ -327,6 +327,7 @@ Post.find("hello-world")   # resolves by slug
 - Clearing the source (`update!(title: nil)`, `""`, or a value that normalizes to nothing such as `"!!!"`) keeps the existing slug instead of replacing it with a random uuid; the uuid fallback only applies when there is no slug yet.
 - **Order-independent source.** A sibling that transforms the source in `before_validation` — [Sanitizable](#-sanitizable) `on: :write`, [Normalizable](#-normalizable), your own callback — no longer loses to include order: a slug built earlier in the same save from the raw value (`"<b>Hello</b>"` → `"b-hello-b"`) is rebuilt at the start of validation, before any validator (`reserved_words:` too) or sibling `before_save` sees it. A slug sourced from a column generated in `before_create` ([Sequenceable](#-sequenceable)'s `into:`, a [Hashable](#-hashable) code) is built in the same `INSERT` instead of staying `nil` until a later save — with the slug column's own write-mode Sanitizable / Normalizable rules applied, since their callbacks have already run. An explicitly assigned slug still wins.
 - Falls back to `to_s` if the configured source field doesn't respond.
+- With `history: true` + `scope:`, moving a record into a scope where another record's friendly_id history holds its slug regenerates the slug. friendly_id's own history finder is not scope-aware, so a mover's stale history row can still match the old slug in the new scope's relation (stock friendly_id behaviour).
 - Uses friendly_id's `:slugged` (+ optionally `:history`, `:scoped`) strategies under the hood.
 
 ---
@@ -364,7 +365,7 @@ sortable_by :position, add_new_at: :top          # new rows insert at the top (a
 **Notes**
 - The configured field must exist as a column; a direction other than `:asc` / `:desc` raises at declaration.
 - `scope:` can't be an [Encryptable](#-encryptable) column (a Symbol — resolved as acts_as_list does, so `scope: :list` means `list_id` or the association's foreign key — an Array entry or a fixed-value Hash key): acts_as_list's scope query would compare ciphertext, match no row and leave every record alone in its list (each new one at position 1, `move_*` a no-op), so the declaration raises `ArgumentError`, in either order. A String SQL scope is not inspected.
-- `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).
+- `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). On a composite primary key (Rails 7.1+) the ids are `[shop_id, id]` tuples (a record is accepted too) and each row is written with its own UPDATE inside the transaction; a malformed tuple raises `ArgumentError` before any write.
 
 ---
 
@@ -384,7 +385,7 @@ article.published?      # => false
 article.publish!
 article.published?      # => true
 article.publish!        # already published (saved state): a no-op (true), keeps published_at, no hooks
-article.unpublish!
+article.unpublish!      # a draft (blank saved column): a no-op (true), no hooks; a scheduled row is still cleared
 
 Article.published       # WHERE published_at <= NOW()
 Article.unpublished     # WHERE published_at IS NULL OR published_at > NOW()
@@ -484,6 +485,8 @@ Passing `true` for a scope- or accessor-name affix means "use the configured fie
 Unrelated to all three: Searchable's `match: :prefix` is a LIKE-match mode (`term%`), not a
 naming affix.
 
+`unpublish!` mirrors `publish!`: on a stored record with no unsaved change to the column and a blank saved value (a draft; `false`/`NULL` on a boolean) it is a no-op — `true`, nothing written, no `before/after_unpublish` (other pending changes are saved); a published or scheduled row still writes with the hooks.
+
 **Lifecycle hooks** — override `before_publish` / `after_publish` / `before_unpublish` /
 `after_unpublish`. They and the write share their own savepoint, so a hook that raises — or
 vetoes with `raise ActiveRecord::Rollback` — undoes the write: `publish!` / `unpublish!` /
@@ -518,6 +521,8 @@ user.soft_delete!
 user.deleted?              # => true
 user.restore!
 user.deleted?              # => false
+# soft_delete!/restore! are no-ops only on the SAVED state (stored, stamp unchanged, saved stamp already in the target
+# state; other pending changes are saved); an unsaved stamp assignment is written, with hooks and cascade
 
 user.really_delete!        # bypasses callbacks, hard deletes from DB; the instance is then destroyed? (not persisted?)
 ```
@@ -993,7 +998,7 @@ User.find_by(email: User.normalize(:email, params[:email]))
 | `:url`          | strip, default scheme to `https://` (`host:port` counts as schemeless; a protocol-relative `//CDN.example.com/x` becomes `https://cdn.example.com/x`), lowercase scheme + host, keep userinfo/path/query, drop a redundant default port. Only `http`/`https` are canonicalized — any other scheme (`mailto:`, `tel:`, `javascript:`, `data:`) and unparseable input come back stripped for your format validator to reject |
 
 **Notes**
-- Runs in `before_validation`, so DB constraints and AR validations see the normalized value — with a `before_save` backstop for saves that skip validation (`update_attribute`, `save(validate: false)`); `update_column(s)`/`update_all` bypass it. A rule runs once per save, even a non-idempotent Proc under `save if valid?` (the second validation skips a field still holding what the first left, also after a Sanitizable `on: :write` rule rewrote it; `reload` forgets the earlier validation). The backstop is prepended to the save callbacks, so a sibling's `before_save` (Addressable's fingerprint) sees the normalized value whichever concern was included first; Encryptable's blind index and Auditable's entry run later still, at the write boundary (`Support::WriteBoundary`). It is one shared dispatcher with the Sanitizable / Taggable / Addressable backstops, run in their `before_validation` order, so a save that skips validation stores the same value as a validated one when two of them transform the same column.
+- Runs in `before_validation`, so DB constraints and AR validations see the normalized value — with a `before_save` backstop for saves that skip validation (`update_attribute`, `save(validate: false)`); `update_column(s)`/`update_all` bypass it. A rule runs once per save, even a non-idempotent Proc under `save if valid?` (the second validation skips a field still holding what the first left, also after a Sanitizable `on: :write` rule rewrote it; `reload` forgets the earlier validation) and also when a save is halted or rolled back and retried on the same record. The `before_save` step never re-normalizes a sibling transform's output (Sanitizable `on: :write`, Taggable, Addressable): it normalizes only a field no transform handled or one rewritten by non-transform code (a slug built in a validate step), so include Normalizable AFTER another transform to normalize that transform's output. The backstop is prepended to the save callbacks, so a sibling's `before_save` (Addressable's fingerprint) sees the normalized value whichever concern was included first; Encryptable's blind index and Auditable's entry run later still, at the write boundary (`Support::WriteBoundary`). It is one shared dispatcher with the Sanitizable / Taggable / Addressable backstops, run in their `before_validation` order, so a save that skips validation stores the same value as a validated one when two of them transform the same column.
 - `with:` takes a preset, a Proc, or an Array of them (applied in order); every entry is validated at class load.
 - `nil` values are skipped — no `nil → ""` coercion (use `:nullify_blank` for the opposite direction).
 - Preset normalizers pass non-string values through unchanged.
@@ -1195,7 +1200,7 @@ Invoice.next_sequence(account_id: 1)   # => 4  (peek the next value, without cre
 | `start_at:`          | `1`         | First value when the scope/period has no rows yet.                                       |
 | `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`, or your `period_column:`). |
-| `period_column:`     | `:created_at` | Datetime column the `reset:` period is cut from. With `assign: :manual` set it to a stamp such as `:finalized_at` so a draft numbers into the period it is **finalized** in (`assign_<field>!` stamps it when blank); with the default a late-finalized draft numbers into its creation period. Not `:updated_at`. Declare it on the class that declares the format (or on an `assign:`-only re-declaration, which inherits it): a subclass restating the same format with a different `period_column:` is refused, since both series would print the same numbers. |
+| `period_column:`     | `:created_at` | Datetime column the `reset:` period is cut from. With `assign: :manual` set it to a stamp such as `:finalized_at` so a draft numbers into the period it is **finalized** in (`assign_<field>!` stamps it when blank); with the default a late-finalized draft numbers into its creation period. Not `:updated_at`. Declare it on the class that declares the format (or on an `assign:`-only re-declaration, which inherits it): a subclass restating the same format with a different `period_column:` is refused, since both series would print the same numbers. A row numbered before a switch (NULL there) also displays (`formatted_<field>`, `sequenceable_period_time`) in its `created_at` period. |
 | `time_zone:`         | app zone    | Zone the `reset:` periods are cut in (a zone name as a String or Symbol, or an `ActiveSupport::TimeZone`). Defaults to `config.time_zone` (`Time.zone_default`), else UTC — never the per-request `Time.zone`. Unknown names raise `ArgumentError`. |
 | `template:`          | `nil`       | `->(seq, record) { ... }` full custom formatter; overrides `prefix` / `padding` / period. To render the period, read `record.sequenceable_period_time(:field)` (the fixed-zone instant), not `created_at`. |
 | `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. Re-declaring the field (same class or an STI subclass) switches the mode; the last declaration wins. Pass only `assign:` to keep the rest of the config (see the notes). |
@@ -1287,7 +1292,7 @@ declaration: a base-class `transition_all` skips the rows of a subclass that re-
 `stateable_by` without the event (it used to abort with `NoMethodError`) and transitions the rows a
 subclass's wider `from:` accepts (the base's `from:` used to filter them out). With `lock: true` each record's guard is checked under its row
 lock, so a row another process moved after the batch loaded it is skipped like any other rejected row
-(it used to raise `InvalidTransition` and roll the whole batch back); a single `<event>!` still raises.
+(it used to raise `InvalidTransition` and roll the whole batch back); a single `<event>!` still raises. A record that fails validation raises `ActiveRecord::RecordNotSaved` (carrying the record; the batch rolls back) — not `RecordInvalid`, which only a single `<event>!` raises (another record's failed `save!` inside a hook still propagates as `RecordInvalid`).
 
 **Timestamps and per-event hooks**
 
@@ -1337,6 +1342,7 @@ stateable_by :state, states: %i[open closed], prefix: true
 - Re-declaring without `default:` keeps the earlier default while it is still one of the declared states; otherwise (or with an explicit `default: nil`) new records fall back to the column's database default.
 - Re-declaring replaces the generated methods too: the states, events and scopes the new declaration no longer lists are removed (hidden in an STI subclass, which keeps its parent's untouched), so a subclass with `states: %i[open closed]` no longer answers its parent's `archive!` or `.draft`. A method of such a name that the class defined itself is left alone.
 - No persistence of transition history; combine with `Publishable` / `Schedulable` for time-based state tracking.
+- An event whose (affixed) name is `transition` is refused at the macro (`ArgumentError`) — its `transition!` would collide with the generic `before_/after_transition` hooks; rename the event or use `prefix:`/`suffix:`.
 
 ---
 
@@ -1463,7 +1469,7 @@ Article.normalize_tags!                        # repair rows written around the
 
 | Option       | Default | Purpose                                                          |
 |--------------|---------|------------------------------------------------------------------|
-| `delimiter:` | `","`   | Character joining the stored tags (a tag must not contain it; an empty delimiter raises). |
+| `delimiter:` | `","`   | Character joining the stored tags (a tag must not contain it; an empty delimiter raises). A tag cannot start or end with part of a self-overlapping delimiter (`"--"`, `"||"`, `" \| "`): the part is dropped when the tag is cleaned (`"a-"` becomes `"a"` under `"--"`). |
 | `downcase:`  | `false` | Case-fold tags on write so matching is case-insensitive.          |
 
 **Notes**
@@ -1599,7 +1605,7 @@ product.formatted_price # => "$19.99"
 | Method            | Returns                                       |
 |-------------------|-----------------------------------------------|
 | `price`           | the amount as a `BigDecimal` (cents ÷ 100)    |
-| `price=`          | assign in major units; rounded to whole cents. Strings are read as plain decimals (`"19.99"`) or in the field's own display format (`"$1,234.50"`, `"€1.234,50"` with `separator: ","`), so `formatted_price` round-trips. The unit is only recognized at the start or end; in a `delimiter: "."` field with another separator, `"1.234"` means 1234 (like `"€1.234"`), but a leading `0` group is never grouping (`"0.500"` is 0.5 there, and `"0,500"` in a `","` field is `nil`, not 500). Garbage, NaN, Infinity and oversized input (over 64 characters, a 3-digit exponent, or ≥ 10^24 — a parse-cost bound, far above a `bigint` column's ~9.2e18 subunits, so the database may still reject a large amount at save) become `nil` |
+| `price=`          | assign in major units; rounded to whole cents. Strings are read as plain decimals (`"19.99"`) or in the field's own display format (`"$1,234.50"`, `"€1.234,50"` with `separator: ","`), so `formatted_price` round-trips. The unit is only recognized at the start or end; in a `delimiter: "."` field with another separator, `"1.234"` means 1234 (like `"€1.234"`), but a leading `0` group is never grouping (`"0.500"` is 0.5 there, and `"0,500"` in a `","` field is `nil`, not 500). Garbage, NaN, Infinity and oversized input (over 64 characters, a 3-digit exponent, or ≥ 10^24 — a parse-cost bound, far above a `bigint` column's ~9.2e18 subunits, and an amount past the cents column's integer range, checked against its type — a 4-byte column overflows at about 21.4 million units) become `nil` |
 | `formatted_price` | a display string (`"$1,234.56"`); accepts per-call overrides: `formatted_price(unit: "€", delimiter: ".", separator: ",")` |
 
 **Aggregates** — class methods that follow the current scope, exact and float-free:
@@ -1809,7 +1815,7 @@ Counters are adjusted with `update_counters` (a single atomic SQL `COALESCE(col,
 **Options** (`counter_cacheable_by association, …`, repeatable — re-declaring the same association + `count:` replaces that rule, e.g. an STI subclass narrowing it with `if:`): `count:` (the parent column; default `"<table_name>_count"`), `if:` (a callable evaluated against the record — counts only when truthy; the previous state is reconstructed for updates), `touch:` (`false`; also bump the parent's `updated_at`).
 
 **Notes**
-- The `belongs_to` must be declared **before** the macro (the reflection is validated at declaration). Polymorphic associations are not supported.
+- The `belongs_to` must be declared **before** the macro (the reflection is validated at declaration). Polymorphic associations and composite-key associations (a composite `foreign_key:`, association primary key or `query_constraints:`, Rails 7.1+) are not supported: the macro raises `ArgumentError` (a model-level `query_constraints` must be declared before `counter_cacheable_by`).
 - Don't also set native `counter_cache: true` on the same column — both would fire and double-count.
 - Counters track the **persisted** record; writes that skip callbacks (`update_column(s)`, `update_all`, `delete`) are not tracked — run `recount_counter_caches!` to reconcile. Bare, it rewrites every parent (portable across adapters, but O(n) for conditional counters) — a maintenance operation, run it offline. On an STI table every class's rows are tallied under that class's own rule for the column, so a repair from any class of the tree matches the live counts (types are resolved without instantiating a row; a stored type that no longer resolves counts under the base class's rule). With `parents:` it zeroes and re-tallies only those parents (O(their children)) in one transaction that locks those rows before tallying, so repairing one imported post is safe on the request path.
 - Reach for [`counter_culture`](https://github.com/magnusvk/counter_culture) when you need multi-level rollups, delta columns, or after-commit execution.
@@ -1838,7 +1844,7 @@ Patient.find_by_email("a@b.com")     # exact-match lookup via the blind index
 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`; a `:datetime` field behaves like a datetime column on the model: under `time_zone_aware_attributes` zone-less input is read in `Time.zone` and it reads back as a `TimeWithZone`, while the plaintext stays UTC ISO8601), `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; the digest is of the canonical plaintext, so a `:datetime` is found by any rendering of the instant in any `Time.zone` and a String finds a typed field — rows indexed before still match the lookup that found them, and `:datetime` fields should be [reindexed once](docs/concerns/encryptable.md#blind-index-of-a-typed-field)).
+**Options** (`encryptable *fields, …`, repeatable): `type:` (cast the decrypted value — `:string` default, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`; a `:datetime` field behaves like a datetime column on the model: under `time_zone_aware_attributes` zone-less input is read in `Time.zone` and it reads back as a `TimeWithZone`, while the plaintext stays UTC ISO8601), `key:` (per-field override; a String or a callable, anything else raises `ArgumentError`. A declared key that resolves to nil or `""` — a Proc over a missing credential, an explicit `key: nil`, an unset `ENV[...]` — is a missing key: `MissingKeyError` naming the field, or plaintext under `on_missing_key: :passthrough`; it never falls back to the global key, which only an omitted `key:` uses), `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; the digest is of the canonical plaintext, so a `:datetime` is found by any rendering of the instant in any `Time.zone` and a String finds a typed field — rows indexed before still match the lookup that found them, and `:datetime` fields should be [reindexed once](docs/concerns/encryptable.md#blind-index-of-a-typed-field)).
 
 **Key rotation** — bump the key id, keep the old key for decrypting, re-encrypt, drop the old key:
 
@@ -1860,6 +1866,7 @@ On the model itself both sweep the **whole table**, bypassing `default_scope`
 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**
+- [Filterable](#-filterable) is Encryptable-aware (`alias_attribute` followed): on an encrypted field equality and `in` (`?ssn=`, `?ssn_in=`) go through the blind index, and every other operator (`not`, `not_in`, `gt`/`gte`/`lt`/`lte`, `contains`, `starts_with`) fails closed (matches nothing); a field without a blind index fails closed for every operator but `null`.
 - 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.
 - 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), no `lock_version` bump (so records open in edit forms don't go stale), 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.
@@ -1933,6 +1940,7 @@ copy = invoice.duplicate!(only: [])                     # shallow copy — attri
 - The macro is optional — bare `include` gives `duplicate`/`duplicate!` with the auto resets.
 - `only:` / `except:` on `duplicate` / `duplicate!` pick which of the declared associations this particular copy carries ("Duplicate with line items?" checkbox); names outside the allow-list raise. They are reserved keys — pass overrides for attributes literally named `only`/`except` as a braced Hash.
 - Override `on_duplicate(copy)` for custom tweaks; it receives the unsaved copy last.
+- A child (or has_one target) marked for destruction in memory (nested attributes `_destroy`, `mark_for_destruction`) is not copied, so a "save as copy" flow does not resurrect a just-removed child.
 - Reach for [`amoeba`](https://github.com/amoeba-rb/amoeba) when you need per-attribute regex/prepend rules or belongs_to graph copying.
 
 ---
@@ -1988,6 +1996,8 @@ render_success(data: paginated(result.hits, total: result.total_hits), meta: pag
 | `?page=`     | `1`     | Page numbers below 1 are clamped to 1 |
 | `?per_page=` | `25`    | Capped at `max_per_page` (default 200) |
 
+`?page=` and `?per_page=` are read as an exact whole number (`?per_page=1e3` is 1000, then capped; `?page=2e0` is 2); anything else — a fraction (`2.9`), trailing garbage (`10abc`), a value beyond 100 digits — is the default (page 1 / the default `per_page`), never its leading digits. A grouped relation counts its groups, a `HAVING` on a select alias included (it is counted as a subquery that keeps its select list). Re-declaring `paginate_by` (e.g. in a subclass) changes only the options passed — every omitted one (`max_per_page:`, `link_header:`, `window:`, `style:`, the param paths) is inherited; `style:` re-derives both param paths, and an explicit `page_param:`/`per_page_param:` still wins.
+
 Rename them, or speak JSON:API — the `Link` header URLs follow whatever you pick:
 
 ```ruby
@@ -2062,7 +2072,7 @@ end
 | Param        | Default | Notes                                                    |
 |--------------|---------|----------------------------------------------------------|
 | `?cursor=`   | —       | The opaque token from `X-Next-Cursor` (omit for page 1)  |
-| `?per_page=` | `25`    | Capped at `max_per_page` (default 200; `0` disables the configured cap, but never the absolute 1,000,000 ceiling it shares with Paginatable) |
+| `?per_page=` | `25`    | Capped at `max_per_page` (default 200; `0` disables the configured cap, but never the absolute 1,000,000 ceiling it shares with Paginatable); read as an exact whole number, anything else is the default |
 | `?order=`    | first preset | With `order_presets:` only — selects a named ordering from the allow-list (unknown names → 400 `invalid_order_preset`) |
 
 **Response headers**: `X-Per-Page`, `X-Count` (rows on **this** page — totals are deliberately not computed), `X-Has-More`, `X-Next-Cursor` (only while more pages exist). With `bidirectional: true`: also `X-Has-Prev`, `X-Prev-Cursor`. Plus an RFC 8288 `Link` header: `rel="next"` carries the next-cursor URL, `rel="prev"` the prev-cursor URL (bidirectional), `rel="first"` the current URL with the cursor dropped (once a cursor is in play); `per_page` and the order preset are preserved. `cursor_paginate_by link_header: false` turns it off.
@@ -2071,7 +2081,7 @@ end
 - 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), must be **selected by the relation, unaliased**, and may be nullable: a column the schema allows NULL in paginates with its **NULLs last** in either direction on every adapter, returning every row exactly once with no extra queries. PostgreSQL uses `NULLS LAST`; other adapters use a `CASE WHEN col IS NULL` sort key, and the keyset WHERE uses the OR-expansion. NOT NULL columns keep the plain, index-friendly SQL, so prefer them on large tables. Boundary values are the stored column values (`read_attribute`), so an overridden attribute reader cannot derail the walk (a binary one — e.g. a `binary(16)` UUID primary key — travels as Base64; a `time` column's is its stored time of day, `"10:30:15.500000"`, which every Rails line reads back exactly); a boundary column the relation did not select raises `ActiveModel::MissingAttributeError`, and a stored non-NULL value that its attribute type casts to nil (an unparseable datetime string) raises `ArgumentError` — neither is minted as a NULL boundary. A select alias that shadows an ordering column (`select(:id, "UPPER(name) AS name")`) is not detected: the cursor would carry the alias's value while the WHERE compares the column, repeating or skipping rows — alias under another name instead. Re-declaring `cursor_paginate_by` (e.g. in a subclass) changes only the options passed — the rest, `signed:` included, are inherited.
 - 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); a value the column cannot hold — a timestamp outside years 0001..9999, a String that is invalid UTF-8 or carries a NUL byte (accepted on MySQL, which stores and escapes one), or is a number beyond a decimal's precision or too long/wide to read (bounded like Filterable's operands), included — is the same 400, never a database error 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).
+- 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). `:row` requires uniform directions, validated at declaration: `predicate: :row` with a mixed-direction `order:` or `order_presets:` entry raises `ArgumentError` at class load (a per-call `cursor_paginated(order:)` with mixed directions raises before page 1) — use `:auto` for a mixed order. A NUL-bearing String ordering value on SQLite is paged with the boundary cast from its hex bytes as TEXT, which assumes a UTF-8 SQLite database (Rails' default).
 - Use Paginatable when you need page numbers and totals.
 
 ---
@@ -2104,7 +2114,7 @@ accepted as a suffix `?price_gte=10` or in bracket form `?price[gte]=10&price[lt
 | `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`) |
+| `null`   | `?deleted_at_null=true`            | `deleted_at IS NULL` (`false` → `IS NOT NULL`); reads true/false (also 1/0, t/f, yes/no, case-insensitive); any other value matches nothing |
 | `contains` `starts_with` | `?title_contains=rails` | `title LIKE '%rails%'` (wildcards escaped; ILIKE on PostgreSQL; string/text columns only) |
 
 Comparison values are cast through the column's own type, or through `type:` (any ActiveModel type
@@ -2121,7 +2131,7 @@ are skipped and unknown operators / non-scalar values ignored. A `gt`/`gte`/`lt`
 cannot represent (`?price_gte=abc`) matches **nothing** rather than silently comparing against `0` —
 nothing raises at request time. So does any operand carrying a NUL byte (`?title_gte=a%00b`,
 `?title_contains=%00`, `?title=a%00b`, a NUL member of an `in` list; binary columns excepted): it used to
-cut the SQL short, a `StatementInvalid` 500. For strict, validated contracts reach for `Permittable`.
+cut the SQL short, a `StatementInvalid` 500. A `with:` lambda declared with a `type:` never receives an Array/Hash/Parameters value: it fails the filter closed for every `type:`, the lambda is not called. A Float column's operand is compared exactly too: a decimal literal the double does not read back as (`0.1000000000000000000001`) equals nothing and compares as the largest double at or below it (`?score_gt=` keeps a stored `0.1`). On an [Encryptable](#-encryptable) column equality and `in` use the blind index and every other operator fails closed (see Encryptable). For strict, validated contracts reach for `Permittable`.
 
 On an `enum` column a comparison operand is a **label** (`?status_gte=review` is `status >= 1`). On an
 integer-backed enum anything else is read as a number, exactly like an integer column's operand, so a
@@ -2294,7 +2304,7 @@ end
 | `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        |
+| `record_not_destroyed`       | `ActiveRecord::RecordNotDestroyed`             | 422    | record errors, if any (message is the generic "Resource could not be deleted") |
 | `stale_object`               | `ActiveRecord::StaleObjectError`               | 409    | —                            |
 | `record_not_unique`          | `ActiveRecord::RecordNotUnique`                | 409    | —                            |
 | `foreign_key_violation`      | `ActiveRecord::InvalidForeignKey`              | 409    | —                            |
@@ -2403,6 +2413,7 @@ GET /articles?include=author,comments.author&fields[articles]=id,title&fields[au
 - A path is kept only if **every** segment follows the allow-list tree (`comments.author` needs `comments: :author`); anything else is **silently dropped** — no error, no arbitrary eager-loading.
 - `default:` applies only when `?include` is absent; `?include=` (blank) means "nothing" and is honoured. Defaults are validated against the allow-list at class load, stored frozen and `dup`ed per request.
 - **A typo in an option name becomes an association.** Inline nested Hashes arrive as `**nested`, so any keyword the macro does not name is registered as an allow-listed association instead of raising: `feilds:` silently leaves `includable_fields` empty — i.e. no sparse-fieldset allow-list at all.
+- Re-declaring `includable` (e.g. in a subclass) changes only what it passes: the association list replaces the parent's, but `fields:`, `default:` and `strategy:` keep their inherited value when omitted (`default: nil` / `fields: {}` clear them). An inherited `default:` path the new list no longer contains is dropped with a one-line warning on stderr at class load.
 - Non-whitelisted tables in `params[:fields]` are dropped; non-whitelisted columns within an allowed table are dropped.
 - Pass `requested_fields` to your serializer (e.g. AMS / Blueprinter) — `Includable` itself does not alter the JSON output, only the query.
 
@@ -2442,7 +2453,7 @@ end
 | `:no_referrer_leak`   | `Referrer-Policy: strict-origin-when-cross-origin`     |
 | `:no_cross_domain`    | `X-Permitted-Cross-Domain-Policies: none`              |
 | `:disable_legacy_xss` | `X-XSS-Protection: 0` (the only correct modern value)  |
-| `:hsts`               | `Strict-Transport-Security: max-age=31536000; includeSubDomains` (no `preload` — opt in via a custom pair) |
+| `:hsts`               | `Strict-Transport-Security: max-age=31536000; includeSubDomains` (no `preload` — opt in via a custom pair). Skipped automatically when `config.force_ssl` is on (Rails' own HSTS, from `config.ssl_options`, applies instead). |
 | `:same_origin_opener` / `:same_origin_opener_allow_popups` | `Cross-Origin-Opener-Policy: same-origin` / `same-origin-allow-popups` |
 | `:require_corp_embedder` | `Cross-Origin-Embedder-Policy: require-corp`        |
 | `:same_origin_resource` | `Cross-Origin-Resource-Policy: same-origin`          |
@@ -2505,8 +2516,8 @@ The predicate runs via `instance_exec`, so `current_user` (and any helper) resol
 
 | Method                    | Signature                                                                                  |
 |---------------------------|--------------------------------------------------------------------------------------------|
-| `authorize_by`            | `authorize_by(only: nil, except: nil, status: :forbidden, message: "Forbidden", name: nil, &block)` |
-| `require_role`            | `require_role(*roles, via: :current_user, role_method: :role, only:, except:, status:, message:, name:)` |
+| `authorize_by`            | `authorize_by(only: nil, except: nil, status: :forbidden, message: <derived from status>, name: nil, &block)` |
+| `require_role`            | `require_role(*roles, via: :current_user, role_method: :role, only:, except:, status:, message:, name:)` — roles may be given as one or several Arrays (flattened) |
 | `skip_authorization`      | `skip_authorization(only: %i[index show])` / `skip_authorization(except: %i[destroy])` / bare — exempt actions from every rule, inherited ones included; bare form exempts all |
 | `authorized?`             | `authorized?(action = action_name)` — evaluate the rules without rendering (for views / conditional UI) |
 | `on_authorization_denied` | `on_authorization_denied(rule)` — override point; instruments `authorization_denied.concerns_on_rails` (call `super` to keep the event) |
@@ -2514,8 +2525,8 @@ The predicate runs via `instance_exec`, so `current_user` (and any helper) resol
 **Notes**
 - Rules run in declaration order; the first failing rule renders and halts.
 - Every denial emits `authorization_denied.concerns_on_rails` with `controller`, `action`, `actor_id`, `actor_type`, `rule` (the `name:`), `status`, `message` — subscribe for audit logs or alerting on repeated denials. The actor is reduced to scalars on purpose: notification payloads aren't filtered by `config.filter_parameters`.
-- When `Respondable` is also included, denials delegate to `render_error` (envelope `{ success: false, error: { message:, code: "forbidden" } }`); otherwise the same envelope is rendered inline. The `code` follows `status:`: `"unauthorized"` for 401, `"not_found"` for 404, `"forbidden"` for 403 and anything else. A `status: :not_found, message: "Resource not found"` concealment rule then answers exactly like ErrorHandleable's missing-record 404.
-- `only:` / `except:` are mutually exclusive (passing both raises `ArgumentError`); `authorize_by` requires a block and `require_role` requires at least one role.
+- When `Respondable` is also included, denials delegate to `render_error` (envelope `{ success: false, error: { message:, code: "forbidden" } }`); otherwise the same envelope is rendered inline. The `code` follows `status:`: `"unauthorized"` for 401, `"not_found"` for 404, `"forbidden"` for 403 and anything else. The default `message:` follows the status: `"Resource not found"` for 404 (ErrorHandleable's exact text), `"Unauthorized"` for 401, `"Forbidden"` otherwise; an explicit `message:` wins. A `status: :not_found` rule then answers exactly like ErrorHandleable's missing-record 404.
+- `only:` / `except:` are mutually exclusive (passing both raises `ArgumentError`); `authorize_by` requires a block and `require_role` requires at least one role (an empty list, or a nil/blank role such as an unset `ENV` lookup, raises at class load; Arrays are flattened).
 - `skip_authorization` validates its arguments at class-load time, because every mistake there fails **open**: a nil `only:`/`except:`, or an empty/non-action `except:` (`[]`, `false`, `""` — what `except: Rails.env.production? && :destroy` collapses to), raises instead of exempting every action of the controller *and its subclasses*. Only the bare form grants a blanket skip. The skip is inherited and outranks rules a subclass declares afterwards; `skip_authorization only: []` switches it back off.
 - **Non-goals**: no policy objects, no ability DSL, no resource inference — reach for [`pundit`](https://github.com/varvet/pundit) / [`cancancan`](https://github.com/CanCanCommunity/cancancan) when you outgrow a predicate per action.
 
@@ -2563,13 +2574,13 @@ class ApplicationController < ActionController::Base
   timezoneable available: ["UTC", "Eastern Time (US & Canada)"], default: "UTC"
   # timezoneable param: :tz, header: false, cookie: :time_zone
   # timezoneable cookie: :time_zone, persist: true          # ?time_zone=London sticks for a year
-  # timezoneable response_header: true                       # X-Time-Zone: London (+ Vary: Time-Zone)
+  # timezoneable response_header: true                       # X-Time-Zone: London
 end
 ```
 
 Resolution order: `params[param]` → `Time-Zone` header → cookie (if enabled) → `default` → the current `Time.zone`. Every value — the configured `available:` / `default:` **and** each request candidate — is resolved through `ActiveSupport::TimeZone[...]`, so a zone accepted at boot can never be rejected at request time.
 
-**Options**: `available:` (allow-list applied to param/header/cookie matching; `default:` bypasses it, mirroring Localizable), `default:`, `param:` (default `:time_zone`), `header:` (default `true`, reads the `Time-Zone` header), `cookie:` (default `false`; `true` reads the `:time_zone` cookie, or pass a cookie name), `persist:` (default `false`; `true` or a Hash of cookie options — writes a **param**-chosen zone into the `cookie:` so a settings link makes it stick; needs `cookie:`), `response_header:` (default `false`; `true` emits `X-Time-Zone`, or pass a header name — `Vary: Time-Zone` is appended when the header source is on).
+**Options**: `available:` (allow-list applied to param/header/cookie matching; `default:` bypasses it, mirroring Localizable), `default:`, `param:` (default `:time_zone`), `header:` (default `true`, reads the `Time-Zone` header), `cookie:` (default `false`; `true` reads the `:time_zone` cookie, or pass a cookie name), `persist:` (default `false`; `true` or a Hash of cookie options — writes a **param**-chosen zone into the `cookie:` so a settings link makes it stick; needs `cookie:`), `response_header:` (default `false`; `true` emits `X-Time-Zone`, or pass a header name), `vary:` (default `true`; appends `Vary: Time-Zone` whenever the header source is on and `Vary: Cookie` whenever the cookie source is on, independent of `response_header:`; `vary: false` opts out).
 
 **Notes**
 - An unknown `available:` / `default:` zone raises `ArgumentError` at declaration time (fail-fast on misconfiguration); so does `persist:` without `cookie:`.
@@ -2860,7 +2871,7 @@ Point your agent at `llms.txt` for an overview, or paste a single concern's `.md
 bundle install                                  # install dev dependencies
 bundle exec rspec                               # run the test suite (3,420 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.33.0.gem      # install locally
+gem install ./concerns_on_rails-1.34.0.gem      # install locally
 
 # Preview the docs site locally (GitHub Pages serves docs/ as-is):
 cd docs && python3 -m http.server 8000          # → http://localhost:8000