concerns_on_rails 1.26.0 → 1.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7552b47dbc09add52b4bb8d519e8a8d4ed4e49590457114003fa83b6e9b7036e
-  data.tar.gz: b03171261ba6e24865ce46ab0c1e77a234cfec514e45e50a2dd055e82b5da287
+  metadata.gz: b06bf25720ff6c5c3a243efdb7b0d575351d50b8a9f33ae4778c1354816075bb
+  data.tar.gz: 01dc0ff521bee7b5c74c9f30ddee414932441d2ceff84a15af1d9ae8e6d30ccc
 SHA512:
-  metadata.gz: 461bbe636a2537cc5b60fe1eb5be3c080c115a3f119ca057a5f75d24dd54da44a6f5833a1f2baff6d2562d829fa77f98e7d1494e57cd8e1402b513f697025d61
-  data.tar.gz: 046a10782bc2259cf8911610a13b71289aa77ce2a1164045fd524fc785b58cc6061756ea99fba3f147d6964145641f63e03ed50b8530656b9a7269a4b83ce2bf
+  metadata.gz: 37a533852c90cc1876519bd8b52fd07f165bfcfb02efca47bd1ed9d3ff86de94457755d57f9b986d244674a29992cead1b43698de7e3480e92276a0b9c9f1eda
+  data.tar.gz: 3651f6a175bf1a1e203bbe8353a9fc8b7a2c6457dd19f73e89e31fa108a8e238f36a7004aeffface605800b2838f6bb935694ef823a65dc0be943763bfd31293

data/CHANGELOG.md

@@ -1,5 +1,112 @@
 <!-- CHANGELOG.md -->
 
+## 1.27.0 (2026-08-29)
+
+Scope-name collisions finally have an escape hatch on the eight concerns whose
+generated scope names can collide (Activatable, Expirable, Lockable, Stateable
+and Anonymizable already had it; Publishable, SoftDeletable and Schedulable
+join them here), and the 1.22 batch-operation contract reaches five more
+concerns. No new columns, migrations or dependencies. 1257 examples, 0
+failures.
+
+### Added
+- **Models::Publishable / SoftDeletable / Schedulable**: `prefix:`/`suffix:` on
+  `publishable_by` / `soft_deletable_by` / `schedulable_by` rename the generated
+  scopes, so a model can include SoftDeletable (`.active`) alongside Activatable
+  or Expirable (also `.active`) without one silently clobbering the other. With
+  no affix passed the scope names, default scopes and emitted SQL are unchanged.
+  `prefix: true` (use the configured field name), previously honoured only by
+  Stateable, now works on every affixing concern.
+- **Models::Publishable**: `publish_all` / `unpublish_all`. `publish_all` targets
+  every not-currently-published row — *including scheduled ones*, whose future
+  timestamp it overwrites; chain the draft scope (`Post.draft.publish_all`) to
+  narrow it, which composes because the predicate is built against the current
+  relation rather than routed through the field-unscoping `unpublished` scope.
+  The flip side: on a model with `default_scope: true` the relation is already
+  narrowed to published rows, so a bare `Post.publish_all` matches nothing —
+  chain `.draft` or `.unpublished` (both unscope the column themselves). Both
+  verbs respect the relation, return an Integer count, and run in a
+  transaction.
+- **Models::Expirable**: `expire_all(time = Time.zone.now)`.
+- **Models::Activatable**: `activate_all` / `deactivate_all`.
+- **Models::Lockable**: `unlock_expired` — clears `locked_at` and zeroes the
+  attempts counter on every row whose `unlock_in` window has elapsed, mirroring
+  `unlock_access!`. Returns 0 without querying when `unlock_in` is nil.
+- **Models::Stateable**: `transition_all(event)` — runs one declared transition
+  across the relation, skipping (not failing) records the guard rejects.
+  Deliberately has no single-UPDATE fast path: the per-record path runs
+  validations through `update!` and a bulk UPDATE would skip them.
+
+### Notes
+Validation semantics of the new batch verbs (`publish_all`, `unpublish_all`,
+`expire_all`, `activate_all`, `deactivate_all`, `unlock_expired`): each
+collapses to a **single `UPDATE`** — one SQL statement for the whole batch —
+only when the host model declares **no validations** (and has overridden
+none of the concern's hooks/bang methods; see the per-concern docs for the
+exact method list). "No validations" means neither `validates` /
+`validates_with` **nor** a custom `validate :method` / `validate do … end` —
+the latter registers only a validate callback and leaves `validators` empty,
+so it is detected through `_validate_callbacks` rather than `validators`.
+It also means **no association carrying the default autosave validation**: a
+bare `has_many`/`has_one` registers a `validate_associated_records_*` callback,
+so in practice most models with associations take the streaming per-record
+path. That is deliberate — the gate errs toward the path that honours the
+rollback contract — but it means the single-`UPDATE` optimisation applies to
+simple models, not to every model that merely omits `validates`.
+`unlock_expired` is exempt from the validations check because
+`unlock_access!` writes via `update_columns`, which always skips validations,
+so its two paths are already equivalent. On a model that declares any
+validation, five of these verbs (`publish_all`, `unpublish_all`, `expire_all`,
+`activate_all`, `deactivate_all`) instead stream the relation record-by-record
+inside a transaction, calling the same guarded bang/update method a single
+record would use; a record that fails to save raises
+`ActiveRecord::RecordNotSaved` and rolls the **entire batch** back — nothing
+partially commits.
+
+The single-`UPDATE` path writes `updated_at` (`updated_on` too, when present)
+alongside the concern's own column whenever the model has that column and
+`record_timestamps` is on, so the fast and slow paths agree — the same thing
+Rails' `touch_all` and `update_counters(touch:)` do. `unlock_expired` is
+exempt here as well: it mirrors `unlock_access!`, which writes via
+`update_columns` and deliberately does not touch timestamps.
+
+`transition_all` also always takes the per-record path, regardless of
+validators — for the same underlying reason (validations must run) — but its
+failure mode is different, not the same: the per-record path calls the
+guarded `<event>!`, which calls `update!`, and `update!` raises
+`ActiveRecord::RecordInvalid` **directly** on a validation failure. That
+exception propagates straight out of the batch loop, never reaching the
+`RecordNotSaved` branch the other five verbs use. Code that rescues
+`RecordNotSaved` around a `transition_all` call will not catch a failed row —
+rescue `RecordInvalid` there instead.
+
+One residual, deliberate divergence survives on the fast path: like every
+`*_all` method in Rails, the single-UPDATE path does not fire host-defined
+`before_save`/`after_save` callbacks (only the concern's own
+`before_*`/`after_*` lifecycle hooks are checked when deciding whether the
+fast path applies at all). If your model relies on `before_save`/`after_save`
+for side effects, either add a validation (forcing the slow, per-record path)
+or call the bang method in a loop.
+
+### Internal
+- New `Support::Affix` (affixed-name computation, `prefix: true` normalization,
+  and the guarded scope capture/retirement used by the three newly affixable
+  concerns) replaces six duplicated implementations across Activatable,
+  Expirable, Lockable, Anonymizable, Stateable and Storable.
+- New `Support::BatchOps`: the whole fast-path safety decision
+  (`fast_path?` = hooks/bang methods unoverridden AND no declared validations,
+  detected through both `validators` and `_validate_callbacks`), the
+  ownership-only half (`unoverridden?`, for the two concerns whose per-record
+  path writes via `update_column(s)` and so needs no validations gate), the
+  `updated_at`/`updated_on` bulk-write payload helper (`with_timestamps`), and
+  the transactional `find_each` runner. SoftDeletable's `soft_delete_all` /
+  `restore_all` now route through it, so the contract has one definition.
+- Retiring a default-named scope is guarded three ways — the name must have been
+  recorded by the concern, be owned by the class's own singleton, and still be
+  the exact method captured — so a model's own override survives and a parent's
+  scopes are never removed from a subclass (that case raises with a pointer to
+  the parent).
+
 ## 1.26.0 (2026-08-24)
 
 A fixes-and-performance round from a full audit of the 25 model concerns: one privacy bug (Anonymizable left Encryptable blind-index fingerprints queryable after erasure), four silent-misbehavior fixes, five query-count reductions, and three hardening changes. No new concerns. 1173 examples, 0 failures.

data/README.md

@@ -358,6 +358,58 @@ publishable_by :published_at, default_scope: true
 # Article.unscoped reaches everything
 ```
 
+**Bulk operations**
+
+```ruby
+Post.draft.publish_all       # publishes every not-currently-published post; returns the count
+Post.published.unpublish_all # unpublishes every currently-published post; returns the count
+```
+
+Both respect the current relation, return an Integer count, and run in a transaction — a
+record that fails to save raises `ActiveRecord::RecordNotSaved` and rolls the whole batch
+back. With no overridden `before_publish`/`after_publish`/`before_unpublish`/`after_unpublish`/
+`publish!`/`unpublish!` and no validations on the model — neither `validates`/`validates_with`,
+a custom `validate :method`, nor an association's autosave validation (a bare `has_many`
+registers one, so most models with associations take the streaming path) — both collapse to a
+single `UPDATE`, which bumps `updated_at`
+exactly as the per-record path does; otherwise they stream per record through
+`publish!`/`unpublish!` so validations still run.
+
+`publish_all` targets every not-currently-published row — **including scheduled ones**, whose
+future `published_at` it overwrites — so chain `.draft` (`Post.draft.publish_all`) to exclude
+them. Its predicate composes with your own constraint on the publish column, so that chain
+really does leave scheduled rows alone. The flip side of composing: with `default_scope: true`
+the relation is already narrowed to published rows, so a bare `Post.publish_all` matches
+nothing — chain `.draft` or `.unpublished` first (both unscope the column themselves, so the
+chain resolves to the rows you mean).
+
+**Scope-name collisions**
+
+```ruby
+publishable_by :published_at, prefix: :article   # => Article.article_published / .article_draft
+publishable_by :published_at, suffix: :posts     # => Article.published_posts / .draft_posts
+publishable_by :published_at, prefix: true       # => Article.published_at_published / ...
+```
+
+`prefix:`/`suffix:` rename every scope `publishable_by` generates, so a model can include
+Publishable alongside another concern that would otherwise generate a same-named scope
+(SoftDeletable and Activatable also define `.active`, for instance) without one clobbering
+the other. With no affix passed, scope names, the optional default scope, and the emitted
+SQL are all unchanged.
+
+`prefix:`/`suffix:` mean three different things across the gem, depending on the concern:
+- **Scope-name affix** (renames generated scopes) — Activatable, Expirable, Lockable,
+  Stateable, Anonymizable, Publishable, SoftDeletable, Schedulable.
+- **Accessor-name affix** (renames generated reader/writer methods) — Storable.
+- **A literal string prepended to the generated value itself** — Sequenceable's `prefix:`
+  (e.g. `"INV-"`), unrelated to scope/method naming.
+
+Passing `true` for a scope- or accessor-name affix means "use the configured field name"
+(`publishable_by :published_at, prefix: true` → `published_at_published`/`published_at_draft`).
+
+Unrelated to all three: Searchable's `match: :prefix` is a LIKE-match mode (`term%`), not a
+naming affix.
+
 **Notes**
 - "Published" means `published_at` is set **and** in the past — so future-dated posts stay unpublished until their time arrives.
 - No `default_scope` is added by default; chain `.published` explicitly (or opt in with `default_scope: true`).
@@ -412,6 +464,21 @@ collapse to a single `UPDATE`. Note that `really_destroy_all` peels the soft-del
 predicate off the relation, so `only_deleted.really_destroy_all` widens to the whole
 relation — purge trash with `User.soft_deleted.delete_all` instead.
 
+**Scope-name collisions**
+
+```ruby
+soft_deletable_by :deleted_at, prefix: :account   # => .account_active / .account_soft_deleted / ...
+soft_deletable_by :deleted_at, suffix: :records    # => .active_records / .soft_deleted_records / ...
+soft_deletable_by :deleted_at, prefix: true        # => .deleted_at_active / ...
+```
+
+`prefix:`/`suffix:` rename every scope `soft_deletable_by` generates (`active`,
+`without_deleted`, `soft_deleted`, `only_deleted`, `with_deleted`, `deleted_within`), so a
+model can combine SoftDeletable with another concern that also defines `.active` (Activatable,
+Expirable) without a collision. `prefix: true` uses the configured field name. With no affix
+passed, scope names, the default scope, and the emitted SQL are unchanged. See the
+Publishable section above for how `prefix:`/`suffix:` differ across the gem.
+
 **Lifecycle hooks** — override these methods on the model:
 
 ```ruby
