concerns_on_rails 1.22.0 → 1.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7414e40bd04fc80a1b87b4c27b908ff169c5a9c2f9c50e66d8ab8d75198b9f40
-  data.tar.gz: 6f458ab30c720e633cd50f34515b7941ec9b6b8a8ef208f3beed909860ac1d9f
+  metadata.gz: ba3e5dc1bc6af51ec2bd4e29946973c5fc68736d4c1994fdbd472874f965c4bc
+  data.tar.gz: 16b2372635abe33484efabcae5407d1debe5a0627df9df0496a04e930c46ec65
 SHA512:
-  metadata.gz: dbbcf38ca1645b801c05e8949f869e587752607bb0d679c279eeac2bc8904c446d7da7ee865498b8578ca5d1d8212477b60cb840d0e3c53e1a1d9593065805af
-  data.tar.gz: 524c14d7bd3e5824c0d266a3ab84e13cd21d622d7637dc4bde38225ff40e88d24559eb36055c16eaa60edb53b99c025c96effa4a458e1701b36a0826bd8a12b5
+  metadata.gz: 8a159b0026bca1ebc72dbc11c45e875caaa19ad2ec0615ee658abd5b3e8ab53e0bb309d816a5371ddba6bad5c609b82a76228e66d678d3346d624021634eddf5
+  data.tar.gz: da89fb098f9e17fd9ae49662efdb027efb64958007bf790ee895c0faf39a1c9f2cb76d2e95a4b0b3b075bcb404fe926c36d970f78ca152bdd287be81e7a3a991

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 <!-- CHANGELOG.md -->
 
