concerns_on_rails 1.28.4 → 1.28.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 615b4ddcff3ebdffc7e32f618731510bf5e386fa015cb0a1ae958a4e6fb04d1c
-  data.tar.gz: 723b3ae2077f43fc5771947d2e610f011ca83ee8215b78fb0894a04400362220
+  metadata.gz: 5c6fcd158fd0dce6d1744e9ad6be5d921bf283e921e717a8327f04f53e8668f4
+  data.tar.gz: fe3b93a06be3a0cbb4b0e1904a976393b77d24c4075f1d8dccb98e13d3ac6597
 SHA512:
-  metadata.gz: 352ff281ce000213b296a1b8ccae97478d6a6726644fb6bcf69c5f4e05d94c57e674f5cff59f3ed0ff8d90891c90b6ebc53affdec5f47ea64102ca88a3c40a0e
-  data.tar.gz: 595236a2464439aa26d10ed118fc5d307ca47022cac8e5c9cae6077419da39dc7a3fc2d085534bfb2d36bdf3625c99442054dc7fd5868be71b9034923aa66e11
+  metadata.gz: 1a113631bd4810decc66aad97ba5fc9fe8866d92dcfd1ab1908c2cdafe7e990e961c3655933ad124ae8275f1a199c4275a7ba72a06cc172ecf248e2825eb42de
+  data.tar.gz: 7102f8a5cb83e21eabe46066f7a62956adf0950dbe926dc8706c9abd217a87577b6004d625c71d179dc2cf4083dc7fdefd25b47883e1a085fee1ec5bb691b41c

data/CHANGELOG.md

@@ -1,5 +1,65 @@
 <!-- CHANGELOG.md -->
 