@@ -512,6 +579,18 @@ promo.reschedule!(starts_at: 1.day.from_now,
                   ends_at:   2.days.from_now)
 ```
 
+**Scope-name collisions**
+
+```ruby
+schedulable_by prefix: :promo    # => .promo_current / .promo_upcoming / .promo_expired / .promo_active_at
+schedulable_by suffix: :window   # => .current_window / .upcoming_window / .expired_window / .active_at_window
+schedulable_by prefix: true      # => .starts_at_current / ... (the configured starts_at/ends_at field)
+```
+
+`prefix:`/`suffix:` rename every scope `schedulable_by` generates (`active_at`, `current`,
+`upcoming`, `expired`). With no affix passed, scope names and the emitted SQL are unchanged.
+See the Publishable section above for how `prefix:`/`suffix:` differ across the gem.
+
 **Notes**
 - Boundary semantics: **inclusive start, exclusive end** — active at exactly `starts_at`, not at exactly `ends_at`.
 - A `nil` end means "never expires"; a `nil` start means "not yet started".
@@ -552,6 +631,21 @@ token.extend_expiry!(by: 1.day)     # pushes expiry forward
 - If `expires_at` is `nil` or in the past → new value is `now + by`
 - If `expires_at` is still in the future → `by` is added to the existing value
 
+**Bulk operations**
+
+```ruby
+ApiToken.expiring_within(1.day).expire_all   # => 12
+```
+
+`expire_all(time = Time.zone.now)` expires every currently-active record in the relation and
+returns the Integer count, in a transaction. With `expire!` unoverridden and no validations on
+the model — neither `validates`/`validates_with`, a custom `validate :method`, nor an
+association's autosave validation (a bare `has_many` registers one, so most models with
+associations take the streaming path) — it collapses
+to a single `UPDATE`, which bumps `updated_at` exactly as the per-record path does; otherwise it
+streams per record through `expire!` so validations still run, and a record that fails to save
+raises `ActiveRecord::RecordNotSaved` and rolls the whole batch back.
+
 **Custom field name**
 
 ```ruby
@@ -659,6 +753,23 @@ Subscription.active     # WHERE active = TRUE
 Subscription.inactive   # WHERE active = FALSE OR active IS NULL
 ```
 
+**Bulk operations**
+
+```ruby
+Subscription.inactive.activate_all     # => 12
+Subscription.active.deactivate_all     # => 3
+```
+
+Both target the relation, return an Integer count, and run in a transaction. With
+`activate!`/`deactivate!` unoverridden and no validations on the model — neither
+`validates`/`validates_with`, a custom `validate :method`, nor an association's autosave
+validation (a bare `has_many` registers one, so most models with associations take the
+streaming path) — they collapse to a single
+`UPDATE`, which bumps `updated_at` exactly as the per-record path does; otherwise they stream
+per record so validations still run, and a record that fails to save raises
+`ActiveRecord::RecordNotSaved` and rolls the whole batch back. `toggle_active!`'s row lock has
+no batch analogue.
+
 **Notes**
 - `NULL` is treated as inactive (same convention as most apps' "unset = off").
 - The configured column must exist; `activatable_by` raises `ArgumentError` otherwise.
@@ -805,6 +916,18 @@ article.may_publish?           # => true  (guard check without raising)
 article.transition_to!(:archived)  # generic move to any declared state
 ```
 
+**Bulk operations**
+
+```ruby
+Article.draft.transition_all(:publish)   # => 12 — runs :publish across every eligible row
+```
+
+Returns the Integer count of records transitioned, running in a transaction; records the
+guard rejects are skipped (not errors). Unlike every other batch verb in this gem,
+`transition_all` has **no single-UPDATE fast path** — it always streams per record through
+the guarded `<event>!` method, because that path runs validations via `update!` while a bulk
+`update_all` would silently skip them.
+
 **Prefix / suffix** — avoid clashes when the state names overlap with other concerns or scopes:
 
 ```ruby
@@ -1094,10 +1217,21 @@ user.reset_failed_attempts!     # call on successful login
 user.lock_access!               # manual lock     (hooks: before/after_lock)
 user.unlock_access!             # manual unlock   (hooks: before/after_unlock)
 User.locked / User.unlocked     # expiry-aware scopes
+
+User.unlock_expired              # => 3 — unlocks every row whose unlock_in window has elapsed
 ```
 
 **Options**: `attempts:` (`:failed_attempts`, must be an integer column), `locked_at:` (`:locked_at`, datetime column), `max_attempts:` (`5`; `nil` = count but never auto-lock), `unlock_in:` (`nil` = locked until manual unlock; a duration makes the lock lapse by itself), `prefix:` / `suffix:` (affix the scope names).
 
+**Bulk operations**
+
+`unlock_expired` clears `locked_at` and zeroes the attempts counter on every row whose
+`locked_at + unlock_in` has passed, exactly as `unlock_access!` does — returns the Integer
+count, runs in a transaction. Returns `0` without querying when `unlock_in` is `nil` (manual
+unlock only). Because `unlock_access!` persists via `update_columns` (which already skips
+validations), the single-`UPDATE` fast path and the per-record path are equivalent here —
+unlike Publishable/Expirable/Activatable, this one has no validators gate.
+
 **Notes**
 - The increment is SQL-side (`COALESCE(attempts, 0) + 1` via `update_counters`), so concurrent failures never lose updates and a NULL counter needs no column default; a locked account stops counting.
 - Expiry is **lazy**: readers and scopes treat a stale lock as unlocked but never write. The column is cleared by the next `unlock_access!` or failed attempt (quietly there — no unlock hooks fire from a failed login).
@@ -1952,9 +2086,9 @@ Point your agent at `llms.txt` for an overview, or paste a single concern's `.md
 
 ```sh
 bundle install                                  # install dev dependencies
-bundle exec rspec                               # run the test suite (1,173 examples)
+bundle exec rspec                               # run the test suite (1,245 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.26.0.gem      # install locally
+gem install ./concerns_on_rails-1.27.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

data/lib/concerns_on_rails/models/activatable.rb

@@ -1,5 +1,7 @@
 require "active_support/concern"
 require "concerns_on_rails/support/column_guard"
+require "concerns_on_rails/support/affix"
+require "concerns_on_rails/support/batch_ops"
 
 module ConcernsOnRails
   module Models
@@ -26,25 +28,72 @@ module ConcernsOnRails
 
       included do
         class_attribute :activatable_field, instance_accessor: false, default: DEFAULT_FIELD
+        class_attribute :activatable_scope_names, instance_accessor: false,
+                                                  default: { active: :active, inactive: :inactive }.freeze
       end
 
-      class_methods do
+      class_methods do # rubocop:disable Metrics/BlockLength
         include ConcernsOnRails::Support::ColumnGuard
 
         def activatable_by(field = DEFAULT_FIELD, prefix: nil, suffix: nil)
           self.activatable_field = field.to_sym
           ensure_columns!("ConcernsOnRails::Models::Activatable", activatable_field, types: :boolean)
 
+          prefix = ConcernsOnRails::Support::Affix.normalize(prefix, default: activatable_field)
+          suffix = ConcernsOnRails::Support::Affix.normalize(suffix, default: activatable_field)
+          self.activatable_scope_names = {
+            active: ConcernsOnRails::Support::Affix.name(:active, prefix: prefix, suffix: suffix),
+            inactive: ConcernsOnRails::Support::Affix.name(:inactive, prefix: prefix, suffix: suffix)
+          }.freeze
+
           # Affix the scope names so two concerns that each define `.active`
           # (e.g. SoftDeletable / Expirable) can coexist on one model.
-          scope activatable_scope_name(:active, prefix, suffix),   -> { where(activatable_field => true) }
-          scope activatable_scope_name(:inactive, prefix, suffix), -> { where(activatable_field => [false, nil]) }
+          scope activatable_scope_names[:active],   -> { where(activatable_field => true) }
+          scope activatable_scope_names[:inactive], -> { where(activatable_field => [false, nil]) }
+        end
+
+        # Activate every inactive record in the relation; returns the count.
+        def activate_all
+          inactive = all.public_send(activatable_scope_names.fetch(:inactive))
+          if activatable_batch_fast_path?(:activate!)
+            return inactive.update_all(
+              ConcernsOnRails::Support::BatchOps.with_timestamps(self, activatable_field => true)
+            )
+          end
+
+          ConcernsOnRails::Support::BatchOps.run(
+            inactive,
+            label: "ConcernsOnRails::Models::Activatable",
+            message: "failed to activate record",
+            &:activate!
+          )
+        end
+
+        # Deactivate every active record in the relation; returns the count.
+        def deactivate_all
+          active = all.public_send(activatable_scope_names.fetch(:active))
+          if activatable_batch_fast_path?(:deactivate!)
+            return active.update_all(
+              ConcernsOnRails::Support::BatchOps.with_timestamps(self, activatable_field => false)
+            )
+          end
+
+          ConcernsOnRails::Support::BatchOps.run(
+            active,
+            label: "ConcernsOnRails::Models::Activatable",
+            message: "failed to deactivate record",
+            &:deactivate!
+          )
         end
 
         private
 
-        def activatable_scope_name(base, prefix, suffix)
-          [prefix, base, suffix].compact.join("_").to_sym
+        # Whether the single-UPDATE fast path is safe — the whole decision
+        # (bang method unoverridden AND the model declares no validations,
+        # plus why) lives in Support::BatchOps.fast_path?. Activatable defines
+        # no lifecycle hooks, so the bang method is the only one to check.
+        def activatable_batch_fast_path?(method)
+          ConcernsOnRails::Support::BatchOps.fast_path?(self, ConcernsOnRails::Models::Activatable, method)
         end
       end
 

data/lib/concerns_on_rails/models/anonymizable.rb

@@ -1,5 +1,6 @@
 require "active_support/concern"
 require "concerns_on_rails/support/column_guard"
+require "concerns_on_rails/support/affix"
 require "digest"
 require "securerandom"
 
@@ -152,9 +153,12 @@ module ConcernsOnRails
           return if anonymizable_scopes_defined || anonymizable_stamp.nil?
 
           self.anonymizable_scopes_defined = true
-          affixed = ->(base) { [prefix, base, suffix].compact.join("_") }
-          scope affixed.call("anonymized"), -> { where.not(anonymizable_stamp => nil) }
-          scope affixed.call("not_anonymized"), -> { where(anonymizable_stamp => nil) }
+          prefix = ConcernsOnRails::Support::Affix.normalize(prefix, default: anonymizable_stamp)
+          suffix = ConcernsOnRails::Support::Affix.normalize(suffix, default: anonymizable_stamp)
+          scope ConcernsOnRails::Support::Affix.name(:anonymized, prefix: prefix, suffix: suffix),
+                -> { where.not(anonymizable_stamp => nil) }
+          scope ConcernsOnRails::Support::Affix.name(:not_anonymized, prefix: prefix, suffix: suffix),
+                -> { where(anonymizable_stamp => nil) }
         end
       end
 

data/lib/concerns_on_rails/models/expirable.rb

@@ -1,5 +1,7 @@
 require "active_support/concern"
 require "concerns_on_rails/support/column_guard"
+require "concerns_on_rails/support/affix"
+require "concerns_on_rails/support/batch_ops"
 
 module ConcernsOnRails
   module Models
@@ -10,9 +12,12 @@ module ConcernsOnRails
 
       included do
         class_attribute :expirable_field, instance_accessor: false, default: DEFAULT_FIELD
+        class_attribute :expirable_scope_names, instance_accessor: false,
+                                                default: { active: :active, expired: :expired,
+                                                           expiring_within: :expiring_within }.freeze
       end
 
-      class_methods do
+      class_methods do # rubocop:disable Metrics/BlockLength
         include ConcernsOnRails::Support::ColumnGuard
 
         # Configure the expiry column.
@@ -25,29 +30,58 @@ module ConcernsOnRails
           define_expirable_scopes(prefix, suffix)
         end
 
+        # Expire every currently-active record in the relation. Returns the
+        # Integer count. Expirable defines no lifecycle hooks, so this is a
+        # single UPDATE unless the model overrode `expire!` or declares
+        # validations (see Support::BatchOps.fast_path?).
+        def expire_all(time = Time.zone.now)
+          active = all.public_send(expirable_scope_names.fetch(:active))
+          if expirable_batch_fast_path?
+            return active.update_all(
+              ConcernsOnRails::Support::BatchOps.with_timestamps(self, expirable_field => time)
+            )
+          end
+
+          ConcernsOnRails::Support::BatchOps.run(
+            active,
+            label: "ConcernsOnRails::Models::Expirable",
+            message: "failed to expire record"
+          ) { |record| record.expire!(time) }
+        end
+
         private
 
+        # Whether the single-UPDATE fast path is safe — the whole decision
+        # (bang method unoverridden AND the model declares no validations,
+        # plus why) lives in Support::BatchOps.fast_path?. Expirable defines
+        # no lifecycle hooks, so `expire!` is the only method to check.
+        def expirable_batch_fast_path?
+          ConcernsOnRails::Support::BatchOps.fast_path?(self, ConcernsOnRails::Models::Expirable, :expire!)
+        end
+
         # Scopes live here (not in `included do`) so their names can be affixed —
         # letting Expirable's `.active`/`.expired` coexist with the same-named
         # scopes from SoftDeletable / Activatable on a single model.
         def define_expirable_scopes(prefix, suffix)
-          scope expirable_scope_name(:active, prefix, suffix), lambda {
+          prefix = ConcernsOnRails::Support::Affix.normalize(prefix, default: expirable_field)
+          suffix = ConcernsOnRails::Support::Affix.normalize(suffix, default: expirable_field)
+          self.expirable_scope_names = %i[active expired expiring_within].to_h do |base|
+            [base, ConcernsOnRails::Support::Affix.name(base, prefix: prefix, suffix: suffix)]
+          end.freeze
+
+          scope expirable_scope_names[:active], lambda {
             column = arel_table[expirable_field]
             where(column.eq(nil).or(column.gt(Time.zone.now)))
           }
-          scope expirable_scope_name(:expired, prefix, suffix), lambda {
+          scope expirable_scope_names[:expired], lambda {
             where(arel_table[expirable_field].lteq(Time.zone.now))
           }
-          scope expirable_scope_name(:expiring_within, prefix, suffix), lambda { |duration|
+          scope expirable_scope_names[:expiring_within], lambda { |duration|
             column = arel_table[expirable_field]
             now = Time.zone.now
             where(column.gt(now)).where(column.lteq(now + duration))
           }
         end
-
-        def expirable_scope_name(base, prefix, suffix)
-          [prefix, base, suffix].compact.join("_").to_sym
-        end
       end
 
       def active?

data/lib/concerns_on_rails/models/lockable.rb

@@ -1,5 +1,7 @@
 require "active_support/concern"
 require "concerns_on_rails/support/column_guard"
+require "concerns_on_rails/support/affix"
+require "concerns_on_rails/support/batch_ops"
 
 module ConcernsOnRails
   module Models
@@ -59,6 +61,8 @@ module ConcernsOnRails
         class_attribute :lockable_locked_at_field, instance_accessor: false, default: DEFAULT_LOCKED_AT_FIELD
         class_attribute :lockable_max_attempts, instance_accessor: false, default: DEFAULT_MAX_ATTEMPTS
         class_attribute :lockable_unlock_in, instance_accessor: false, default: nil
+        class_attribute :lockable_scope_names, instance_accessor: false,
+                                               default: { locked: :locked, unlocked: :unlocked }.freeze
       end
 
       module ClassMethods
@@ -81,6 +85,39 @@ module ConcernsOnRails
           define_lockable_scopes(prefix, suffix)
         end
 
+        # Unlock every row whose lock window has fully elapsed, clearing
+        # locked_at and zeroing the attempts counter exactly as
+        # unlock_access! does. Returns the Integer count.
+        #
+        # Nothing expires when unlock_in is nil (manual unlock only), so that
+        # case returns 0 without touching the database. The boundary instant
+        # counts as expired, matching lock_expired? and the scopes.
+        def unlock_expired
+          unlock_in = lockable_unlock_in
+          return 0 unless unlock_in
+
+          locked_field = lockable_locked_at_field
+          attempts_field = lockable_attempts_field
+          # `lteq` on a NULL locked_at is NULL, so never-locked rows are
+          # excluded without an extra predicate.
+          expired = all.where(arel_table[locked_field].lteq(Time.zone.now - unlock_in))
+
+          # Ownership-only check (no validations gate, and no updated_at on the
+          # bulk write): `unlock_access!` writes via update_columns, which
+          # already skips validations and timestamps, so the two paths agree.
+          if ConcernsOnRails::Support::BatchOps.unoverridden?(self, ConcernsOnRails::Models::Lockable,
+                                                              :before_unlock, :after_unlock, :unlock_access!)
+            return expired.update_all(locked_field => nil, attempts_field => 0)
+          end
+
+          ConcernsOnRails::Support::BatchOps.run(
+            expired,
+            label: LABEL,
+            message: "failed to unlock record",
+            &:unlock_access!
+          )
+        end
+
         private
 
         def validate_lockable!(attempts, locked_at, max_attempts:, unlock_in:)
@@ -109,7 +146,14 @@ module ConcernsOnRails
         # configuration and compute the cutoff in Ruby at call time, so the
         # predicate stays portable (no adapter-specific SQL date math).
         def define_lockable_scopes(prefix, suffix)
-          scope lockable_scope_name(:locked, prefix, suffix), lambda {
+          prefix = ConcernsOnRails::Support::Affix.normalize(prefix, default: lockable_locked_at_field)
+          suffix = ConcernsOnRails::Support::Affix.normalize(suffix, default: lockable_locked_at_field)
+          self.lockable_scope_names = {
+            locked: ConcernsOnRails::Support::Affix.name(:locked, prefix: prefix, suffix: suffix),
+            unlocked: ConcernsOnRails::Support::Affix.name(:unlocked, prefix: prefix, suffix: suffix)
+          }.freeze
+
+          scope lockable_scope_names[:locked], lambda {
             field = lockable_locked_at_field
             if lockable_unlock_in
               where(arel_table[field].gt(Time.zone.now - lockable_unlock_in))
@@ -117,7 +161,7 @@ module ConcernsOnRails
               where.not(field => nil)
             end
           }
-          scope lockable_scope_name(:unlocked, prefix, suffix), lambda {
+          scope lockable_scope_names[:unlocked], lambda {
             field = lockable_locked_at_field
             if lockable_unlock_in
               column = arel_table[field]
@@ -128,10 +172,6 @@ module ConcernsOnRails
           }
         end
 
-        def lockable_scope_name(base, prefix, suffix)
-          [prefix, base, suffix].compact.join("_").to_sym
-        end
-
         def positive_integer_or_nil?(value)
           value.nil? || (value.is_a?(Integer) && value.positive?)
         end