+## 1.23.0 (2026-07-26)
+
+Two new model concerns — the roadmap picks after 1.22's fixes round: the right-to-erasure capability that completes the sensitive-data suite, and the concern-aware deep copy that makes "duplicate this invoice" safe next to unique slugs, tokens, and sequence numbers. 1075 examples, 0 failures.
+
+### Added
+- **Models::Anonymizable**: declarative right-to-erasure ("GDPR-lite") for personal data — the fourth member of the sensitive-data suite (Maskable masks display, Sanitizable strips HTML, Encryptable protects at rest; Anonymizable DESTROYS). `anonymizable *fields, with:` declares an erasure strategy per field group (repeatable; rules merge): presets `:nullify`, `:redact`, `:hash` (SHA-256 — deterministic pseudonymization, joins keep working), `:email` (random unique `anon-…@anonymized.invalid`, so NOT NULL + unique email columns survive erasure), `:random_hex`, or a callable (`->(value)` / `->(value, record)`); presets pass nil through untouched. `anonymize!` runs `before_anonymize` + ONE `update_columns` UPDATE + `after_anonymize` in a single transaction — deliberately skipping validations (erasure must not be blocked by a presence check) and callbacks (nothing may copy the old values elsewhere; Auditable's capture hook is the canonical example) — then reloads. Values serialize through the model's attribute types, so a field that is also `encryptable` stores a fresh ciphertext envelope of the anonymized value, never plaintext (spec-verified). When an erased field is also `auditable_by`, the audit column (which holds its plaintext history) is cleared in the same UPDATE (`clear_audit_trail: false` opts out). `stamp:` column (default `:anonymized_at`; `false` opts out) powers `anonymized?`, the `anonymized`/`not_anonymized` scopes (affixable via `prefix:`/`suffix:`), and the idempotent batch `anonymize_all!` (Integer count, skips stamped records — the 1.22 batch contract). Macro-time `ArgumentError` validation for fields, presets, callables, and columns. Zero new dependencies.
+- **Models::Duplicable**: concern-aware deep copy ("clone this invoice/template"). A bare AR `dup` copies identity-bearing columns — slug, API token, invoice number, audit trail, even `created_at` (which AR preserves on save when present) — so naive copies collide with unique indexes or lie about their history. `duplicate` (unsaved) / `duplicate!(overrides)` (saved, one transaction, autosaved children) blank exactly those columns automatically: timestamps, Sluggable's slug, Tokenizable/Hashable columns, Sequenceable sequence + `into:` columns, Auditable's trail (the copy inherits no history; its own creation is then audited normally), SoftDeletable's timestamp (a copy of trash is live), and Lockable's attempts (0) / locked_at (nil) — each concern regenerates fresh values on the copy's save. Business state (Publishable/Stateable/…) is deliberately NOT auto-reset — list it in `reset:`. `duplicable_by associations:, reset:, suffix:` (optional — bare include works): the association allow-list is validated at macro time (declared-before, the CounterCacheable convention); `has_many`/`has_one` children deep-copy — a child whose class also includes Duplicable copies via ITS OWN rules, so nested graphs stay declarative; `has_and_belongs_to_many` re-links the same records; `belongs_to` and `has_many :through` are rejected with explanations. `suffix: { title: " (copy)" }` appends to present values; `on_duplicate(copy)` is the override hook. Zero new dependencies.
+
+### Internal
+- Top-level aliases `ConcernsOnRails::Anonymizable` / `ConcernsOnRails::Duplicable` registered alongside the existing set; docs site pages + registry entries added for both concerns.
+
 ## 1.22.0 (2026-07-26)
 
 A fixes-and-optimizations release driven by a full-library review of all 40 concerns: one data-loss bug, three request-crashing 500s verified through real ActionController dispatch, security headers restored on rescued error responses, a fail-open authorization path closed, and the gem's largest performance defect (unmemoized PBKDF2 per encrypted-value access) eliminated. 1031 examples, 0 failures.

data/README.md

@@ -66,6 +66,8 @@ Article.published.without_deleted.find("hello-world")
 | [⚙️ Storable](#-storable) | Typed accessors over one JSON column ("store_attribute-lite") |
 | [🧮 CounterCacheable](#-countercacheable) | Conditional denormalized counters ("counter_culture-lite") |
 | [🔏 Encryptable](#-encryptable) | Transparent field encryption (AES-256-GCM) + blind-index lookups |
+| [🕵️ Anonymizable](#-anonymizable) | GDPR right-to-erasure with per-field strategies |
+| [🧬 Duplicable](#-duplicable) | Concern-aware deep copy ("clone this invoice") |
 
 ### 🎮 Controller concerns
 
@@ -92,7 +94,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Twenty-four model concerns + sixteen controller concerns**, all production-ready
+- **Twenty-six model concerns + sixteen controller concerns**, all production-ready
 - **One include, one macro** — no boilerplate, no glue code
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable); controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early
@@ -105,7 +107,7 @@ Article.published.without_deleted.find("hello-world")
 Add to your application's `Gemfile`:
 
 ```ruby
-gem "concerns_on_rails", "~> 1.22"
+gem "concerns_on_rails", "~> 1.23"
 ```
 
 Or pull the latest from GitHub:
@@ -1167,6 +1169,66 @@ Patient.where_email("a@b.com")       # chainable Relation (accepts arrays too)
 
 ---
 
+## 🕵️ Anonymizable
+
+Declarative right-to-erasure ("GDPR-lite"): each personal-data field gets an erasure strategy, and `anonymize!` rewrites them all in **one UPDATE** while stamping `anonymized_at`. Completes the sensitive-data suite — Maskable masks *display*, Sanitizable strips *HTML*, Encryptable protects *at rest*; Anonymizable **destroys**.
+
+```ruby
+class User < ApplicationRecord
+  include ConcernsOnRails::Models::Anonymizable
+
+  anonymizable :email, with: :email                 # unique fake address
+  anonymizable :first_name, :last_name, with: :redact
+  anonymizable :ssn, with: :nullify
+  anonymizable :bio, with: ->(value) { value && "removed by user request" }
+end
+
+user.anonymize!                    # hooks + single UPDATE + stamp, in one transaction
+user.anonymized?                   # => true
+User.not_anonymized                # scope (and .anonymized)
+User.where(...).anonymize_all!     # batch; returns the count, skips stamped records
+```
+
+**Strategies** (`with:`): `:nullify`, `:redact` (`"[REDACTED]"`), `:hash` (SHA-256 — deterministic *pseudonymization*, joins keep working), `:email` (random unique `anon-…@anonymized.invalid`, so NOT NULL + unique email columns survive), `:random_hex`, or a callable (`->(value)` / `->(value, record)`). Presets pass `nil` through untouched.
+
+**Options** (repeatable; field rules merge): `stamp:` (default `:anonymized_at`; `false` disables stamping + scopes), `clear_audit_trail:` (default `true` — when an erased field is also `auditable_by`, the trail holding its plaintext history is cleared in the same UPDATE), `prefix:`/`suffix:` (scope names).
+
+**Notes**
+- Deliberately `update_columns`: erasure is never blocked by validations and never runs callbacks that could copy old values elsewhere. Values still serialize through the attribute types, so an `encryptable` field stores a fresh ciphertext envelope — never plaintext.
+- `before_anonymize`/`after_anonymize` hooks run inside the transaction; the record reloads afterwards (erasure is terminal for the instance).
+- `:hash` is pseudonymization — use `:nullify`/`:random_hex` for true erasure. Backups/replicas/logs are out of scope.
+
+---
+
+## 🧬 Duplicable
+
+Concern-aware deep copy — the "clone this invoice / duplicate this template" feature. A bare `dup` copies identity-bearing columns (slug, token, invoice number, audit trail, even `created_at`, which AR preserves on save), so naive copies collide with unique indexes. Duplicable blanks exactly those columns and lets each sibling concern regenerate fresh values on save.
+
+```ruby
+class Invoice < ApplicationRecord
+  include ConcernsOnRails::Models::Duplicable
+
+  has_many :line_items
+  duplicable_by associations: %i[line_items],
+                reset: %i[issued_at],
+                suffix: { title: " (copy)" }
+end
+
+copy = invoice.duplicate                # unsaved deep copy
+copy = invoice.duplicate!(title: "Q3")  # saved (one transaction, autosaved children)
+```
+
+**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:`.
+
+**Associations** (`associations:` allow-list, declared before the macro, validated at macro time): `has_many`/`has_one` children are deep-copied — a child that also includes Duplicable copies via **its own** rules, so nested graphs stay declarative; `has_and_belongs_to_many` re-links the *same* records; `belongs_to` and `has_many :through` are rejected with an explanation.
+
+**Notes**
+- The macro is optional — bare `include` gives `duplicate`/`duplicate!` with the auto resets.
+- 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.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -1739,6 +1801,7 @@ Both forms reference the same module, so you can freely mix them.
 | Full-text search with ranking / stemming | [`pg_search`](https://github.com/Casecommons/pg_search) / Elasticsearch |
 | Versioned audit trails with undo/reify, who-dunnit queries, or association tracking | [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) / [`audited`](https://github.com/collectiveidea/audited) |
 | Field encryption with managed key rotation / Rails-native key infrastructure | [`lockbox`](https://github.com/ankane/lockbox) / Rails 7+ native `encrypts` |
+| Deep clone with per-attribute regex/prepend rules or belongs_to graph copying | [`amoeba`](https://github.com/amoeba-rb/amoeba) |
 
 `Sluggable` wraps [`friendly_id`](https://github.com/norman/friendly_id) and `Sortable` wraps [`acts_as_list`](https://github.com/brendon/acts_as_list), so you get those leaders' engines behind the declarative macro.
 
@@ -1750,7 +1813,7 @@ Both forms reference the same module, so you can freely mix them.
 bundle install                                  # install dev dependencies
 bundle exec rspec                               # run the test suite
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.22.0.gem      # install locally
+gem install ./concerns_on_rails-1.23.0.gem      # install locally
 ```
 
 The test suite uses an in-memory SQLite database and a lightweight `FakeController` harness for controller-concern specs — no Rails routes or boot required.

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -26,4 +26,6 @@ module ConcernsOnRails
   Storable      = Models::Storable
   CounterCacheable = Models::CounterCacheable
   Encryptable = Models::Encryptable
+  Anonymizable = Models::Anonymizable
+  Duplicable = Models::Duplicable
 end

data/lib/concerns_on_rails/models/anonymizable.rb

@@ -0,0 +1,218 @@
+require "active_support/concern"
+require "concerns_on_rails/support/column_guard"
+require "digest"
+require "securerandom"
+
+module ConcernsOnRails
+  module Models
+    # Declarative right-to-erasure ("GDPR-lite") for personal data. The fourth
+    # member of the sensitive-data suite: Maskable masks *display*, Sanitizable
+    # strips *HTML*, Encryptable protects *at rest* — Anonymizable DESTROYS.
+    #
+    #   class User < ApplicationRecord
+    #     include ConcernsOnRails::Models::Anonymizable
+    #
+    #     anonymizable :email, with: :email                 # unique fake address
+    #     anonymizable :first_name, :last_name, with: :redact
+    #     anonymizable :ssn, with: :nullify
+    #     anonymizable :bio, with: ->(value) { value && "removed by user request" }
+    #   end
+    #
+    #   user.anonymize!        # one UPDATE: strategies + anonymized_at stamp
+    #   user.anonymized?       # => true
+    #   User.not_anonymized    # scope (and .anonymized)
+    #   User.where(...).anonymize_all!   # batch; returns the count
+    #
+    # HOW IT WRITES — deliberately update_columns (single UPDATE, no
+    # validations, no callbacks): erasure must not be blocked by a presence/
+    # format validation, and must not run callbacks that would copy the OLD
+    # values somewhere new (Auditable's capture hook is the canonical example).
+    # update_columns serializes each value through the model's attribute types
+    # — Encryptable's custom type included — so a field that is also
+    # `encryptable` stores a fresh ciphertext envelope of the anonymized
+    # value, never plaintext. The record is reloaded afterwards so in-memory
+    # readers see the anonymized values through the types.
+    #
+    # Strategy presets (`with:`):
+    #   :nullify    — nil
+    #   :redact     — "[REDACTED]"
+    #   :hash       — SHA-256 hex of the value (deterministic pseudonymization:
+    #                 the same input digests the same, so datasets keyed on the
+    #                 value still join — NOT full anonymization)
+    #   :email      — "anon-<random-hex>@anonymized.invalid" (random + unique,
+    #                 so NOT NULL / unique-index email columns survive erasure;
+    #                 .invalid is an RFC 2606 reserved TLD — it can never send)
+    #   :random_hex — 32 random hex chars (unique tokens/usernames)
+    #   a callable  — ->(value) { ... } or ->(value, record) { ... }; nil-in
+    #                 nil-out is the preset convention, custom callables choose
+    #
+    # Notes:
+    #   * The stamp column (default :anonymized_at, `stamp: false` to opt out)
+    #     is what makes `anonymized?`, the scopes, and anonymize_all!'s
+    #     idempotency work — add it (a datetime) unless you truly can't.
+    #   * Auditable interaction: if any anonymized field is also audited, the
+    #     trail already holds historical plaintext, so anonymize! clears the
+    #     audit column in the SAME update (opt out per-macro with
+    #     `clear_audit_trail: false`). The trail is one column — clearing is
+    #     all-or-nothing.
+    #   * Encryptable interaction: works transparently (see HOW IT WRITES).
+    #   * Erasure is terminal: unsaved changes on the instance are discarded by
+    #     the post-write reload.
+    module Anonymizable
+      extend ActiveSupport::Concern
+
+      LABEL = "ConcernsOnRails::Models::Anonymizable".freeze
+      DEFAULT_STAMP = :anonymized_at
+      # Distinguishes "option not passed" from an explicit value, so repeat
+      # macro calls merge fields without silently resetting earlier options.
+      UNSET = Object.new
+
+      PRESETS = {
+        nullify: ->(_value) {},
+        redact: ->(value) { value.nil? ? nil : "[REDACTED]" },
+        hash: ->(value) { value.nil? ? nil : Digest::SHA256.hexdigest(value.to_s) },
+        email: ->(value) { value.nil? ? nil : "anon-#{SecureRandom.hex(10)}@anonymized.invalid" },
+        random_hex: ->(value) { value.nil? ? nil : SecureRandom.hex(16) }
+      }.freeze
+
+      included do
+        class_attribute :anonymizable_rules, instance_accessor: false, default: {}
+        class_attribute :anonymizable_stamp, instance_accessor: false, default: DEFAULT_STAMP
+        class_attribute :anonymizable_clear_audit, instance_accessor: false, default: true
+        class_attribute :anonymizable_scopes_defined, instance_accessor: false, default: false
+      end
+
+      module ClassMethods
+        include ConcernsOnRails::Support::ColumnGuard
+
+        # Declare fields and their erasure strategy. Repeatable — field rules
+        # merge across calls; stamp:/clear_audit_trail:/prefix:/suffix: apply
+        # only when explicitly passed (last explicit value wins).
+        def anonymizable(*fields, with:, stamp: UNSET, clear_audit_trail: UNSET, prefix: nil, suffix: nil)
+          raise ArgumentError, "#{LABEL}: at least one field is required" if fields.empty?
+
+          strategy = anonymizable_resolve_strategy(with)
+          anonymizable_apply_options(stamp, clear_audit_trail)
+
+          ensure_columns!(LABEL, fields)
+          ensure_columns!(LABEL, anonymizable_stamp) if anonymizable_stamp
+          self.anonymizable_rules = anonymizable_rules.merge(fields.to_h { |f| [f.to_sym, strategy] })
+
+          anonymizable_define_scopes(prefix, suffix)
+        end
+
+        # Anonymize every matching record that isn't already stamped, in one
+        # transaction. Returns the Integer count of records anonymized (the
+        # 1.22 batch contract). Without a stamp column every record matches.
+        def anonymize_all!
+          transaction do
+            all.to_a.count do |record|
+              next false if record.anonymized?
+
+              record.anonymize!
+              true
+            end
+          end
+        end
+
+        private
+
+        def anonymizable_apply_options(stamp, clear_audit_trail)
+          # `.presence` (not `&.`): `stamp: false` must resolve to nil, and
+          # false&.to_sym would raise.
+          self.anonymizable_stamp = stamp.presence && stamp.to_sym unless stamp.equal?(UNSET)
+          return if clear_audit_trail.equal?(UNSET)
+
+          self.anonymizable_clear_audit = clear_audit_trail ? true : false
+        end
+
+        def anonymizable_resolve_strategy(with)
+          case with
+          when Symbol
+            PRESETS.fetch(with) do
+              raise ArgumentError, "#{LABEL}: unknown preset '#{with}'. Valid presets: #{PRESETS.keys.join(', ')}"
+            end
+          else
+            raise ArgumentError, "#{LABEL}: :with must be a preset symbol or a callable, got #{with.class}" unless with.respond_to?(:call)
+
+            with
+          end
+        end
+
+        # Scopes read the class attribute lazily, so later stamp changes take
+        # effect; defined once (affixes come from the first defining call).
+        def anonymizable_define_scopes(prefix, suffix)
+          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) }
+        end
+      end
+
+      # Lifecycle hooks — override in the model. Run inside the anonymize!
+      # transaction, so a raising hook rolls the erasure back.
+      def before_anonymize; end
+      def after_anonymize; end
+
+      # Erase the configured fields in a single UPDATE (see the module docs for
+      # why validations and callbacks are deliberately skipped). Returns true.
+      def anonymize!
+        raise ArgumentError, "#{LABEL}: anonymize! cannot be called on a new record" if new_record?
+
+        payload = anonymizable_payload
+        transaction do
+          before_anonymize
+          update_columns(payload)
+          after_anonymize
+        end
+        # update_columns leaves DB-serialized values (e.g. ciphertext) in the
+        # in-memory attributes; reload so readers decode through the types.
+        reload
+        true
+      end
+
+      # True when the stamp column is set; always false with `stamp: false`
+      # (there is nothing to observe).
+      def anonymized?
+        stamp = self.class.anonymizable_stamp
+        stamp ? self[stamp].present? : false
+      end
+
+      private
+
+      # { column => value }: strategy output cast through the attribute's type,
+      # plus the stamp and — when an anonymized field is also audited — the
+      # cleared audit column. update_columns serializes each value through the
+      # model's attribute types (verified: Encryptable's custom type included),
+      # so an encrypted field stores a fresh ciphertext envelope — passing a
+      # pre-serialized value here would double-encrypt.
+      def anonymizable_payload
+        payload = {}
+        self.class.anonymizable_rules.each do |field, strategy|
+          value = anonymizable_apply_strategy(strategy, public_send(field))
+          payload[field] = self.class.type_for_attribute(field.to_s).cast(value)
+        end
+        stamp = self.class.anonymizable_stamp
+        payload[stamp] = Time.zone.now if stamp
+        payload[self.class.auditable_into] = nil if anonymizable_clear_audit_column?
+        payload
+      end
+
+      def anonymizable_apply_strategy(strategy, value)
+        strategy.arity == 1 ? strategy.call(value) : strategy.call(value, self)
+      end
+
+      # The audit trail holds historical plaintext of tracked fields; when any
+      # of them is being erased, the trail must go too (see module docs).
+      def anonymizable_clear_audit_column?
+        return false unless self.class.anonymizable_clear_audit
+        return false unless self.class.respond_to?(:auditable_fields)
+
+        tracked = Array(self.class.auditable_fields).map(&:to_sym)
+        self.class.anonymizable_rules.keys.intersect?(tracked)
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/models/duplicable.rb

@@ -0,0 +1,207 @@
+require "active_support/concern"
+require "concerns_on_rails/support/column_guard"
+
+module ConcernsOnRails
+  module Models
+    # Concern-aware deep copy ("clone this invoice/template"). A bare
+    # ActiveRecord `dup` copies identity-bearing columns — the slug, the API
+    # token, the invoice number, the audit trail, even `created_at` (which AR
+    # preserves on save when present) — so naive copies collide with unique
+    # indexes or lie about their history. Duplicable knows its sibling
+    # concerns and blanks exactly those columns, letting each concern
+    # regenerate fresh values on save.
+    #
+    #   class Invoice < ApplicationRecord
+    #     include ConcernsOnRails::Models::Duplicable
+    #     include ConcernsOnRails::Models::Sequenceable
+    #
+    #     has_many :line_items
+    #     sequenceable_by :sequence, into: :number, prefix: "INV-"
+    #     duplicable_by associations: %i[line_items],
+    #                   reset: %i[issued_at],
+    #                   suffix: { title: " (copy)" }
+    #   end
+    #
+    #   copy = invoice.duplicate                  # unsaved deep copy
+    #   copy = invoice.duplicate!(title: "Q3")    # saved, with overrides
+    #
+    # What gets blanked automatically (identity, not business state):
+    #   * created_at / updated_at (AR keeps a present created_at on save)
+    #   * Sluggable slug — regenerated from the source field on save
+    #   * Tokenizable / Hashable columns — regenerated on create
+    #   * Sequenceable sequence + into: columns — next number on create
+    #   * Auditable trail column — a copy inherits no history (its own
+    #     creation is then audited normally, like any create)
+    #   * SoftDeletable timestamp — a copy of trash is a live record
+    #   * Lockable attempts (0) / locked_at (nil) — a copy starts unlocked
+    # Business state (Publishable/Stateable/Activatable/...) is a judgment
+    # call, so it is NOT auto-reset — list those columns in `reset:`.
+    #
+    # Associations (`associations:` allow-list, declared before the macro):
+    #   * has_many / has_one — children are deep-copied. A child whose class
+    #     also includes Duplicable is copied via ITS OWN `duplicate` (own
+    #     resets, own nested associations) — recursive graphs stay declarative.
+    #   * has_and_belongs_to_many — the copy links to the SAME records (join
+    #     rows are duplicated, the associated records are not).
+    #   * has_many :through — rejected; duplicate the direct association.
+    #   * belongs_to — rejected; a copy shares its parent by keeping the FK.
+    #
+    # `duplicate` returns an UNSAVED record with unsaved children (persisted
+    # together by `duplicate!` / `save!` via autosave). Override
+    # `on_duplicate(copy)` for custom tweaks — it runs last, before return.
+    module Duplicable
+      extend ActiveSupport::Concern
+
+      LABEL = "ConcernsOnRails::Models::Duplicable".freeze
+      SUPPORTED_MACROS = %i[has_many has_one has_and_belongs_to_many].freeze
+      TIMESTAMP_COLUMNS = %w[created_at updated_at].freeze
+
+      included do
+        class_attribute :duplicable_config, instance_accessor: false,
+                                            default: { associations: [], reset: [], suffix: {} }.freeze
+      end
+
+      module ClassMethods
+        include ConcernsOnRails::Support::ColumnGuard
+
+        # Configure the copy rules. Optional — `duplicate` works with bare
+        # `include` (attribute copy + the automatic identity resets).
+        def duplicable_by(associations: [], reset: [], suffix: {})
+          associations = Array(associations).map(&:to_sym)
+          reset = Array(reset).map(&:to_sym)
+          suffix = suffix.to_h { |field, text| [field.to_sym, text.to_s] }
+
+          duplicable_validate_associations!(associations)
+          ensure_columns!(LABEL, reset) unless reset.empty?
+          ensure_columns!(LABEL, suffix.keys) unless suffix.empty?
+
+          self.duplicable_config = { associations: associations, reset: reset, suffix: suffix }.freeze
+        end
+
+        private
+
+        def duplicable_validate_associations!(names)
+          names.each do |name|
+            reflection = reflect_on_association(name)
+            if reflection.nil?
+              raise ArgumentError,
+                    "#{LABEL}: no association `#{name}` — declare it before `duplicable_by` " \
+                    "(the CounterCacheable convention)"
+            end
+            duplicable_validate_reflection!(name, reflection)
+          end
+        end
+
+        def duplicable_validate_reflection!(name, reflection)
+          if reflection.through_reflection
+            raise ArgumentError,
+                  "#{LABEL}: `#{name}` is a has_many :through association — duplicate the direct " \
+                  "association instead (the through rows follow from it)"
+          end
+          return if SUPPORTED_MACROS.include?(reflection.macro)
+
+          raise ArgumentError,
+                "#{LABEL}: `#{name}` is a #{reflection.macro} association; only " \
+                "#{SUPPORTED_MACROS.join(' / ')} can be duplicated (a copy shares its belongs_to parents)"
+        end
+      end
+
+      # Override point — receives the UNSAVED copy as the last step of
+      # `duplicate`, so tweaks apply before any save.
+      def on_duplicate(_copy); end
+
+      # 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 = {})
+        copy = dup
+        duplicable_reset_attributes(copy)
+        duplicable_apply_suffixes(copy)
+        overrides.each { |attribute, value| copy.public_send("#{attribute}=", value) }
+        duplicable_copy_associations(copy)
+        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)
+        transaction { copy.save! }
+        copy
+      end
+
+      private
+
+      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)
+        end
+        copy[self.class.lockable_attempts_field] = 0 if duplicable_concern?(Lockable)
+      end
+
+      def duplicable_apply_suffixes(copy)
+        self.class.duplicable_config[:suffix].each do |field, text|
+          copy[field] = "#{copy[field]}#{text}" if copy[field].present?
+        end
+      end
+
+      # Identity-bearing columns owned by sibling concerns (see module docs).
+      def duplicable_auto_reset_columns
+        columns = TIMESTAMP_COLUMNS.dup
+        columns.concat(duplicable_generator_columns)
+        columns << self.class.auditable_into if duplicable_concern?(Auditable)
+        columns << self.class.soft_delete_field if duplicable_concern?(SoftDeletable)
+        columns << self.class.lockable_locked_at_field if duplicable_concern?(Lockable)
+        columns
+      end
+
+      # Columns whose values are generated per record (slug, tokens, sequence
+      # numbers) — each concern regenerates them on the copy's save.
+      def duplicable_generator_columns
+        columns = []
+        columns << self.class.friendly_id_config.slug_column if duplicable_concern?(Sluggable)
+        columns.concat(self.class.tokenizable_fields.keys) if duplicable_concern?(Tokenizable)
+        columns << self.class.hashable_field if duplicable_concern?(Hashable) && self.class.hashable_field
+        columns.concat(duplicable_sequence_columns) if duplicable_concern?(Sequenceable)
+        columns
+      end
+
+      def duplicable_sequence_columns
+        self.class.sequenceable_config.flat_map do |field, cfg|
+          [field, cfg[:into]].compact
+        end
+      end
+
+      def duplicable_concern?(concern)
+        self.class.include?(concern)
+      end
+
+      def duplicable_copy_associations(copy)
+        self.class.duplicable_config[:associations].each do |name|
+          reflection = self.class.reflect_on_association(name)
+          case reflection.macro
+          when :has_many
+            public_send(name).each { |child| copy.public_send(name) << duplicable_child_copy(child) }
+          when :has_one
+            child = public_send(name)
+            copy.public_send("#{name}=", duplicable_child_copy(child)) if child
+          when :has_and_belongs_to_many
+            copy.public_send("#{name}=", public_send(name).to_a)
+          end
+        end
+      end
+
+      # A child that is itself Duplicable copies by its OWN rules; anything
+      # else gets a dup with the timestamps blanked (AR preserves a present
+      # created_at on save).
+      def duplicable_child_copy(child)
+        return child.duplicate if child.class.include?(Duplicable)
+
+        plain = child.dup
+        TIMESTAMP_COLUMNS.each { |column| plain[column] = nil if plain.class.column_names.include?(column) }
+        plain
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.22.0".freeze
+  VERSION = "1.23.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -96,6 +96,8 @@ require "concerns_on_rails/models/aliasable"
 require "concerns_on_rails/models/storable"
 require "concerns_on_rails/models/counter_cacheable"
 require "concerns_on_rails/models/encryptable"
+require "concerns_on_rails/models/anonymizable"
+require "concerns_on_rails/models/duplicable"
 
 # Controller concerns
 require "concerns_on_rails/controllers/paginatable"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.22.0
+  version: 1.23.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-26 00:00:00.000000000 Z
+date: 2026-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -92,8 +92,10 @@ files:
 - lib/concerns_on_rails/models/activatable.rb
 - lib/concerns_on_rails/models/addressable.rb
 - lib/concerns_on_rails/models/aliasable.rb
+- lib/concerns_on_rails/models/anonymizable.rb
 - lib/concerns_on_rails/models/auditable.rb
 - lib/concerns_on_rails/models/counter_cacheable.rb
+- lib/concerns_on_rails/models/duplicable.rb
 - lib/concerns_on_rails/models/encryptable.rb
 - lib/concerns_on_rails/models/expirable.rb
 - lib/concerns_on_rails/models/hashable.rb