+## 1.28.5 (2026-09-17)
+
+Eight feature PRs deepening existing concerns, released as a patch by request:
+no new concerns and no dependency changes, though several add an optional
+column or option. Every PR was reviewed before merge and carries the review's
+fixes; the notes below call out the ones that change a documented behaviour.
+1522 examples, 0 failures.
+
+### Added
+- **Models::Schedulable**: `overlapping(from, to)` scope and `overlaps?`
+  predicate for booking-clash checks. Open-ended windows (a `NULL` start or
+  end), touching intervals, reversed arguments and Range forms behave
+  identically in SQL and in Ruby. Affixable like the other scopes. (#58)
+- **Models::Duplicable**: per-call `only:` / `except:` association selection —
+  `invoice.duplicate!(except: :line_items)`. The macro's list stays the
+  ceiling, so a controller param cannot smuggle in an undeclared association.
+  An explicit `nil` counts as passed, not absent, so an empty checkbox list
+  copies nothing rather than everything. (#73)
+- **Models::Monetizable**: scope-aware `sum_`, `average_`, `minimum_` and
+  `maximum_<name>` aggregates plus their `formatted_` twins, with per-call
+  formatting overrides. BigDecimal throughout; a grouped relation returns a
+  Hash of converted values instead of raising. (#67)
+- **Models::Taggable**: `tag_counts` — tag to record count in one `GROUP BY`
+  query, relation-aware, with `limit:` for the top N. A `select`, `group` or
+  `order` on the relation is stripped; a `limit`/`offset` window is honoured by
+  resolving it to ids first. (#56)
+- **Models::Expirable**: `before_expire` / `after_expire` lifecycle hooks,
+  `expire_in!(duration)` and `clear_expiry!`. The hooks fire when a write
+  actually expires the record; a future time only schedules expiry and fires
+  nothing, so `after_expire { account.downgrade! }` is safe next to
+  `trial.expire_in!(14.days)`. Overriding either hook moves `expire_all` to the
+  per-record path. (#54)
+- **Controllers::SecureHeadable**: HSTS, cross-origin (COOP/COEP/CORP) and
+  Permissions-Policy presets, plus the `:recommended` and
+  `:cross_origin_isolation` bundles. `:recommended` uses `(self)`-scoped
+  permission values, so it denies third-party frames without disabling the
+  app's own camera, microphone, geolocation or Payment Request. HSTS is skipped
+  on a plaintext request (RFC 6797 §7.2) and never overwrites a stricter value
+  already on the response. (#55)
+- **Models::Addressable**: `address_fingerprint` (SHA-256 of the normalized
+  address), `same_address_as?`, `address_parts_changed?` and a `fingerprint:`
+  column option with a `with_address` finder for deduplication reports. The
+  column is stamped in `before_save`, after every `before_validation`, so a
+  sibling concern rewriting a mapped column cannot desync it. (#79)
+- **Controllers::Localizable**: `Content-Language` response header and
+  `Vary: Accept-Language`, both written before the action so a
+  `rescue_from`-rendered error carries them. Rails' own `Vary: Accept` is
+  preserved rather than suppressed, and `Vary` is advertised only when
+  `Accept-Language` can actually change the resolved locale. (#53)
+
+### Notes
+- **Addressable** defines `address_changed?` only when the model has no
+  `address` column of its own, so it never shadows ActiveModel's dirty
+  predicate; `address_parts_changed?` is always available.
+- Existing rows keep a `NULL` address fingerprint until they are re-saved.
+  Backfill with `Model.find_each(&:save)`; `update_columns`, `insert_all` and
+  `upsert_all` bypass callbacks and leave it stale.
+- The address digest is unkeyed, so treat the column as revealing the address.
+  Do not pair it with an `encryptable` address column.
+
 ## 1.28.4 (2026-09-16)
 
 Eleven bug-fix PRs (#91–#101) from the audit of the shipped gem, released as a

data/README.md

@@ -148,7 +148,7 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable), and both load **lazily**: an app that never includes those concerns never loads them. Depends on `activerecord`/`actionpack`/`activesupport`, not the full `rails` meta-gem; controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured columns exist and raises `ArgumentError` early — listing *every* missing column at once, with one ready-to-paste `rails generate migration` command that adds them all
 - **Composable** — concerns are independent; mix and match per model
-- **Tested like an app, not a snippet** — **1,460 RSpec examples** run against a real database on every CI build
+- **Tested like an app, not a snippet** — **1,522 RSpec examples** run against a real database on every CI build
 - **Documented twice** — everything in this README also lives as a per-concern page on the [docs site](https://vsn2015.github.io/concerns_on_rails), searchable and deep-linkable
 
 ---
@@ -601,6 +601,9 @@ Promotion.current                    # WHERE starts_at <= NOW AND (ends_at IS NU
 Promotion.upcoming                   # WHERE starts_at > NOW
 Promotion.expired                    # WHERE ends_at <= NOW
 Promotion.active_at(time)            # active at an arbitrary time
+Promotion.overlapping(from, to)      # windows intersecting [from, to) — clashing bookings, a calendar page
+Promotion.overlapping(from..to)      # Range form; `..` makes the end inclusive; nil on either side = unbounded
+promo.overlaps?(from, to)            # the instance-side predicate
 ```
 
 **Configuration**
@@ -667,13 +670,21 @@ ApiToken.expiring_within(1.day)  # future expiry within the next 1 day
 ```ruby
 token.expire!                       # expires_at = now
 token.expire!(2.hours.from_now)     # explicit time
+token.expire_in!(15.minutes)        # absolute lifetime from now, whatever the current expiry
 token.extend_expiry!(by: 1.day)     # pushes expiry forward
+token.clear_expiry!                 # never expires (nil)
 ```
 
 `extend_expiry!` is smart about the base:
 - 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
 
+**Lifecycle hooks** — override `before_expire` / `after_expire` on the model; they fire around a write that
+actually expires the record (`expire!` with a past-or-now time, and `expire_all`) inside one transaction, so
+a raising `after_expire` rolls the expiry back. A future time only *schedules* expiry, so `expire_in!(14.days)`
+fires nothing — as with renewals (`extend_expiry!`) and `clear_expiry!`. Overriding either hook moves
+`expire_all` from its single `UPDATE` to the per-record path so the hooks run for every row.
+
 **Bulk operations**
 
 ```ruby
@@ -681,7 +692,7 @@ 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
+returns the Integer count, in a transaction. With `expire!` and both hooks 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
@@ -1042,6 +1053,7 @@ end
 | `allow_blank:`    | `false`                              | Per-field opt-out for the length check: an Array of parts (e.g. `%i[line2 state]`), or `true` for all parts. A blank value for an allowed part skips its length check. Independent of `required:`. |
 | `normalize_country:` | `false`                           | When `true`, canonicalize the country to its ISO 3166-1 alpha-2 code: an English name (`"Canada"`, `"United States"`) or a 3-letter alpha-3 (`"CAN"`, `"USA"`) maps to the alpha-2 (`"CA"`, `"US"`); unrecognized values are left untouched. This also lets postal/state validation recognize a named country. |
 | `verify_with:`    | `nil`                                | A callable for real-world verification (see below).                 |
+| `fingerprint:`    | `nil`                                | A `string` column to store `address_fingerprint` in (stamped in `before_validation`, after normalization) so duplicates are one indexed query away: `Location.with_address(record)`. |
 | `if:` / `unless:` | `nil`                                | Standard Rails validation conditions (Symbol, Proc, or Array) gating the address **validations** — e.g. `if: :on_addresses?`. Normalization still runs unconditionally. |
 
 **What it normalizes** (in `before_validation`)
@@ -1065,6 +1077,18 @@ end
 | `String`          | added as a `:base` error                        |
 | `Array`           | each element added as a `:base` error           |
 
+**Dedupe helpers**
+
+```ruby
+loc.address_fingerprint        # => "9f2c…" — SHA-256 of the normalized parts: case, whitespace, postal spacing
+                               #    and a blank country (→ default_country) don't change it; nil for a blank address
+loc.same_address_as?(other)    # fingerprints equal (never true for two blanks)
+loc.address_changed?           # any mapped column dirty (address_parts_changed? when you have an `address` column)
+
+addressable_by fingerprint: :address_fingerprint     # add a string column + index
+Location.with_address(loc).where.not(id: loc.id)     # the duplicates of loc (or pass a fingerprint)
+```
+
 **Notes**
 - Scope is **format/structure only** — it checks shape, not real-world deliverability. Plug a USPS/Google/Smarty client into `verify_with:` for that.
 - Error messages are plain English strings — no host-app i18n setup required.
@@ -1096,6 +1120,7 @@ article.save!
 Article.tagged_with("ruby", "rails")          # records carrying BOTH tags
 Article.tagged_with("ruby", "go", any: true)  # records carrying ANY tag
 Article.all_tags                               # => sorted unique tags in use
+Article.published.tag_counts(limit: 20)        # => { "ruby" => 12, "rails" => 7, ... } — a tag cloud, relation-aware
 ```
 
 **Options**
@@ -1108,7 +1133,8 @@ Article.all_tags                               # => sorted unique tags in use
 **Notes**
 - Matching is **boundary-safe** — searching `rail` does not match `rails`. An explicit SQL `ESCAPE` clause makes tags containing `_` / `%` match literally on every adapter.
 - Tags are normalized in `before_validation`, so a direct `record.tags = "a, b"` assignment is cleaned too. An empty list stores `NULL`.
-- Reach for [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on) when you need tag contexts, ownership, counts/clouds, or polymorphic tags shared across models.
+- `tag_counts` runs one `GROUP BY` on the raw column — identical tag strings ship once with their row count and are split in Ruby — so it scales with distinct tag strings, not rows; ordered by count desc then name, `limit:` keeps the top N.
+- Reach for [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on) when you need tag contexts, ownership, or polymorphic tags shared across models.
 
 ---
 
@@ -1206,9 +1232,17 @@ product.formatted_price # => "$19.99"
 |-------------------|-----------------------------------------------|
 | `price`           | the amount as a `BigDecimal` (cents ÷ 100)    |
 | `price=`          | assign in major units; rounded to whole cents |
-| `formatted_price` | a display string (`"$1,234.56"`)              |
+| `formatted_price` | a display string (`"$1,234.56"`); accepts per-call overrides: `formatted_price(unit: "€", delimiter: ".", separator: ",")` |
 
-**Options**: `as:` (explicit method name — required when the column does not end in `_cents`), `unit:` (`"$"`), `precision:` (`2`), `delimiter:` (`","`), `separator:` (`"."`), `subunit_to_unit:` (`100`). `nil` stays `nil` across all three methods.
+**Aggregates** — class methods that follow the current scope, exact and float-free:
+
+```ruby
+Product.sum_price                      # => BigDecimal   SUM(price_cents) / 100
+Product.in_stock.average_price         # average_ / minimum_ / maximum_ too — nil on an empty set (sum is 0)
+Order.paid.formatted_sum_total         # => "€3.500,50"  every aggregate has a formatted_ twin (overrides accepted)
+```
+
+**Options**: `as:` (explicit method name — required when the column does not end in `_cents`), `unit:` (`"$"`), `precision:` (`2`), `delimiter:` (`","`), `separator:` (`"."`), `subunit_to_unit:` (`100`). `nil` stays `nil` across all the accessors.
 
 ---
 
@@ -1471,6 +1505,8 @@ end
 
 copy = invoice.duplicate                # unsaved deep copy
 copy = invoice.duplicate!(title: "Q3")  # saved (one transaction, autosaved children)
+copy = invoice.duplicate!(except: :line_items)          # this copy skips the line items
+copy = invoice.duplicate!(only: [])                     # shallow copy — attributes only
 ```
 
 **Auto-reset identity columns** (no configuration): `created_at`/`updated_at`, Sluggable slug, Tokenizable/Hashable tokens, Sequenceable sequence + `into:` columns, Auditable trail, SoftDeletable timestamp, Lockable attempts/locked_at. Business state (Publishable, Stateable, …) is a judgment call — list it in `reset:`.
@@ -1479,6 +1515,7 @@ copy = invoice.duplicate!(title: "Q3")  # saved (one transaction, autosaved chil
 
 **Notes**
 - 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.
 - Reach for [`amoeba`](https://github.com/amoeba-rb/amoeba) when you need per-attribute regex/prepend rules or belongs_to graph copying.
 
@@ -1868,6 +1905,9 @@ class ApplicationController < ActionController::Base
   # Preset headers, plus any custom "Header-Name" => "value" pairs:
   secure_headers :nosniff, :sameorigin_frame, :no_referrer_leak, :disable_legacy_xss
   secure_headers "Permissions-Policy" => "geolocation=()"
+  # ...or the break-nothing baseline in one line, then relax what you must (later wins):
+  secure_headers :recommended
+  secure_headers :sameorigin_frame
 
   # Delegates to Rails' native CSP DSL — roll out report-only FIRST:
   content_security_policy_for(report_only: true) do |policy|
@@ -1888,6 +1928,14 @@ 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) |
+| `: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`          |
+| `:no_sensitive_permissions` | `Permissions-Policy` denying camera, microphone, geolocation, payment, usb and motion sensors to everyone, your own pages included |
+| `:self_sensitive_permissions` | The same list scoped to `(self)` — denies third-party frames, keeps first-party use |
+
+**Bundles** (expand to presets in place, so a later preset or custom pair still wins): `:recommended` = nosniff, deny_frame, no_referrer_leak, no_cross_domain, disable_legacy_xss, same_origin_opener_allow_popups, self_sensitive_permissions — deliberately *without* COEP/CORP (they block cross-origin embeds of your resources and CDN assets lacking CORP headers) and HSTS (belongs with `force_ssl`); relax `deny_frame` with `:sameorigin_frame` if the app frames itself; `:cross_origin_isolation` = same_origin_opener + require_corp_embedder + same_origin_resource (what SharedArrayBuffer / high-resolution timers require).
 
 **Notes**
 - Headers are applied in an `after_action`, so they reinforce Rails' middleware defaults; later `secure_headers` declarations win on a colliding name.
@@ -1912,7 +1960,9 @@ end
 
 Resolution order: `params[param]` → first match in `Accept-Language` → `default` → `I18n.default_locale`. The chosen locale is always validated against `I18n.available_locales`, so a stray param or a mismatched `available:` list can never raise `I18n::InvalidLocale`.
 
-**Options**: `available:` (allow-list for matching; defaults to `I18n.available_locales`), `default:`, `param:` (default `:locale`), `header:` (default `true`).
+Every response carries **`Content-Language: <resolved locale>`** (BCP 47 form — `pt_BR` → `pt-BR`) and, when `Accept-Language` is a locale source, **`Vary: Accept-Language`** appended to any existing `Vary` (de-duplicated) so shared caches key on the header. Both are written *before* the action runs, so a `rescue_from`-rendered error still carries them; `response_headers: false` turns them off.
+
+**Options**: `available:` (allow-list for matching; defaults to `I18n.available_locales`), `default:`, `param:` (default `:locale`), `header:` (default `true`), `response_headers:` (default `true`).
 
 ---
 
@@ -2250,9 +2300,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,460 examples)
+bundle exec rspec                               # run the test suite (1,522 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.28.4.gem      # install locally
+gem install ./concerns_on_rails-1.28.5.gem      # install locally
 
 # Preview the docs site locally (GitHub Pages serves docs/ as-is):
 cd docs && python3 -m http.server 8000          # → http://localhost:8000

data/lib/concerns_on_rails/controllers/localizable.rb

@@ -18,9 +18,15 @@ module ConcernsOnRails
     # against `I18n.available_locales` before use, so a stray param or a
     # mismatched `available:` list can never raise `I18n::InvalidLocale`.
     #
+    # Every response carries `Content-Language: <resolved locale>` (BCP 47
+    # form, `pt_BR` → `pt-BR`) and, when the header is a locale source,
+    # `Vary: Accept-Language` appended to any existing Vary — written before
+    # the action runs, so a rescued error still carries them. Both are behind
+    # `response_headers:` (default `true`).
+    #
     # Options: `available:` (allow-list for param/header matching; defaults to
     # `I18n.available_locales`), `default:`, `param:` (default `:locale`),
-    # `header:` (default `true`).
+    # `header:` (default `true`), `response_headers:` (default `true`).
     module Localizable
       extend ActiveSupport::Concern
 
@@ -30,19 +36,23 @@ module ConcernsOnRails
       end
 
       class_methods do
-        def localizable(available: nil, default: nil, param: :locale, header: true)
+        def localizable(available: nil, default: nil, param: :locale, header: true, response_headers: true)
           self.localizable_options = {
             available: available&.map(&:to_sym),
             default: default&.to_sym,
             param: param&.to_sym,
-            header: header
+            header: header,
+            response_headers: response_headers ? true : false
           }
         end
       end
 
-      # Public so subclasses can override; runs the action under the resolved locale.
+      # Public so subclasses can override; writes the response headers, then
+      # runs the action under the resolved locale.
       def switch_locale(&)
-        I18n.with_locale(resolved_locale, &)
+        locale = resolved_locale
+        apply_locale_response_headers(locale)
+        I18n.with_locale(locale, &)
       end
 
       # The locale chosen for this request — always one I18n can switch to.
@@ -60,6 +70,49 @@ module ConcernsOnRails
 
       private
 
+      # Content-Language always; Vary: Accept-Language only when the header can
+      # influence the choice (a param-only setup already differs by URL).
+      # Vary is appended and de-duplicated, never clobbered (Cacheable, the
+      # paginators' Link header — same rule).
+      def apply_locale_response_headers(locale)
+        return unless locale_response_headers?
+
+        response.set_header("Content-Language", locale.to_s.tr("_", "-"))
+        # Only advertise the dimension the resolver actually consults: with
+        # `header: false` (or no `localizable` call at all) Accept-Language
+        # cannot change the answer.
+        append_vary_accept_language if self.class.localizable_options[:header]
+      end
+
+      def locale_response_headers?
+        opts = self.class.localizable_options
+        return false if opts.key?(:response_headers) && !opts[:response_headers]
+
+        respond_to?(:response) && response.respond_to?(:set_header)
+      end
+
+      def append_vary_accept_language
+        existing = response.headers["Vary"].to_s.split(",").map(&:strip).reject(&:empty?)
+        return if existing.include?("*")
+
+        # Rails adds its own `Vary: Accept` during render, but ONLY while the
+        # header is still blank (ActionController::Rendering#_set_vary_header).
+        # Writing ours before the action would therefore SUPPRESS it and cost a
+        # cache dimension, so seed Accept ourselves whenever Rails would have.
+        merged = existing + vary_accept_dimension + ["Accept-Language"]
+        deduped = merged.each_with_object([]) do |value, list|
+          list << value unless list.any? { |seen| seen.casecmp?(value) }
+        end
+        response.set_header("Vary", deduped.join(", "))
+      end
+
+      def vary_accept_dimension
+        return [] unless respond_to?(:request, true) && (req = request)
+        return [] unless req.respond_to?(:should_apply_vary_header?) && req.should_apply_vary_header?
+
+        ["Accept"]
+      end
+
       def locale_from_param(opts, allowed)
         return nil unless opts[:param] && respond_to?(:params) && params
 

data/lib/concerns_on_rails/controllers/secure_headable.rb

@@ -13,6 +13,9 @@ module ConcernsOnRails
     #     # Apply preset headers, plus any custom "Header-Name" => "value" pairs:
     #     secure_headers :nosniff, :sameorigin_frame, :no_referrer_leak, :disable_legacy_xss
     #     secure_headers "Permissions-Policy" => "geolocation=()"
+    #     # ...or the break-nothing baseline in one line, then relax what you must:
+    #     secure_headers :recommended
+    #     secure_headers :sameorigin_frame          # later declarations win
     #
     #     # Delegates to Rails' native CSP DSL — roll out report-only FIRST:
     #     content_security_policy_for(report_only: true) do |policy|
@@ -36,9 +39,32 @@ module ConcernsOnRails
     #   :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
+    #                         (for API-only apps behind a TLS-terminating proxy; when
+    #                         you use force_ssl / config.ssl_options Rails sets it)
+    #   :same_origin_opener              — Cross-Origin-Opener-Policy: same-origin
+    #   :same_origin_opener_allow_popups — Cross-Origin-Opener-Policy: same-origin-allow-popups
+    #                                      (keeps OAuth / payment popups working)
+    #   :require_corp_embedder           — Cross-Origin-Embedder-Policy: require-corp
+    #   :same_origin_resource            — Cross-Origin-Resource-Policy: same-origin
+    #   :no_sensitive_permissions        — Permissions-Policy denying camera, microphone,
+    #                                      geolocation, payment, usb and motion sensors
+    #
+    # Bundles (expand to presets, so a later preset or custom pair still wins):
+    #   :recommended            — nosniff, deny_frame, no_referrer_leak, no_cross_domain,
+    #                             disable_legacy_xss, same_origin_opener_allow_popups,
+    #                             no_sensitive_permissions. Deliberately WITHOUT COEP/CORP
+    #                             (they block cross-origin embeds of your resources and
+    #                             CDN assets without CORP headers) and HSTS (belongs
+    #                             with force_ssl) — the baseline that breaks nothing.
+    #   :cross_origin_isolation — same_origin_opener, require_corp_embedder,
+    #                             same_origin_resource (SharedArrayBuffer / high-res
+    #                             timers need all three).
     module SecureHeadable
       extend ActiveSupport::Concern
 
+      HSTS_HEADER = "Strict-Transport-Security".freeze
+
       # Frozen, string-only header presets, each "Header-Name" => "value".
       # :disable_legacy_xss emits "0" deliberately — the legacy browser XSS
       # auditor was itself exploitable and is gone from modern browsers
@@ -49,8 +75,34 @@ module ConcernsOnRails
         deny_frame: %w[X-Frame-Options DENY],
         no_referrer_leak: %w[Referrer-Policy strict-origin-when-cross-origin],
         no_cross_domain: %w[X-Permitted-Cross-Domain-Policies none],
-        disable_legacy_xss: %w[X-XSS-Protection 0]
-      }.freeze
+        disable_legacy_xss: %w[X-XSS-Protection 0],
+        # One year, subdomains included, no `preload` — the preload list is a
+        # months-long commitment that must be an explicit, custom-pair decision.
+        hsts: ["Strict-Transport-Security", "max-age=31536000; includeSubDomains"],
+        same_origin_opener: %w[Cross-Origin-Opener-Policy same-origin],
+        same_origin_opener_allow_popups: %w[Cross-Origin-Opener-Policy same-origin-allow-popups],
+        require_corp_embedder: %w[Cross-Origin-Embedder-Policy require-corp],
+        same_origin_resource: %w[Cross-Origin-Resource-Policy same-origin],
+        no_sensitive_permissions: ["Permissions-Policy",
+                                   "accelerometer=(), camera=(), geolocation=(), gyroscope=(), " \
+                                   "magnetometer=(), microphone=(), payment=(), usb=()"],
+        # The same list scoped to `(self)`: third-party frames are denied, the
+        # app's own pages keep getting/asking for permission. This is the one
+        # that belongs in a general-purpose bundle -- an empty allowlist denies
+        # the app itself, which silently breaks getUserMedia, geolocation and
+        # Payment Request with only a console warning.
+        self_sensitive_permissions: ["Permissions-Policy",
+                                     "accelerometer=(self), camera=(self), geolocation=(self), gyroscope=(self), " \
+                                     "magnetometer=(self), microphone=(self), payment=(self), usb=(self)"]
+      }.each_value { |pair| pair.each(&:freeze).freeze }.freeze
+
+      # Named sets of presets. Expanded in declaration position, so
+      # `secure_headers :recommended, :sameorigin_frame` relaxes the frame rule.
+      BUNDLES = {
+        cross_origin_isolation: %i[same_origin_opener require_corp_embedder same_origin_resource],
+        recommended: %i[nosniff deny_frame no_referrer_leak no_cross_domain disable_legacy_xss
+                        same_origin_opener_allow_popups self_sensitive_permissions]
+      }.each_value(&:freeze).freeze
 
       included do
         class_attribute :secure_headable_headers, instance_accessor: false, default: {}
@@ -67,14 +119,16 @@ module ConcernsOnRails
       end
 
       class_methods do
-        # Register preset headers (by symbol) plus optional custom
-        # "Header-Name" => "value" pairs. Later declarations win on collision.
+        # Register preset headers (by symbol, bundles expanded in place) plus
+        # optional custom "Header-Name" => "value" pairs. Later declarations —
+        # and later positions within one call — win on collision.
         def secure_headers(*presets, **custom)
-          resolved = presets.to_h do |key|
+          expanded = presets.flat_map { |key| BUNDLES.fetch(key, [key]) }
+          resolved = expanded.to_h do |key|
             PRESETS.fetch(key) do
               raise ArgumentError,
                     "ConcernsOnRails::Controllers::SecureHeadable: unknown preset '#{key}'. " \
-                    "Valid presets: #{PRESETS.keys.join(', ')}"
+                    "Valid presets: #{PRESETS.keys.join(', ')}. Bundles: #{BUNDLES.keys.join(', ')}"
             end
           end
 
@@ -107,7 +161,32 @@ module ConcernsOnRails
       def apply_secure_headers
         return unless respond_to?(:response) && response
 
-        self.class.secure_headable_headers.each { |name, value| response.set_header(name, value) }
+        self.class.secure_headable_headers.each do |name, value|
+          next if secure_headable_skip?(name)
+
+          response.set_header(name, value)
+        end
+      end
+
+      # HSTS is the one preset that is wrong to send unconditionally: RFC 6797
+      # section 7.2 forbids it over plaintext, and overwriting a value the app
+      # already set would silently shorten a longer max-age or drop `preload`.
+      def secure_headable_skip?(name)
+        return false unless name == HSTS_HEADER
+
+        secure_headable_plain_http? || secure_headable_existing_hsts.present?
+      end
+
+      def secure_headable_plain_http?
+        return false unless respond_to?(:request, true) && (req = request)
+
+        req.respond_to?(:ssl?) && !req.ssl?
+      end
+
+      def secure_headable_existing_hsts
+        return response.get_header(HSTS_HEADER) if response.respond_to?(:get_header)
+
+        response.headers[HSTS_HEADER] if response.respond_to?(:headers)
       end
     end
   end

data/lib/concerns_on_rails/models/addressable.rb

@@ -1,4 +1,5 @@
 require "active_support/concern"
+require "digest"
 require "concerns_on_rails/support/column_guard"
 require "concerns_on_rails/support/address_data"
 
@@ -49,10 +50,18 @@ module ConcernsOnRails
         class_attribute :addressable_allow_blank, instance_accessor: false, default: [].freeze
         class_attribute :addressable_normalize_country, instance_accessor: false, default: false
         class_attribute :addressable_validation_registered, instance_accessor: false, default: false
+        class_attribute :addressable_fingerprint_column, instance_accessor: false, default: nil
 
         # `validate :validate_address` is registered by `addressable_by` (not here) so it can
         # carry the optional if:/unless: condition. Normalization always runs.
         before_validation :normalize_address
+        # Stamping is its OWN callback, not a tail call inside normalize_address:
+        # a sibling concern's later before_validation (Normalizable, say) can
+        # still rewrite a mapped column, and a fingerprint computed before that
+        # would disagree with `address_fingerprint` -- leaving `with_address`
+        # unable to find the record itself. before_save also covers
+        # `save(validate: false)`.
+        before_save :stamp_address_fingerprint
       end
 
       # Defined as a real module (not `class_methods do`) so the public macro and
@@ -65,7 +74,7 @@ module ConcernsOnRails
         # keyword pairs; everything else tunes behavior. See the module docs.
         def addressable_by(required: DEFAULT_REQUIRED, default_country: "US",
                            validate_state: false, verify_with: nil,
-                           lengths: {}, allow_blank: false, normalize_country: false, **mapping)
+                           lengths: {}, allow_blank: false, normalize_country: false, fingerprint: nil, **mapping)
           condition = extract_validation_condition!(mapping)
           self.addressable_fields = resolve_addressable_fields(mapping)
           self.addressable_required = Array(required).map(&:to_sym)
@@ -75,12 +84,53 @@ module ConcernsOnRails
           self.addressable_lengths = resolve_lengths(lengths)
           self.addressable_allow_blank = resolve_allow_blank(allow_blank)
           self.addressable_normalize_country = normalize_country
+          self.addressable_fingerprint_column = resolve_fingerprint_column(fingerprint)
           ensure_required_columns!
           register_address_validation(condition)
+          define_address_changed_alias
+        end
+
+        # Records stored with the same address fingerprint as `value` (a record,
+        # or a fingerprint String). Needs `fingerprint:` — the digest has to be
+        # persisted to be queryable. A nil fingerprint (blank address) matches
+        # nothing rather than every other blank row.
+        def with_address(value)
+          column = addressable_fingerprint_column
+          unless column
+            raise ArgumentError,
+                  "#{LABEL}: with_address needs `addressable_by fingerprint:` (a column to store address_fingerprint in)"
+          end
+
+          fingerprint = value.respond_to?(:address_fingerprint) ? value.address_fingerprint : value
+          fingerprint.nil? ? none : where(column => fingerprint)
         end
 
         private
 
+        # `address_changed?` would override ActiveModel's generated predicate on
+        # a model that also carries a plain `address` column -- the legacy-blob
+        # shape apps arrive with -- silently reporting false for a real change.
+        # Define it only when the name is free; `address_parts_changed?` is
+        # always available.
+        def define_address_changed_alias
+          has_address_column = begin
+            column_names.include?("address")
+          rescue StandardError
+            false # schema unreachable (db:create, assets:precompile) -- as ColumnGuard does
+          end
+          return if has_address_column
+
+          alias_method :address_changed?, :address_parts_changed?
+        end
+
+        def resolve_fingerprint_column(fingerprint)
+          return nil if fingerprint.nil?
+
+          column = fingerprint.to_sym
+          ensure_columns!(LABEL, column, types: :string)
+          column
+        end
+
         def resolve_addressable_fields(mapping)
           unknown = mapping.keys.map(&:to_sym) - DEFAULT_FIELDS.keys
           raise ArgumentError, "#{LABEL}: unknown address part(s): #{unknown.join(', ')}" if unknown.any?
@@ -237,8 +287,66 @@ module ConcernsOnRails
         end
       end
 
+      # SHA-256 of the normalized address — every part downcased and squished,
+      # the postal code without spaces, the country resolved the way validation
+      # resolves it (blank → default_country) — so rows that differ only in
+      # case, whitespace, postal formatting or an omitted default country hash
+      # the same. nil for a blank address (a country alone is not an address).
+      def address_fingerprint
+        return nil unless address_fingerprintable?
+
+        parts = DEFAULT_FIELDS.keys.map { |part| address_fingerprint_part(part) }
+        Digest::SHA256.hexdigest(parts.join("\n"))
+      end
+
+      # Equal fingerprints — never true for two blank addresses.
+      def same_address_as?(other)
+        # Tolerant like the sibling `with_address`, which accepts a record, a
+        # digest String or nil: a bare `other.address_fingerprint` turned
+        # `same_address_as?(nil)` into a NoMethodError.
+        return false unless other.respond_to?(:address_fingerprint)
+
+        fingerprint = address_fingerprint
+        !fingerprint.nil? && fingerprint == other.address_fingerprint
+      end
+
+      # Any mapped address column has an unsaved change. `address_changed?` is
+      # the documented spelling, but a model with its own `address` column
+      # already has that method from ActiveModel dirty tracking, so the macro
+      # only aliases it where nothing would be shadowed.
+      def address_parts_changed?
+        self.class.addressable_fields.values.any? { |column| attribute_changed?(column) }
+      end
+
       private
 
+      # Something beyond the country must be present — a country alone is not
+      # an address, and the default country is always "present".
+      def address_fingerprintable?
+        self.class.addressable_fields.any? { |part, column| part != :country && self[column].present? }
+      end
+
+      def address_fingerprint_part(part)
+        column = self.class.addressable_fields[part]
+        return "" unless column
+
+        raw = self[column]
+        return (resolved_country || raw).to_s.squish.downcase if part == :country
+
+        value = raw.to_s.squish.downcase
+        part == :postal_code ? value.delete(" ") : value
+      end
+
+      # Keep the fingerprint column (when configured) in step with the
+      # normalized address; written only when it actually differs.
+      def stamp_address_fingerprint
+        column = self.class.addressable_fingerprint_column
+        return unless column
+
+        fingerprint = address_fingerprint
+        self[column] = fingerprint unless self[column] == fingerprint
+      end
+
       def ordered_parts
         DEFAULT_FIELDS.keys.select { |part| self.class.addressable_fields.key?(part) }
       end

data/lib/concerns_on_rails/models/duplicable.rb

@@ -113,26 +113,57 @@ module ConcernsOnRails
       # Unsaved deep copy: attributes via `dup`, identity columns blanked,
       # `reset:` columns blanked, `suffix:` strings appended, `overrides`
       # assigned, allow-listed associations copied, then `on_duplicate`.
-      def duplicate(overrides = {})
+      #
+      # `only:` / `except:` pick which of the macro's associations THIS copy
+      # carries (`duplicate!(except: :line_items)`; `only: []` is a shallow
+      # copy). An explicit nil counts as passed, not as absent, so
+      # `only: params[:associations]` with nothing checked copies NO
+      # associations rather than silently deep-copying every one. Braceless overrides arrive through **options too (Ruby 3
+      # keyword rules), so `only`/`except` are reserved keys — an attribute
+      # literally named that goes in a braced Hash.
+      def duplicate(overrides = {}, **options)
+        overrides = overrides.merge(options.except(:only, :except))
+        associations = duplicable_selected_associations(options.slice(:only, :except))
+
         copy = dup
         duplicable_reset_attributes(copy)
         duplicable_apply_suffixes(copy)
         overrides.each { |attribute, value| copy.public_send("#{attribute}=", value) }
-        duplicable_copy_associations(copy)
+        duplicable_copy_associations(copy, associations)
         on_duplicate(copy)
         copy
       end
 
       # Persisted deep copy — the copy and its copied children save together
       # (autosave) inside one transaction. Returns the saved copy.
-      def duplicate!(overrides = {})
-        copy = duplicate(overrides)
+      def duplicate!(overrides = {}, **)
+        copy = duplicate(overrides, **)
         transaction { copy.save! }
         copy
       end
 
       private
 
+      # The macro's list is the ceiling: a per-call name outside it raises, so
+      # a controller param can never smuggle in an unvetted association.
+      def duplicable_selected_associations(selection)
+        declared = self.class.duplicable_config[:associations]
+        raise ArgumentError, "#{LABEL}: pass either :only or :except, not both" if selection.size > 1
+        return declared if selection.empty?
+
+        mode, names = selection.first
+        chosen = duplicable_validate_selection!(Array(names).map(&:to_sym), declared)
+        mode == :only ? declared & chosen : declared - chosen
+      end
+
+      def duplicable_validate_selection!(chosen, declared)
+        chosen.each do |name|
+          next if declared.include?(name)
+
+          raise ArgumentError, "#{LABEL}: #{name} is not a duplicable association (declared: #{declared.join(', ')})"
+        end
+      end
+
       def duplicable_reset_attributes(copy)
         (duplicable_auto_reset_columns + self.class.duplicable_config[:reset]).each do |column|
           copy[column] = nil if copy.class.column_names.include?(column.to_s)
@@ -177,8 +208,8 @@ module ConcernsOnRails
         self.class.include?(concern)
       end
 
-      def duplicable_copy_associations(copy)
-        self.class.duplicable_config[:associations].each do |name|
+      def duplicable_copy_associations(copy, associations)
+        associations.each do |name|
           reflection = self.class.reflect_on_association(name)
           case reflection.macro
           when :has_many

data/lib/concerns_on_rails/models/expirable.rb

@@ -31,9 +31,10 @@ module ConcernsOnRails
         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?).
+        # Integer count. A single UPDATE unless the model overrode `expire!`
+        # or a lifecycle hook (before_expire / after_expire), or declares
+        # validations (see Support::BatchOps.fast_path?) — then it streams
+        # per record so the hooks run.
         def expire_all(time = Time.zone.now)
           active = all.public_send(expirable_scope_names.fetch(:active))
           if expirable_batch_fast_path?
@@ -52,11 +53,11 @@ module ConcernsOnRails
         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.
+        # (bang method and hooks unoverridden AND the model declares no
+        # validations, plus why) lives in Support::BatchOps.fast_path?.
         def expirable_batch_fast_path?
-          ConcernsOnRails::Support::BatchOps.fast_path?(self, ConcernsOnRails::Models::Expirable, :expire!)
+          ConcernsOnRails::Support::BatchOps.fast_path?(self, ConcernsOnRails::Models::Expirable,
+                                                        :expire!, :before_expire, :after_expire)
         end
 
         # Scopes live here (not in `included do`) so their names can be affixed —
@@ -96,8 +97,47 @@ module ConcernsOnRails
         value <= Time.zone.now
       end
 
+      # Lifecycle hooks — override in the model. Fired when a write actually
+      # expires the record, i.e. `expire!` with a past-or-now time (and so by
+      # `expire_all`). A FUTURE time only schedules expiry, so it fires
+      # nothing — same as `extend_expiry!` (a renewal) or `clear_expiry!`.
+      # Otherwise `after_expire { account.downgrade! }` paired with
+      # `trial.expire_in!(14.days)` would downgrade the account immediately.
+      # Overriding either hook moves `expire_all` to the per-record path.
+      def before_expire; end
+      def after_expire; end
+
+      # Write the expiry (default: now, i.e. expire immediately). The hooks and
+      # the write share one transaction, so a raising after_expire rolls the
+      # expiry back (SoftDeletable's pattern); a failed write (validation)
+      # returns false and skips after_expire.
       def expire!(time = Time.zone.now)
-        update(self.class.expirable_field => time)
+        hooks = !expirable_scheduled?(time)
+        result = false
+        transaction do
+          before_expire if hooks
+          result = update(self.class.expirable_field => time)
+          after_expire if result && hooks
+        end
+        result
+      end
+
+      # Set an absolute lifetime from now — `token.expire_in!(15.minutes)` —
+      # whatever the current expiry. Sugar for `expire!(now + duration)`, so a
+      # positive duration schedules expiry and fires no hooks.
+      def expire_in!(duration)
+        unless duration.respond_to?(:to_i) && !duration.is_a?(String)
+          raise ArgumentError,
+                "ConcernsOnRails::Models::Expirable: expire_in! takes a duration " \
+                "(e.g. 15.minutes), got #{duration.class}"
+        end
+
+        expire!(Time.zone.now + duration)
+      end
+
+      # Make the record never expire (nil expiry). No hooks: nothing expired.
+      def clear_expiry!
+        update(self.class.expirable_field => nil)
       end
 
       # Push expiry forward by `by:`. If the record has no expiry yet, or has
@@ -127,7 +167,17 @@ module ConcernsOnRails
         now = Time.zone.now
         value.nil? || value <= now ? now : value
       end
-      private :expiry_extension_base
+
+      # A write dated in the future schedules expiry rather than performing it.
+      def expirable_scheduled?(time)
+        return false if time.blank?
+
+        time.to_time > Time.zone.now
+      rescue StandardError
+        false # unparseable input: treat it as an immediate expiry, as before
+      end
+
+      private :expiry_extension_base, :expirable_scheduled?
     end
   end
 end

data/lib/concerns_on_rails/models/monetizable.rb

@@ -28,9 +28,18 @@ module ConcernsOnRails
     # Options: `as:` (explicit method name — required when the column does not
     # end in `_cents`), `unit:` ("$"), `precision:` (2), `delimiter:` (","),
     # `separator:` ("."), `subunit_to_unit:` (100).
+    #
+    # Class-level aggregates come for free and follow the current scope:
+    #   Product.sum_price                        # => BigDecimal, SUM(price_cents) / 100
+    #   Product.in_stock.average_price           # average / minimum / maximum too; nil on empty sets
+    #   Product.formatted_sum_price              # => "$1,234.56" — every aggregate has a formatted_ twin
+    #   product.formatted_price(unit: "€", delimiter: ".", separator: ",")   # per-call display overrides
     module Monetizable
       extend ActiveSupport::Concern
 
+      LABEL = "ConcernsOnRails::Models::Monetizable".freeze
+      AGGREGATES = %i[sum average minimum maximum].freeze
+
       included do
         class_attribute :monetizable_rules, instance_accessor: false, default: {}
       end
@@ -54,15 +63,18 @@ module ConcernsOnRails
 
           ensure_columns!("ConcernsOnRails::Models::Monetizable", fields, types: :integer)
           config = { unit: unit, precision: precision, delimiter: delimiter, separator: separator, subunit_to_unit: subunit_to_unit }
-          fields.each { |cents_field| define_money_accessors(cents_field.to_sym, as, config) }
+          fields.each do |cents_field|
+            name = money_name(cents_field.to_sym, as)
+            define_money_accessors(cents_field.to_sym, name, config)
+            define_money_aggregates(cents_field.to_sym, name, config)
+          end
         end
       end
 
       class_methods do # rubocop:disable Metrics/BlockLength
         private
 
-        def define_money_accessors(cents_field, as, config)
-          name = money_name(cents_field, as)
+        def define_money_accessors(cents_field, name, config)
           subunit = config[:subunit_to_unit]
           self.monetizable_rules = monetizable_rules.merge(cents_field => name)
 
@@ -87,9 +99,27 @@ module ConcernsOnRails
                                 end
           end
 
-          define_method("formatted_#{name}") do
-            cents = self[cents_field]
-            cents.nil? ? nil : ConcernsOnRails::Support::Money.format(cents, config)
+          define_method("formatted_#{name}") do |**overrides|
+            options = ConcernsOnRails::Support::Money.format_options(config, overrides, LABEL)
+            ConcernsOnRails::Support::Money.format_each(self[cents_field], options)
+          end
+        end
+
+        # `sum_price` / `average_price` / `minimum_price` / `maximum_price` and
+        # their `formatted_` twins. Defined on the singleton so a relation
+        # (`Product.in_stock.sum_price`) delegates here inside its scoping;
+        # `public_send(aggregate)` then runs against the current scope.
+        def define_money_aggregates(cents_field, name, config)
+          subunit = config[:subunit_to_unit]
+          AGGREGATES.each do |aggregate|
+            define_singleton_method("#{aggregate}_#{name}") do
+              ConcernsOnRails::Support::Money.decimal(public_send(aggregate, cents_field), subunit)
+            end
+
+            define_singleton_method("formatted_#{aggregate}_#{name}") do |**overrides|
+              options = ConcernsOnRails::Support::Money.format_options(config, overrides, LABEL)
+              ConcernsOnRails::Support::Money.format_each(public_send(aggregate, cents_field), options)
+            end
           end
         end
 

data/lib/concerns_on_rails/models/schedulable.rb

@@ -9,7 +9,7 @@ module ConcernsOnRails
 
       DEFAULT_STARTS_AT_FIELD = :starts_at
       DEFAULT_ENDS_AT_FIELD = :ends_at
-      SCOPE_BASES = %i[active_at current upcoming expired].freeze
+      SCOPE_BASES = %i[active_at current upcoming expired overlapping].freeze
 
       included do
         class_attribute :schedulable_starts_at_field, instance_accessor: false, default: DEFAULT_STARTS_AT_FIELD
@@ -49,8 +49,50 @@ module ConcernsOnRails
                                                   label: "ConcernsOnRails::Models::Schedulable")
         end
 
+        # The relation behind the `overlapping` scope. Public (like
+        # schedulable_window) because scope lambdas resolve methods through the
+        # relation, which cannot reach private class methods.
+        def schedulable_overlapping(from, to = nil)
+          from, to, inclusive_end = schedulable_window(from, to)
+          relation = all
+          relation = schedulable_started_before(relation, to, inclusive_end) if schedulable_starts_at_field
+          relation = schedulable_ending_after(relation, from) if schedulable_ends_at_field && from
+          relation
+        end
+
+        # Normalizes an overlapping/overlaps? window into [from, to,
+        # inclusive_end]: two Times, or one Range (`..` → inclusive end).
+        def schedulable_window(from, to)
+          inclusive_end = false
+          if from.is_a?(Range)
+            raise ArgumentError, "ConcernsOnRails::Models::Schedulable: pass a Range or from/to, not both" unless to.nil?
+
+            inclusive_end = !from.exclude_end?
+            to = from.end
+            from = from.begin
+          end
+          raise ArgumentError, "ConcernsOnRails::Models::Schedulable: from must not be after to" if from && to && from > to
+
+          [from, to, inclusive_end]
+        end
+
         private
 
+        # Started (NULL never overlaps, matching active_at) and, with a `to`,
+        # started before it — or on it for an inclusive Range end.
+        def schedulable_started_before(relation, to, inclusive_end)
+          column = arel_table[schedulable_starts_at_field]
+          return relation.where.not(schedulable_starts_at_field => nil) if to.nil?
+
+          relation.where(inclusive_end ? column.lteq(to) : column.lt(to))
+        end
+
+        # Open-ended, or ending strictly after `from`.
+        def schedulable_ending_after(relation, from)
+          column = arel_table[schedulable_ends_at_field]
+          relation.where(column.eq(nil).or(column.gt(from)))
+        end
+
         # Built here rather than inline in `included do` so the names can be
         # affixed. `current` resolves `active_at` through the names map — a
         # literal call would break under an affix.
@@ -88,6 +130,14 @@ module ConcernsOnRails
 
             where(arel_table[field].lteq(Time.zone.now))
           }
+
+          # Records whose window intersects [from, to) — bookings that clash,
+          # events on a calendar page. Same boundary rules as active_at
+          # (inclusive start, exclusive end): a window that merely touches the
+          # query window does not overlap. Either side may be nil (unbounded);
+          # a Range works too, and `from..to` makes the end inclusive.
+          # Unstarted records (nil starts_at) never overlap, matching active_at.
+          scope schedulable_scope_names[:overlapping], ->(from, to = nil) { schedulable_overlapping(from, to) }
         end
       end # rubocop:enable Metrics/BlockLength
 
@@ -100,6 +150,13 @@ module ConcernsOnRails
         active_at?(Time.zone.now)
       end
 
+      # Does this record's window intersect [from, to)? Mirrors the
+      # `overlapping` scope — boundaries, nil sides and Ranges included.
+      def overlaps?(from, to = nil)
+        from, to, inclusive_end = self.class.schedulable_window(from, to)
+        schedulable_starts_before?(to, inclusive_end) && schedulable_ends_after?(from)
+      end
+
       def upcoming?
         field = self.class.schedulable_starts_at_field
         value = field && self[field]
@@ -169,6 +226,30 @@ module ConcernsOnRails
         value.nil? || value > time
       end
       private :schedulable_not_ended_at?
+
+      # Started (nil = never, matching active_at) and, when `to` is given,
+      # started before it (or on it, for an inclusive Range end).
+      def schedulable_starts_before?(to, inclusive_end)
+        field = self.class.schedulable_starts_at_field
+        return true unless field
+
+        value = self[field]
+        return false if value.nil?
+        return true if to.nil?
+
+        inclusive_end ? value <= to : value < to
+      end
+      private :schedulable_starts_before?
+
+      # Still running at `from` (open-ended or ending strictly after it).
+      def schedulable_ends_after?(from)
+        field = self.class.schedulable_ends_at_field
+        return true unless field && from
+
+        value = self[field]
+        value.nil? || value > from
+      end
+      private :schedulable_ends_after?
     end
   end
 end

data/lib/concerns_on_rails/models/taggable.rb

@@ -24,6 +24,7 @@ module ConcernsOnRails
     #   Article.tagged_with("ruby", "rails")          # records carrying BOTH tags
     #   Article.tagged_with("ruby", "go", any: true)  # records carrying ANY tag
     #   Article.all_tags                               # sorted unique tags in use
+    #   Article.published.tag_counts(limit: 20)        # { "ruby" => 12, "rails" => 7, ... } for a tag cloud
     #
     # Notes:
     #   * Matching is boundary-safe ("rail" does not match "rails").
@@ -32,7 +33,7 @@ module ConcernsOnRails
     #     "a" and "b"), everywhere, so what you read back always matches what
     #     a save would have produced.
     #   * Reach for acts-as-taggable-on when you need tag contexts, ownership,
-    #     tag counts/clouds, or polymorphic tags shared across models.
+    #     or polymorphic tags shared across models.
     module Taggable
       extend ActiveSupport::Concern
 
@@ -92,6 +93,38 @@ module ConcernsOnRails
                .uniq.sort
         end
 
+        # Tag => number of records carrying it, ordered by count desc then tag
+        # asc (a Hash keeps insertion order, so `.first(n)` / `.keys` are the
+        # cloud). Relation-aware: `Article.published.tag_counts`. One GROUP BY
+        # query on the raw column — identical tag strings ship once with their
+        # row count and are split in Ruby, so the cost scales with DISTINCT tag
+        # strings, not rows. `limit:` keeps the top N.
+        def tag_counts(limit: nil)
+          counts = Hash.new(0)
+          taggable_count_scope.where.not(taggable_field => nil)
+                              .group(taggable_field).count.each do |raw, rows|
+            taggable_split(raw).each { |tag| counts[tag] += rows }
+          end
+          ordered = counts.sort_by { |tag, count| [-count, tag] }
+          ordered = ordered.first([limit.to_i, 0].max) if limit
+          ordered.to_h
+        end
+
+        # The rows to tally. A caller's select/group/order cannot survive the
+        # GROUP BY (COUNT(a, b) is invalid SQL, an array group key is
+        # meaningless, and a trailing ORDER BY breaks Postgres), so they are
+        # stripped. limit/offset genuinely pick rows, so they are honoured by
+        # resolving the window to ids first -- MySQL rejects LIMIT inside an
+        # IN subquery, so the ids come back through Ruby. The window is
+        # bounded by definition, so that stays cheap.
+        def taggable_count_scope
+          relation = all
+          base = relation.except(:select, :group)
+          return base.except(:order) unless (relation.limit_value || relation.offset_value) && primary_key
+
+          unscoped.where(primary_key => base.pluck(primary_key))
+        end
+
         # Split a raw stored column value into a normalized tag array.
         def taggable_split(raw)
           taggable_clean_all(raw.to_s.split(taggable_delimiter))

data/lib/concerns_on_rails/support/money.rb

@@ -6,6 +6,8 @@ module ConcernsOnRails
     # string. Pure and stateless; used by Models::Monetizable. Uses BigDecimal
     # throughout so there is no binary-float rounding drift.
     module Money
+      FORMAT_OPTIONS = %i[unit precision delimiter separator subunit_to_unit].freeze
+
       module_function
 
       # format(199999) => "$1,999.99"
@@ -32,6 +34,33 @@ module ConcernsOnRails
         "#{sign}#{unit}#{number}"
       end
 
+      # Merge per-call display overrides into a field's formatting config,
+      # rejecting typos (`units:`) instead of silently ignoring them.
+      def format_options(config, overrides, label)
+        return config if overrides.empty?
+
+        unknown = overrides.keys - FORMAT_OPTIONS
+        raise ArgumentError, "#{label}: unknown formatting option(s): #{unknown.join(', ')}" if unknown.any?
+
+        config.merge(overrides)
+      end
+
+      # Subunits to a BigDecimal amount. A grouped relation's aggregate is a
+      # Hash keyed by the GROUP BY value, so map over it rather than feeding
+      # the whole Hash to BigDecimal().
+      def decimal(cents, subunit)
+        return cents.transform_values { |value| decimal(value, subunit) } if cents.is_a?(Hash)
+
+        cents.nil? ? nil : BigDecimal(cents.to_s) / subunit
+      end
+
+      # format() that is likewise grouped-relation aware and nil-safe.
+      def format_each(cents, options)
+        return cents.transform_values { |value| format_each(value, options) } if cents.is_a?(Hash)
+
+        cents.nil? ? nil : format(cents, options)
+      end
+
       # Insert the thousands delimiter into a non-negative integer string.
       # Single lookahead pass — the old reverse/gsub/reverse allocated three
       # strings per formatted amount.

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.28.4".freeze
+  VERSION = "1.28.5".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.28.4
+  version: 1.28.5
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-16 00:00:00.000000000 Z
+date: 2026-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack