concerns_on_rails 1.30.0 → 1.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01db17beb47c485890bfd3c755086624432941547fdd77ecc52536164a2a3404
-  data.tar.gz: 8aeca6a8b1e4d901a8d1b128a75ff27f25f5f85138034819b75ed66cfb16cc4e
+  metadata.gz: a5638a56a20ce9b346dd013448af31656fe6925eaefbf8bd87ee8906c17825b4
+  data.tar.gz: b3feeb0feaab7f14bf5d03ea46a9e7a1a69f0d087173cf2fb0baa1efb2c86daa
 SHA512:
-  metadata.gz: 7615ea7a35f68bffb71e55975a9ad3097d683287dd1cddc81d4d0397343fba1d38289a8589db573ebe3a5f310ed5e2ddf43f621082f6bc16f56587402594df0e
-  data.tar.gz: '093ac4ae4b2de63d42722de0f75b23ce9423cc8528fa6c1768e849a515079d501b5df095e64c54227cd967d355ce302c63d55fe4467b7903083770ff38115adc'
+  metadata.gz: 25623c6d25c7fafc8e8c4dfd5f16350df059a5f0bb2999c0d457b986cfcff1c55365f8e072ab5dd01cb9ae48e6226ff335a546f02c1521ca0c3934898e92c296
+  data.tar.gz: ad5dd6aa2c310c9d711fd9513e01488e79f164df54aa2accdbca8ab9a46f3c2fe296c0733c6b0c404c0df09147c28160f7c5177e0938b6637eb3037d71f1e363

data/CHANGELOG.md

@@ -1,5 +1,377 @@
 <!-- CHANGELOG.md -->
 
+## 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
+signed it off: the 2026-09-25 audit of 1.30.0 (#116–#120) and the 2026-09-30 audit of this
+release's own candidate (#123–#125: values generated in `before_create`, optimistic locking
+around the gem's raw writes, and time values), plus dependency refreshes (#121, #126). It is a
+minor release because Sequenceable gains an option and a reader, and several fixes change
+observable behaviour or raise where the gem used to silently misbehave. Read **Changed** before
+upgrading: blind indexes of generated encrypted values, and of `:datetime` fields, want a
+one-off backfill. No new concerns and no migrations. Every fix ships with a regression spec.
+2723 examples, 0 failures (2694 on Rails 6.0), green on PostgreSQL and MySQL.
+
+### Changed
+- **Sequenceable: `reset:` periods are cut in one fixed zone**, not the per-request
+  `Time.zone`. The `MAX` range and the period token both use the new `time_zone:` (default:
+  `config.time_zone`, resolved at use time, else UTC). Before, two requests in different zones
+  (Timezoneable, `Time.use_zone`) could issue the **same number**, and `formatted_<field>`
+  without `into:` rendered a different date for readers in different zones. Apps that keep
+  `Time.zone == config.time_zone` see no change. With `into:` and `reset:` (no `template:`) the
+  next number also accounts for rows whose stored value already carries the period's `prefix +
+  token + separator`, so a number stamped under a request zone before the upgrade is continued,
+  never reissued; without `into:`, add a unique index before upgrading. (#116)
+- **Sequenceable: re-declaration.** A call passing **only `assign:` and/or `time_zone:`** keeps
+  the rest of the field's current config, so `sequenceable_by :sequence, assign: :manual` on a
+  `Draft` subclass keeps the parent's `into:`/`prefix:`/`reset:`/`template:`. Every other
+  re-declaration, a bare one included, restates the format from the defaults as before. A
+  re-declaration whose full format tuple is identical to an inherited owner's now shares that
+  owner's counter, instead of numbering a subclass-only series that could reissue its numbers
+  (Procs compare by identity, so a draft subclass should re-declare only `assign:`).
+  **Upgrading:** a subclass declared the `assign:`-only way used to number its own
+  default-format series; its rows without an `into:` value now render in the parent's format,
+  so backfill `into:` first. (#116)
+- **Sequenceable: classes sharing a counter under `reset:` must cut the same periods.** Both
+  `time_zone:` omitted, or both explicit and the same zone (compared by canonical TZInfo
+  identifier, then by UTC offsets 1970–2100, so `"Kolkata"`/`"Asia/Calcutta"` match), else
+  `ArgumentError` at class load. Declare `time_zone:` on the class that first declares a
+  format, and declare an owner fully before its subclasses. (#116)
+- **CursorPaginatable: nullable ordering columns paginate, NULLs last** in both directions on
+  every adapter (PostgreSQL `NULLS LAST`, a `CASE` sort key elsewhere; the keyset WHERE uses
+  the OR-expansion). NULL-ordered rows used to be silently dropped, and NULLs sorted first
+  under PostgreSQL DESC and SQLite/MySQL ASC. NOT NULL columns keep the same SQL. An ordering
+  column the relation did not select raises `ActiveModel::MissingAttributeError`, a stored
+  non-NULL value that casts to nil raises `ArgumentError`, and ordering columns must be
+  selected unaliased. (#117)
+- **CursorPaginatable**: re-declaring `cursor_paginate_by` (e.g. in a subclass) changes only
+  the options passed and inherits the rest, so a subclass setting only `order:` no longer
+  silently disables the parent's `signed:`. (#117)
+- **Paginatable**: a `DISTINCT` relation with its own `SELECT` list
+  (`select(:group_id).distinct`) is counted as a subquery of the relation's own SQL, so
+  `X-Total-Count` / `X-Total-Pages` count the distinct rows returned, not every underlying row.
+  Only MySQL, which rejects repeated output names in a derived table (error 1060, recognised by
+  driver code), retries with the select list re-aliased, and falls back to the previous
+  over-count if that fails too. (#117)
+- **Stateable: name collisions raise.** `stateable_by` raises `ArgumentError` when a generated
+  `<state>?`/`<state>!`/`<event>!`/`may_<event>?` method or `.<state>` scope would override a
+  method the class already has from ActiveRecord or another concern — an event `lock`
+  overriding AR's `lock!` (which broke `with_lock` and `lock: true`), an event `restore` next
+  to SoftDeletable, a state `active` next to Activatable. Use `prefix:`/`suffix:`. The reverse
+  order raises too. One exemption: a state may take a scope that is still SoftDeletable's,
+  Publishable's or Schedulable's untouched include-time default on the same class, so that
+  concern's own macro can rename it — include that concern before `stateable_by`; only its
+  affixing macro may come after. An unrenamed collision raises when the shared scope is called.
+  (#120)
+- **Stateable**: a re-declaration retires the methods and scopes the earlier declaration
+  generated and the new one no longer lists (a subclass with `states: %i[open closed]` no
+  longer answers its parent's `archive!` or `.draft`). Only methods Stateable itself defined
+  are retired; a user's own method under such a name is left alone. The attribute default no
+  longer forces a `:string` type onto the state column (a PG enum/citext or host-declared
+  `attribute` type is kept, per declaring class), and a re-declaration without `default:` keeps
+  the earlier default only while it is still a declared state. (#120)
+- **Publishable**: `default_scope:` is a flag read by one lazily registered default scope,
+  added only the first time a class passes `default_scope: true`, so a model that never asks
+  for it keeps Rails' statement cache. An explicit `default_scope: false` on a later call or an
+  STI subclass turns it off; omitting the option keeps the inherited setting. (#120)
+- **Encryptable**: an encrypted field used as a friendly_id slug source raises `ArgumentError`
+  — the `sluggable_by` field, a `candidates:` entry, an `alias_attribute` of the field (chains
+  followed) or a bare friendly_id base — at declaration where it can, otherwise at save, before
+  the row is written. The slug used to store the field's plaintext. **Upgrading:** regenerate
+  those slugs from a safe field and delete the stale `friendly_id_slugs` rows (see the
+  Encryptable docs). (#118)
+- **SoftDeletable `cascade:` / Duplicable** now reach children hidden by Publishable's
+  `default_scope: true` (drafts). Only the gem's own hiding predicates on the child's own table
+  are removed; every other default-scope predicate still applies, as for Rails' `dependent:` —
+  a tenant scope, a discriminator on a shared table, a joined table's same-named column. A
+  `has_one` cascades to / copies the child its reader returns. Duplicable never copies a
+  SoftDeletable child's soft-deleted rows into a `has_many`/`has_one` copy, whatever its
+  `default_scope:` (with it off, the copy used to get them back as live rows). (#119)
+- **Normalizable**: saves that skip validation (`update_attribute`, `save(validate: false)`)
+  are normalized by a prepended `before_save` backstop, so Encryptable's blind index, Auditable
+  and Addressable see the normalized value whatever the include order. (#120)
+- **CounterCacheable**: re-declaring the same association + `count:` column replaces the
+  earlier rule (it double-counted); an STI subclass can narrow an inherited counter with `if:`;
+  on an STI table `recount_counter_caches!` tallies every class's rows under its own rule,
+  resolving each stored type without building a record (an unknown type counts under the base
+  rule instead of raising). (#120)
+
+- **Upgrading (Encryptable + Tokenizable/Hashable/Sequenceable):** rows created before this
+  release with a generated, blind-indexed encrypted value (a token, code or number) were stored
+  with a **NULL** blind index. They stay unfindable by `find_by_<field>` / `where_<field>` /
+  `authenticate_by_<field>` / `consume_<field>` until backfilled. `reencrypt_all!` does not
+  reach them, because they are already under the current key. Run once per field:
+  `Model.unscoped.where(<field>_bidx: nil).where.not(<field>: nil).find_each { |r|
+  r.update_columns(<field>_bidx: Model.<field>_fingerprint(r.<field>)) }` (no callbacks, any
+  key). See `docs/concerns/encryptable.md#upgrading-blind-indexes-of-generated-values`. (#123)
+- **Searchable:** `searchable_by` over an `encryptable` column (or `encryptable` over a searched
+  one) raises `ArgumentError` at declaration. Before, `search` ran `LIKE` against ciphertext and
+  silently returned nothing. (#123)
+- **Taggable:** `taggable_by` over an `encryptable` column (or `encryptable` over the tag
+  column) raises `ArgumentError` at declaration. A model that includes Taggable without
+  `taggable_by` and encrypts its default `:tags` is refused when `tagged_with` is called. New
+  `taggable_declared` class attribute. (#123)
+- **Tokenizable:** on an `encryptable :<field>, blind_index: true` token,
+  `authenticate_by_<field>` / `consume_<field>` look the token up through the blind index (still
+  `secure_compare`d), and `consume_<field>` clears the index along with the token. Encrypted
+  without a blind index, they raise `ArgumentError` when called; before, they returned `nil` for
+  every token. Generating, storing and rotating an encrypted token work as before. (#123)
+- **Anonymizable:** with `lock_version`, `anonymize!` / `anonymize_all!` write their single
+  UPDATE through `update_all`, bumping `lock_version` in SQL (the row's value + 1). An edit form
+  loaded before the erasure now raises `StaleObjectError` instead of writing the personal data
+  back. A stale anonymizing instance now erases; on Rails 7.0+ its constrained `update_columns`
+  used to erase nothing while returning `true`. `update_columns`' refusals (destroyed,
+  `readonly!`, `attr_readonly`) are kept. (#124)
+- **Expirable:** `extend_expiry!` extends the **stored** expiry, read under a row lock, so
+  concurrent extensions compound (two `+30.days` renewals give +60, not +30). An expiry assigned
+  but not yet saved, and a new record, still extend from the instance's value. With optimistic
+  locking, a stale instance raises `StaleObjectError` rather than losing a renewal. (#124)
+- **Encryptable:** `type: :datetime` behaves like a datetime column on the same model. Under
+  `time_zone_aware_attributes`, a zone-less String (a `datetime-local` form value) and a
+  `datetime_select` value are wall-clock time in `Time.zone`, a `Date` is midnight there, and
+  the field reads back as an `ActiveSupport::TimeWithZone`. Otherwise it follows
+  `ActiveRecord.default_timezone`. It is exactly the handling Rails gives `attribute :name,
+  :datetime` (ActiveRecord wraps the type in its own `TimeZoneConverter`), so `normalizes` and a
+  parent's re-declaration are inherited by subclasses.
+  `skip_time_zone_conversion_for_attributes` (Symbols) is honored when set before the
+  `encryptable` line; on Rails 6.0–7.1 wherever it is set. From Rails 7.2, where Rails decides
+  at declaration, a skip list set later or on a subclass raises `ArgumentError` when the model
+  is first used, unless the field is re-declared right after it. The plaintext stays UTC
+  ISO8601, so existing rows read as the same instant. A stored plaintext without `Z` or an
+  offset is read in `default_timezone`, never the server's zone. (#125)
+- **Encryptable:** a blind index fingerprints the field's canonical plaintext (the value cast
+  through its `type:`, a `:datetime` as UTC ISO8601) on write and on lookup. `find_by_<field>` /
+  `where_<field>` on a `:datetime` field find the record by any rendering of the instant,
+  whatever `Time.zone` the writer, the reader or `reencrypt!` ran in, and a String finds a typed
+  field (`find_by_age("042")`). `expression:` receives the cast value (a `:datetime` as a UTC
+  `Time`). Lookups also try the digest the index used before, so existing rows stay findable by
+  the lookup that found them. `:datetime` fields should be reindexed once (recipe in
+  `docs/concerns/encryptable.md#blind-index-of-a-typed-field`, which skips rows it cannot
+  decrypt); every other type's digest is unchanged. A non-numeric String on an `:integer` field
+  finds nothing, as an integer column's `where`, and a value that does not cast
+  (`Float::INFINITY`) is stored as `NULL` with no digest. (#125)
+- **Storable:** `:datetime` keys behave like a datetime column on the same model, with the same
+  `Time.zone` / `default_timezone` rules as Encryptable. The reader returns an
+  `ActiveSupport::TimeWithZone` under `time_zone_aware_attributes`, `where_<key>` parses its
+  argument the same way as the writer, a `datetime_select` value is wall-clock time in
+  `Time.zone`, and a `default:` (a String, a `Time` or a Proc) reads back as the same value
+  stored would. List the accessor in `skip_time_zone_conversion_for_attributes` to opt a key
+  out. The stored UTC ISO8601 form is unchanged. (#125)
+- **Publishable / SoftDeletable / Schedulable / Expirable:** `publish_at!`, `soft_delete!(at:)`,
+  `start!`, `finish!`, `reschedule!`, `expire!` and `expire_all` raise `ArgumentError` before
+  any hook runs when given a value that is not a time: a String must read as a date the way
+  `Time.zone.parse` will read it: a four-digit year, no ordinal day, every part in range, years
+  0001–9999, and only date words or a time zone (ISO 8601, RFC 2822 with its comments, HTTP
+  dates, JavaScript `Date#toString`, Go and RFC 9557 forms, `"Oct 1 2026"`, `"2026-10-01 10:30
+  EST"` and `"10:30 p.m."` all pass; `"junk"`, `"Monday"`, `"10:30"`, `"junk 2026"`, `"Oct 1
+  26"`, `"15th of October 2026"` and `"7:30p"` do not, although `Time.zone.parse` reads them as
+  June 1st, today, year 26 AD, October 1st or military zone P), and `42` or `1.hour` never cast.
+  The first five used to write `NULL` and still return `true`; Expirable accepted the yearless
+  words in time-zone-aware apps. Column assignment is unchanged. The check is the shared
+  `Support::TimeValue.cast_argument!`. (#125)
+- **SoftDeletable:** `soft_delete!(at: nil)` or a blank `at:` means now, as for `expire!`.
+  `soft_delete!(at: params[:at])` with the param absent used to write `NULL`, fire the hooks and
+  return `true` with nothing deleted. `publish_at!(nil)` (and blank) still writes `NULL` and
+  fires the publish hooks. (#125)
+
+### Added
+- **Sequenceable**: `time_zone:` (a zone name as a String or Symbol, or an
+  `ActiveSupport::TimeZone`; an unknown zone raises at class load) and
+  `sequenceable_period_time(field)`, the fixed-zone period instant for `template:` lambdas that
+  render a date. (#116)
+
+### Fixed
+- **Sequenceable**: re-declaring a field with `assign: :manual`, on the same class or an STI
+  subclass, really stops numbering at create. Each call used to add its own `before_create`
+  lambda, and the earlier `:create` one kept firing. Each field now has one symbol callback,
+  registered at its first `assign: :create` declaration, honouring the receiving class's
+  current declaration. (#116)
+- **Paginatable**: `paginated(Model)` / `pagination_meta(Model)` with a bare model class no
+  longer raises. A non-finite JSON-body `page`/`per_page` (`1e400`, NaN) falls back to the
+  default instead of a 500 (Paginatable and CursorPaginatable). (#117)
+- **CursorPaginatable**: boundary values are read from the stored column, so an overridden
+  attribute reader no longer makes the walk repeat pages forever, and a value changed in memory
+  (an `after_initialize` default) no longer keys the cursor on a value the row's sort position
+  does not have. (#117)
+- **Callable options**: Throttleable `by:`, WebhookVerifiable `secret:`, Deprecatable
+  `notify:`, CounterCacheable `if:` and Auditable `actor:` accept every callable the macro
+  validates. A lambda with no required parameter or a block is `instance_exec`'d as before; a
+  lambda with a required parameter or a symbol proc is called with the controller (the record
+  for `if:`/`actor:`); any other callable object gets it only when its `#call` requires an
+  argument, and is otherwise called bare. These used to raise `TypeError`/`ArgumentError` (for
+  `actor:`, on every save). Throttleable's `if:`/`unless:` keep their own dispatch. (#117)
+- **Anonymizable**: a callable-object `with:` strategy no longer raises `NoMethodError`
+  (`#arity`). (#117) A rewritten slug counts as an erased field for `clear_audit_trail:`,
+  `slug: :auto` sees a slug built from an `alias_attribute` of an erased column, erasing an
+  Addressable-mapped column clears its `fingerprint:` in the same UPDATE, and
+  `prefix:`/`suffix:` passed on a later call are honoured (old scope names retired safely).
+  (#118)
+- **Idempotentable**: a replay carries the original's exact `Content-Type`, so
+  `application/problem+json` is no longer replayed with `; charset=utf-8`. (#117)
+- **Monetizable**: underscore-grouped amounts (`"5_5"`, `"1_000"`) are rejected (nil) like
+  other mis-grouped input. (#117)
+- **Filterable**: a nonzero float operand that underflows to 0.0 (`"1e-400"`) is treated as
+  inexact, so `=` matches nothing and `<`/`>` compare correctly. (#117)
+- **Maskable**: presets stringify non-String values before masking instead of returning them
+  raw (integer SSN/phone columns were shown unmasked); integral BigDecimal/Float values render
+  without `.0`. (#118)
+- **Lockable**: `lock_access!` is a conditional UPDATE — a concurrent stale instance adopts the
+  existing lock instead of re-minting the mailed unlock token and re-firing `after_lock`;
+  `before_lock` runs after the row is claimed. `register_failed_attempt!` clears a lapsed lock
+  the same way: a stale instance used to wipe a lock another request had just taken (a second
+  token and `after_lock`, or, below `max_attempts`, an account left unlocked). (#118)
+- **Loader**: every concern file works when required directly (`gem "concerns_on_rails",
+  require: false`). The gem-level singletons live in `concerns_on_rails/core`, and a directly
+  required file now also wires its sensitive fields into Rails' `filter_parameters` and
+  ActiveRecord's `filter_attributes` whether required before, during (eager load,
+  `config/initializers`) or after boot — unlock tokens used to be logged in clear and
+  `#inspect` showed decrypted values. Deprecatable/Timezoneable require the ActiveSupport time
+  extensions they use. (#118)
+- **Sluggable**: a re-declaration refused by the column check no longer leaves its field
+  assigned. **Duplicable**: sibling-concern detection no longer autoloads Sluggable/friendly_id
+  (or raises without the loader). (#118)
+- **Batch verbs** (`*_all`, `anonymize_all!`, `reencrypt_all!`, `recount_counter_caches!`, the
+  cascade) on their per-record path act on exactly the rows an ordered or limited relation
+  selects (`order(id: :desc).limit(2).publish_all` touched the two lowest ids), no longer raise
+  under `error_on_ignored_order`, and visit each record once over a `has_many` join (hooks ran
+  once per joined row); a limited joined slice instantiates one record per row. (#119)
+- **Duplicable**: identity columns (token, slug, sequence number, audit trail, lock state) are
+  reset on copies of children that do not include Duplicable; they used to share the original's
+  token or raise `RecordNotUnique`. (#119)
+- **Hooked writes** (`publish!`, a Stateable event, `soft_delete!`, `expire!`, `activate!`,
+  `anonymize!`): a veto or failure restores every in-memory attribute, including a nested
+  in-place edit of an already-read json value, never decrypting anything. (#119)
+- **Auditable**: works on a native `json`/`jsonb` trail column (declare it without a default —
+  MySQL rejects a literal JSON `DEFAULT`); earlier double-encoded trails still read, and
+  `audit_trail` entries are detached from the column value. (#119)
+- **Searchable**: `mode: :any` strips surrounding whitespace from the query. **Storable**:
+  every non-Proc `default:` is deep-duped per read. (#120)
+
+- **Encryptable:** a blind-indexed value that Tokenizable, Hashable or Sequenceable generates in
+  `before_create` is now fingerprinted when it is generated. Before, the row was stored with a
+  NULL blind index, so `find_by_<field>` never found a freshly created record. Works in either
+  include or declaration order. (#123)
+- **Sluggable:** a slug whose source is filled in `before_create` (Sequenceable's `into:`
+  number, a Hashable code) is now built in the same `INSERT`, not left `nil` until a later save.
+  friendly_id's rules still apply: an explicit slug is kept, a conflict gets the uuid suffix,
+  and `candidates:` are honored. The late slug is built after every
+  `before_validation`/`before_save`, so it gets what those would have done: a reserved word gets
+  the uuid suffix, and the slug column's own write-mode Sanitizable and Normalizable rules are
+  applied (`normalizable :slug, with: ->(v) { v.tr("-", "_") }` → `"inv_1"`). (#123)
+- **Sluggable:** a slug built earlier in the same save from a source that a later
+  `before_validation` then transformed (Sanitizable `on: :write`, Normalizable, your own
+  callback, included after Sluggable) is rebuilt from the final value at the start of
+  validation. Before, `"<b>Hello</b>"` got the slug `"b-hello-b"`. The rebuild runs before every
+  validator (`reserved_words:` included) and every sibling `before_save`, and never touches an
+  explicitly assigned slug. (#123)
+- **Auditable:** the creation entry now includes a tracked column generated in `before_create`
+  (a Sequenceable number, a Tokenizable/Hashable value, or a slug built from one), whatever the
+  include order. (#123)
+- **Hashable:** the report of a generated code to its siblings is a separate `before_create
+  :hashable_report_generated_value`, right after the unchanged `before_create
+  :assign_hashable_value`. Calling `assign_hashable_value` yourself, outside a save, only
+  assigns the value. (#123)
+- **Tokenizable / Hashable:** the uniqueness precheck on an encrypted field goes through the
+  blind index. It used to compare against ciphertext and could never detect a collision. (#123)
+- **Lockable:** with optimistic locking (`lock_version`), the raw writes —
+  `register_failed_attempt!`'s increment, the `lock_access!` claim, the quiet lapsed-lock reset,
+  and `unlock_by_token`'s token claim — bump `lock_version` in SQL, and the bump is now mirrored
+  into the instance exactly as Rails' `increment!` does. The same instance, and the record
+  `unlock_by_token` returns, save afterwards instead of raising `StaleObjectError`. On Rails
+  7.0+ this also fixes `unlock_by_token` leaving the account locked: the stale instance's
+  `update_columns` matched no row while the call reported success. A hook that aborts takes the
+  in-memory bump back. (#124)
+- **CounterCacheable:** with `lock_version` on the parent, the parent instance the child's
+  association holds (`post.comments.create!`'s `post`, the one passed as `post:`, the old parent
+  a foreign-key reassignment left loaded, the parent on destroy) gets the counter delta and the
+  `lock_version` bump mirrored in memory — the in-memory half of native `counter_cache`'s
+  `increment!`. `post.comments.create!(...); post.update!(...)` no longer raises
+  `StaleObjectError`. A counter you assigned and haven't saved is left exactly as assigned,
+  still pending (native `increment!` would add the delta to it), while `lock_version` is still
+  bumped. When the child's save is rolled back — your `ActiveRecord::Rollback`, a later callback
+  raising, a Stateable/HookedWrite hook vetoing, a rolled-back savepoint, a rolled-back
+  `transaction(joinable: false)` — the mirror is taken back off the parent instance, so it stays
+  saveable (native `counter_cache` leaves it stale). Only the adjustments that were actually
+  rolled back are undone, and a counter or `lock_version` you assigned after the mirror is left
+  as you assigned it. The undo holds the parent only weakly, once per parent and transaction, so
+  long batches keep nothing in memory, and the parent stays `Marshal`-dumpable. An
+  `attr_readonly` counter is not mirrored. Known limit: a parent destroyed later in the same
+  rolled-back transaction keeps its mirror (reload it). Without `lock_version`, nothing changes.
+  (#124)
+- **Encryptable:** `reencrypt!` / `reencrypt_all!` no longer bump `lock_version`, since the
+  column is pinned to itself in the rotation UPDATE. A key rotation changes no value, so records
+  open in edit forms during the sweep no longer turn into `StaleObjectError`s. The ciphertext
+  guard is unchanged. (#124)
+- **Stateable:** `lock: true` works on records with unsaved changes (`ticket.note = "fixed";
+  ticket.resolve!` saves the note with the state, as `lock: false` does); `with_lock`'s reload
+  used to raise "Locking a record with unpersisted changes is not supported". For such a record
+  only the state column is read (`SELECT <state> ... FOR UPDATE`) and adopted, and the guard
+  decides from it (a disallowed event raises `InvalidTransition`). On a model with optimistic
+  locking, a record with unsaved changes whose row has changed since it was loaded raises
+  `StaleObjectError`: its changes were made against a stale copy. A deleted row raises
+  `RecordNotFound`. A record without unsaved changes is still reloaded under the lock, exactly
+  as before. (#124)
+- **Activatable:** `toggle_active!` works on records with unsaved changes. It used `with_lock`
+  too, and raised the same "unpersisted changes" error. Such a record now has only its flag read
+  under the lock; it flips the row's value, and its changes save with the flip. A record without
+  unsaved changes is still reloaded under the lock. (#124)
+- **Encryptable:** `type: :datetime` stores a frozen or non-UTC `Time` correctly and never
+  modifies it. `Time#utc` converted the caller's value in place, and a frozen `Time` was
+  silently saved as `NULL`. (#125)
+- **Auditable:** recording a tracked datetime no longer converts the record's (the caller's)
+  `Time` to UTC in place, and a frozen `Time` no longer makes the save raise `FrozenError`.
+  (#125)
+- **CursorPaginatable:** minting a cursor no longer converts the page-boundary record's
+  timestamp to UTC in place. (#125)
+- **CursorPaginatable:** a cursor carrying a timestamp outside years 0001..9999 is an
+  `InvalidCursor` (400). It used to reach the WHERE clause and raise `DatetimeFieldOverflow` on
+  PostgreSQL (a 500), and SQLite compared it as text. (#125)
+- **Filterable:** date/time comparison operands outside `0001-01-01`..`9999-12-31` (the portable
+  SQL range) never reach the database. They are answered per operator, like out-of-range
+  numbers: `?happened_at_lt=300000-01-01` is every non-NULL row, `_gt` none, and in equality /
+  `in` / `not` / `not_in` such a value equals nothing. They used to raise
+  `DatetimeFieldOverflow` on PostgreSQL (a 500), and SQLite answered year-10000 comparisons
+  backwards. (#125)
+
+### Internal
+- New support modules: `Support::Callable`, `Support::SlugSources`,
+  `Support::AssociationScope`; gem-level singletons moved to `lib/concerns_on_rails/core.rb`. A
+  real-Rails-app subprocess spec covers filter wiring for direct requires.
+- Dev dependencies: Rails 8.1.4, permittable 0.10.0; the permittable compatibility suite accepts
+  both the pre-0.9 and 0.9+ validation messages (the gemspec still allows `~> 0.1`). (#121, #126)
+- New support modules: `Support::Locking` (lock_version mirroring, row-locked reads),
+  `Support::TimeValue` (verb time arguments, virtual datetimes, the portable year range),
+  `Support::GeneratedValues` and `Support::EncryptedLookup` (values generated in
+  `before_create`, equality lookups over encrypted columns). (#123–#125)
+- Documented limits: see `docs/concerns/sequenceable.md` (zones across STI leaves under an
+  abstract declarer; re-declaring an owner after its subclasses) and
+  `docs/concerns/stateable.md` (a subclass stub outlives a later parent re-declaration).
+  `unlock_access!`'s unconditional write is left for a follow-up. Also documented: a
+  CounterCacheable parent destroyed later in the same rolled-back transaction keeps its
+  in-memory mirror (reload it); Encryptable `find_by_<field>` does not apply the field's Rails
+  `normalizes`; on Rails 7.2+ an Encryptable `:datetime` skip list must precede the `encryptable`
+  line or be followed by a re-declaration (`docs/concerns/encryptable.md`).
+
 ## 1.30.0 (2026-09-27)
 
 The fixes from the 2026-09-23 whole-gem audit of 1.29.0: 37 bugs (8 HIGH) across six PRs