active_record-undo 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3463f7d5263618417b5dc0bda22a13f8185b349c24d8b4e1610657afc5509564
-  data.tar.gz: d89197a34b065986d1f0060a83b6d5284af254ec4e9d2710de48549f60078e55
+  metadata.gz: 16734d3b5f4910ac41564182b5cb70b05bf2013aeb488c1aac4475aefada4cc0
+  data.tar.gz: b302073f99a063d32c4ed4e811f3f5df651ac1c446c7d9ce082b03dedc44b1b6
 SHA512:
-  metadata.gz: 6daed055a8e31d9ce9386c92943b9e07133ca69aa0f782412d032e090491cfcc080054359fa7e9340b78563addf9dc17cf3cc6dabed4baffda12a611bf32e5ff
-  data.tar.gz: 3259b19bec3a4519ad5dda5b3d56dc94ff3ff6c4d4853fb81cdde33556cbbc530689875863a00893ac277bd042f9153261f4413ff0ad6a9dd87fcc26d09d6091
+  metadata.gz: f8fb0a5fa5ccd779460eb5211c2250fc40b7644f3d5c30739067b92e14caa1df582c547efab1c9aa36de12172fbf4235c7c469af90f22c6f30ab3e57a8be1690
+  data.tar.gz: 8a37a66af071b37b1e6fce2cd6dcc93c4365a25063d1c252a3f925e86f51f803561264a0182081abc0d6fecfcdb144f0e047233bf431e6d8a1e2827a4562e7cf

data/DOCUMENTATION.md

@@ -39,16 +39,23 @@ graph TD
 
 ### Component Summary
 
-| Component | File Path | Class / Module | Core Responsibility |
-| :--- | :--- | :--- | :--- |
-| **Main Hook** | `lib/active_record/undo.rb` | `ActiveRecord::Undo` | Hooks into `ActiveSupport.on_load(:active_record)` |
-| **Model Extension** | `lib/active_record/undo/model_extension.rb` | `ModelExtension` | Injects DSL (`acts_as_undoable`), scopes (`kept`, `soft_deleted`), and methods (`soft_delete!`, `undoable?`, `restore!`) |
-| **Cascade Engine** | `lib/active_record/undo/cascade_handler.rb` | `CascadeHandler` | Inspects ActiveRecord reflections (`reflections`) and executes DFS traversal |
-| **Cascade Association Finder** | `lib/active_record/undo/cascade_handler/association_finder.rb` | `AssociationFinder` | Resolves which records should cascade based on dependency configuration |
-| **Cascade Record Updater** | `lib/active_record/undo/cascade_handler/record_updater.rb` | `RecordUpdater` | Updates the database timestamps directly bypassing callbacks |
-| **Audit Log Parent** | `lib/active_record/undo/undo_log.rb` | `UndoLog` | Represents the top-level deletion event and manages atomic batch restoration |
-| **Audit Log Child** | `lib/active_record/undo/undo_log_item.rb` | `UndoLogItem` | Maps polymorphic targets (`item_type`, `item_id`) to original deleted entities |
-| **Engine Link** | `lib/active_record/undo/engine.rb` | `Engine` | Appends `db/migrate/` directly to host app migration paths |
+| Component                      | File Path                                                      | Class / Module       | Core Responsibility                                                                                                                    |
+| :----------------------------- | :------------------------------------------------------------- | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
+| **Main Hook & Context**        | `lib/active_record/undo.rb`                                    | `ActiveRecord::Undo` | Hooks into `ActiveSupport.on_load(:active_record)`, manages ambient thread context (`whodunnit`, `current_tenant`), and defines errors |
+| **Model Extension**            | `lib/active_record/undo/model_extension.rb`                    | `ModelExtension`     | Injects DSL (`acts_as_undoable`), scopes (`kept`, `soft_deleted`), and methods (`soft_delete!`, `undoable?`, `restore!`)               |
+| **Model Attribution Helper**   | `lib/active_record/undo/model_extension/attribution_helper.rb` | `AttributionHelper`  | Resolves user attribution and tenant context from parameters, configured procs, or thread contexts                                     |
+| **Tenant Verification**        | `lib/active_record/undo/model_extension/tenant_verification.rb`| `TenantVerification` | Validates initiating context against log tenant on `#restore!`, raising `SecurityError` on mismatch                                    |
+| **Cascade Engine**             | `lib/active_record/undo/cascade_handler.rb`                    | `CascadeHandler`     | Inspects ActiveRecord reflections (`reflections`) and executes DFS traversal                                                           |
+| **Cascade Association Finder** | `lib/active_record/undo/cascade_handler/association_finder.rb` | `AssociationFinder`  | Resolves which records should cascade based on dependency configuration                                                                |
+| **Cascade Record Updater**     | `lib/active_record/undo/cascade_handler/record_updater.rb`     | `RecordUpdater`      | Updates the database timestamps directly bypassing callbacks                                                                           |
+| **Audit Log Parent**           | `lib/active_record/undo/undo_log.rb`                           | `UndoLog`            | Represents the top-level deletion event and manages atomic batch restoration, tenancy, and user attribution                            |
+| **Audit Log Child**            | `lib/active_record/undo/undo_log_item.rb`                      | `UndoLogItem`        | Maps polymorphic targets (`item_type`, `item_id`) to original deleted entities                                                         |
+| **Engine Link**                | `lib/active_record/undo/engine.rb`                             | `Engine`             | Appends `db/migrate/` directly to host app migration paths                                                                             |
+| **Configuration**              | `lib/active_record/undo/configuration.rb`                      | `Configuration`      | Houses retention_period, current_user_method, and current_tenant_method settings                                                       |
+| **Purger Service**             | `lib/active_record/undo/purger.rb`                             | `Purger`             | Deletes expired UndoLog/Items and soft-deleted model records in batches, scoped to tenant context when present                         |
+| **Purger Reflection Helper**   | `lib/active_record/undo/purger/reflection_helper.rb`           | `ReflectionHelper`   | Determines cascade and nullify reflection behavior for purge routines                                                                  |
+| **Purge Job**                  | `lib/active_record/undo/purge_job.rb`                          | `PurgeJob`           | ActiveJob background runner invoking Purger                                                                                            |
+| **Rake Task**                  | `lib/active_record/undo/tasks/purge.rake`                      | Rake Task            | Exposes `active_record_undo:purge_expired` command                                                                                     |
 
 ---
 
@@ -58,9 +65,15 @@ graph TD
 erDiagram
     UNDO_LOGS ||--|{ UNDO_LOG_ITEMS : "has_many"
     UNDO_LOG_ITEMS }|--|| TARGET_MODEL : "belongs_to (polymorphic)"
+    UNDO_LOGS }o--o| WHODUNNIT_MODEL : "belongs_to (polymorphic)"
+    UNDO_LOGS }o--o| TENANT_MODEL : "belongs_to (polymorphic)"
 
     UNDO_LOGS {
         bigint id PK
+        string whodunnit_type "optional"
+        bigint whodunnit_id "optional"
+        string tenant_type "optional"
+        bigint tenant_id "optional"
         datetime created_at
         datetime updated_at
       }
@@ -175,118 +188,198 @@ sequenceDiagram
 4. **Bypassing Callbacks:** Soft-deletion updates use `update_columns`. This executes a direct SQL `UPDATE` query without firing standard ActiveRecord persistence callbacks (`save`, `validate`), preventing unintended side effects during soft deletes.
 5. **Unscoped Model Resolution:** `#restore_item!` uses `klass.unscoped.find_by(id: item_id)` to locate records. This guarantees records are retrieved even when models define default scopes that filter out soft-deleted records.
 6. **Class Inheritance Security Check:** When constantizing stored class strings, the gem validates that target models inherit from `ActiveRecord::Base` to prevent arbitrary non-model constant manipulation.
+7. **Tenant Matching Verification:** During `#restore!`, if `UndoLog` is associated with a tenant, the current tenant context is verified against the log's tenant before initiating restoration, raising `ActiveRecord::Undo::SecurityError` on mismatch to prevent cross-tenant data restores.
+8. **User Attribution Transparency:** `#soft_delete!` and `#restore!` support transparent user tracking via explicit keyword arguments or ambient context resolution (`Current.user` / Thread context).
+9. **Configured Context Enforcement:** When `current_user_method` or `current_tenant_method` is configured via `ActiveRecord::Undo.configure`, operations verify that the evaluated context is not `nil`. If any configured method evaluates to `nil`, `soft_delete!` and `restore!` immediately raise `ActiveRecord::Undo::SecurityError` to prevent unauthenticated or tenantless mutations.
 
 ---
 
 ## 6. Method-by-Method Implementation Reference
 
-### 6.1 `lib/active_record/undo.rb` (Entrypoint)
+### 6.1 `lib/active_record/undo.rb` (Entrypoint & Context)
 
 * **`require 'active_record'` Loader Check**
-  - *Function*: Safely imports ActiveRecord. If ActiveRecord is not in the load path, it catches the `LoadError` and throws a detailed error instructing the developer to add `activerecord` to their `Gemfile`.
+  * *Function*: Safely imports ActiveRecord. If ActiveRecord is not in the load path, it catches the `LoadError` and throws a detailed error instructing the developer to add `activerecord` to their `Gemfile`.
 * **Loader Hook Block**
-  - *Function*: Detects if `ActiveSupport` is loaded:
-    - If present, registers `ActiveSupport.on_load(:active_record)` to inject the extension module when ActiveRecord boots.
-    - If absent (e.g. running in simple Ruby scripts), directly includes `ModelExtension` into `ActiveRecord::Base` as a fallback.
+  * *Function*: Detects if `ActiveSupport` is loaded:
+    * If present, registers `ActiveSupport.on_load(:active_record)` to inject the extension module when ActiveRecord boots.
+    * If absent (e.g. running in simple Ruby scripts), directly includes `ModelExtension` into `ActiveRecord::Base` as a fallback.
+* **`whodunnit` / `whodunnit=`**
+  * *Function*: Thread/Fiber-safe accessor for the active actor performing deletions or restorations.
+* **`current_tenant` / `current_tenant=`**
+  * *Function*: Thread/Fiber-safe accessor for the active tenant context.
+* **`verify_configured_context!`**
+  * *Function*: Enforces that configured `current_user_method` and `current_tenant_method` do not return `nil`. Raises `ActiveRecord::Undo::SecurityError` if any configured method evaluates to `nil`.
+* **`SecurityError` Exception Class**
+  * *Function*: Custom error inheriting from `ActiveRecord::Undo::Error`, raised when a cross-tenant restoration attempt, missing tenant context, or configured context violation occurs.
 
 ### 6.2 `lib/active_record/undo/engine.rb` (Rails Integration)
 
 * **`initializer 'active_record_undo.migrations'`**
-  - *Function*: Automatically runs on Rails boot to append the gem's engine migrations directory to the host application's migrations search paths. This allows host applications to detect and run gem database migrations without needing to manually copy them into the application's workspace.
+  * *Function*: Automatically runs on Rails boot to append the gem's engine migrations directory to the host application's migrations search paths. This allows host applications to detect and run gem database migrations without needing to manually copy them into the application's workspace.
 
 ### 6.3 `lib/active_record/undo/model_extension.rb` (Model Extension Module)
 
 * **`acts_as_undoable(column: :deleted_at)`**
-  - *Function*: Class-level DSL macro injected into models to enable soft-deletion.
-  - *Details*: Defines class-level configurations:
-    - `undoable_column`: Caches the name of the column (defaults to `:deleted_at`).
-    - `kept` scope: Returns records that are not soft-deleted (`where(column => nil)`).
-    - `soft_deleted` scope: Returns records that are soft-deleted (`where.not(column => nil)`).
+  * *Function*: Class-level DSL macro injected into models to enable soft-deletion.
+  * *Details*: Defines class-level configurations:
+    * `undoable_column`: Caches the name of the column (defaults to `:deleted_at`).
+    * `kept` scope: Returns records that are not soft-deleted (`where(column => nil)`).
+    * `soft_deleted` scope: Returns records that are soft-deleted (`where.not(column => nil)`).
+    * `expired` scope: Returns records soft-deleted before the global retention period threshold.
 * **`soft_deleted?`**
-  - *Function*: Checks if the current record instance has been soft-deleted. Returns `true` if the configured deletion column is populated with a timestamp.
+  * *Function*: Checks if the current record instance has been soft-deleted. Returns `true` if the configured deletion column is populated with a timestamp.
 * **`undoable?`**
-  - *Function*: Checks if the soft-deleted record has a valid undo log entry available for restoration.
-  - *Steps*:
+  * *Function*: Checks if the soft-deleted record has a valid undo log entry available for restoration.
+  * *Steps*:
     1. Returns `false` immediately if `soft_deleted?` is `false`.
     2. Performs a lightweight SQL `EXISTS` query (`ActiveRecord::Undo::UndoLogItem.joins(:undo_log).exists?(item_type: self.class.name, item_id: id)`).
     3. Returns `true` if both the log item and its parent `UndoLog` exist in the database.
-* **`soft_delete!`**
-  - *Function*: Starts the cascade soft-deletion sequence for the record.
-  - *Steps*:
+* **`soft_delete!(whodunnit: nil, tenant: nil)`**
+  * *Function*: Starts the cascade soft-deletion sequence for the record.
+  * *Parameters*:
+    * `whodunnit`: User/Actor executing the delete (falls back to `current_user_method` or Thread/Fiber context).
+    * `tenant`: Tenant context (falls back to `current_tenant_method`, Thread/Fiber context, or record's tenant association).
+  * *Steps*:
     1. Calls `ensure_undoable_column_exists!` to verify the database column is present.
     2. Aborts and returns `false` if the record is already soft-deleted.
-    3. Opens an ActiveRecord database transaction block.
-    4. Creates a new parent `UndoLog` object.
-    5. Recursively invokes cascading soft-deletes on associations and marks the record itself as soft-deleted via `CascadeHandler`.
-    6. Saves the transaction and returns the constructed `UndoLog`.
-* **`restore!`**
-  - *Function*: Restores the record from its soft-deleted state.
-  - *Steps*:
+    3. Invokes `ActiveRecord::Undo.verify_configured_context!` to enforce that configured context methods do not evaluate to `nil`.
+    4. Resolves user and tenant attributes via `AttributionHelper`.
+    5. Opens an ActiveRecord database transaction block, creates a parent `UndoLog`, and cascades deletion via `CascadeHandler`.
+* **`restore!(whodunnit: nil)`**
+  * *Function*: Restores the record from its soft-deleted state.
+  * *Parameters*:
+    * `whodunnit`: User/Actor executing the restore.
+  * *Steps*:
     1. Verifies column presence via `ensure_undoable_column_exists!`.
     2. Aborts and returns `false` if the record is not soft-deleted.
-    3. Resolves the latest `UndoLogItem` that records the soft-deletion of this instance.
-    4. If a log item is found, it calls `restore!` on the parent `UndoLog` (which restores the entire deleted tree).
-    5. If no log item is found, it falls back to a simple, direct restore by setting the deletion column back to `nil`.
+    3. Invokes `ActiveRecord::Undo.verify_configured_context!` to enforce that configured context methods do not evaluate to `nil`.
+    4. Resolves the latest `UndoLogItem` that records the soft-deletion of this instance.
+    5. If a log item is found, verifies that the current tenant context matches the log's tenant via `TenantVerification` (raises `ActiveRecord::Undo::SecurityError` if mismatched).
+    6. Attributes the restoration transaction context to `whodunnit`.
+    7. Calls `restore!` on the parent `UndoLog` (which restores the entire deleted tree).
+    8. If no log item is found, it falls back to a simple, direct restore by setting the deletion column back to `nil`.
+    9. Automatically reloads the instance attributes in-memory (using `reload`) to refresh the model state before returning `true`.
 * **`ensure_undoable_column_exists!` (Private)**
-  - *Function*: Asserts that the configured soft-delete column exists in the database schema table. Raises `ActiveRecord::Undo::Error` if missing.
+  * *Function*: Asserts that the configured soft-delete column exists in the database schema table. Raises `ActiveRecord::Undo::Error` if missing.
 * **`find_latest_undo_log_item` (Private)**
-  - *Function*: Queries `UndoLogItem` records pointing to this record, ordering by `created_at DESC` to find the most recent deletion event.
+  * *Function*: Queries `UndoLogItem` records pointing to this record, ordering by `created_at DESC` to find the most recent deletion event.
 * **`soft_delete_cascade_internal!(timestamp, undo_log)` (Private)**
-  - *Function*: Wraps instantiation and invocation of `CascadeHandler` to encapsulate cascade traversal.
+  * *Function*: Wraps instantiation and invocation of `CascadeHandler` to encapsulate cascade traversal.
+
+### 6.4 `lib/active_record/undo/model_extension/attribution_helper.rb` (Attribution Helper)
+
+* **`resolve_whodunnit(whodunnit)` (Private)**
+  * *Function*: Resolves the actor executing the action in priority order: explicit parameter -> `config.current_user_method.call` -> `ActiveRecord::Undo.whodunnit` -> `nil`.
+* **`resolve_tenant(tenant)` (Private)**
+  * *Function*: Resolves the tenant context in priority order: explicit parameter -> `config.current_tenant_method.call` -> `ActiveRecord::Undo.current_tenant` -> model instance `tenant` association -> `nil`.
+* **`build_undo_log_attributes(whodunnit, tenant)` (Private)**
+  * *Function*: Builds attributes hash supporting polymorphic model instances and scalar IDs for both actor and tenant.
+
+### 6.5 `lib/active_record/undo/model_extension/tenant_verification.rb` (Tenant Verification)
 
-### 6.4 `lib/active_record/undo/cascade_handler.rb` (Cascade Execution)
+* **`verify_tenant_match!(undo_log)` (Private)**
+  * *Function*: Asserts that the initiating context's tenant matches the log's tenant before restoration. Raises `ActiveRecord::Undo::SecurityError` if the context tenant is missing or mismatched.
+* **`tenant_matches?(undo_log, ctx)` (Private)**
+  * *Function*: Compares `undo_log` tenant type/id against active context, supporting polymorphic model instances and raw scalar identifiers.
+
+### 6.6 `lib/active_record/undo/cascade_handler.rb` (Cascade Execution)
 
 * **`initialize(record)`**
-  - *Function*: Caches the record instance to be cascade deleted.
+  * *Function*: Caches the record instance to be cascade deleted.
 * **`soft_delete_with_cascade!(timestamp, undo_log)`**
-  - *Function*: Coordinates the cascade deletion of the current record.
-  - *Steps*:
+  * *Function*: Coordinates the cascade deletion of the current record.
+  * *Steps*:
     1. Invokes `#cascade_to_associations!` to recurse into child tables.
     2. Invokes `#update_record_timestamps!` to mark the current record as soft-deleted.
     3. Appends an `UndoLogItem` pointing to this record to the `UndoLog` transaction.
 * **`cascade_to_associations!(timestamp, undo_log)` (Private)**
-  - *Function*: Iterates over reflections retrieved by `AssociationFinder`, fetches their records, and calls `#cascade_to_record!` on each associated record.
+  * *Function*: Iterates over reflections retrieved by `AssociationFinder`, fetches their records, and calls `#cascade_to_record!` on each associated record.
 * **`cascade_to_record!(associated, reflection, timestamp, undo_log)` (Private)**
-  - *Function*: Handles deletion of a single associated child record:
-    - Excludes it if it is already soft-deleted.
-    - If the child model is also configured with `acts_as_undoable`, calls its private `#soft_delete_cascade_internal!` recursively.
-    - If it is not undoable, but configured with `dependent: :destroy`, it invokes `#destroy!` to perform a hard-deletion.
+  * *Function*: Handles deletion of a single associated child record:
+    * Excludes it if it is already soft-deleted.
+    * If the child model is also configured with `acts_as_undoable`, calls its private `#soft_delete_cascade_internal!` recursively.
+    * If it is not undoable, but configured with `dependent: :destroy`, it invokes `#destroy!` to perform a hard-deletion.
 
-### 6.5 `lib/active_record/undo/cascade_handler/association_finder.rb` (Reflections Finder)
+### 6.7 `lib/active_record/undo/cascade_handler/association_finder.rb` (Reflections Finder)
 
 * **`associations_to_cascade` (Private)**
-  - *Function*: Reflects on the model's association metadata and filters list of associations to select only those configured with `dependent: :destroy`, `dependent: :soft_delete`, or `dependent: :delete_all`.
+  * *Function*: Reflects on the model's association metadata and filters list of associations to select only those configured with `dependent: :destroy`, `dependent: :soft_delete`, or `dependent: :delete_all`.
 * **`associated_records_for(reflection)` (Private)**
-  - *Function*: Fetches associated target records. Normalizes single relations and collection associations (like `has_many`) into a flat array structure.
+  * *Function*: Fetches associated target records. Normalizes single relations and collection associations (like `has_many`) into a flat array structure.
 
-### 6.6 `lib/active_record/undo/cascade_handler/record_updater.rb` (Timestamps Updater)
+### 6.8 `lib/active_record/undo/cascade_handler/record_updater.rb` (Timestamps Updater)
 
 * **`update_record_timestamps!(timestamp)` (Private)**
-  - *Function*: Bypasses ActiveRecord validations, callbacks, and dirty checking to directly write updates for the soft-delete column and `updated_at` timestamps using database-level `update_columns`.
+  * *Function*: Bypasses ActiveRecord validations, callbacks, and dirty checking to directly write updates for the soft-delete column and `updated_at` timestamps using database-level `update_columns`.
 
-### 6.7 `lib/active_record/undo/undo_log.rb` (Batch Restoration)
+### 6.9 `lib/active_record/undo/undo_log.rb` (Batch Restoration)
 
 * **`restore!`**
-  - *Function*: Triggers database restoration of the entire tree recorded under this log.
-  - *Steps*:
-    1. Opens a database transaction block.
-    2. Iterates over associated `undo_log_items` in *reverse order* (`reverse_each`), guaranteeing parent records are restored before child records.
-    3. Invokes `#restore_item!` on each item.
-    4. Automatically calls `#destroy!` on completion to purge the audit records (`UndoLog` and nested `UndoLogItem` rows) from the database.
-
-### 6.8 `lib/active_record/undo/undo_log_item.rb` (Item Restoration)
+  * *Function*: Triggers database restoration of the entire tree recorded under this log.
+  * *Steps*:
+    1. Invokes `ActiveRecord::Undo.verify_configured_context!` to enforce that configured context methods do not evaluate to `nil`.
+    2. Opens a database transaction block.
+    3. Iterates over associated `undo_log_items` in *reverse order* (`reverse_each`), guaranteeing parent records are restored before child records.
+    4. Invokes `#restore_item!` on each item.
+    5. Automatically calls `#destroy!` on completion to purge the audit records (`UndoLog` and nested `UndoLogItem` rows) from the database.
+* **`.for_whodunnit(user)`**
+  * *Function*: Scopes logs to those deleted by a specific user/actor. Supports both model instances and raw IDs.
+* **`.for_tenant(tenant)`**
+  * *Function*: Scopes logs to those belonging to a specific tenant. Supports both model instances and raw IDs.
+
+### 6.10 `lib/active_record/undo/undo_log_item.rb` (Item Restoration)
 
 * **`restore_item!`**
-  - *Function*: Performs restoration of the individual record referenced by the audit log item.
-  - *Steps*:
+  * *Function*: Performs restoration of the individual record referenced by the audit log item.
+  * *Steps*:
     1. Resolves model class via `#resolve_model_class`.
     2. Resolves target record using `unscoped.find_by(id: item_id)` (unscoping ignores default scopes filtering soft-deleted records).
     3. Ensures the soft-delete column exists on the model table.
     4. Resets the soft-delete column to `nil` using `#reset_soft_delete_column!`.
 * **`resolve_model_class` (Private)**
-  - *Function*: Constantizes the stored `item_type` string.
-  - *Security*: Asserts that the constant is a valid class that inherits from `ActiveRecord::Base`. Raises `ActiveRecord::Undo::Error` if constantization fails or targets non-model classes.
+  * *Function*: Constantizes the stored `item_type` string.
+  * *Security*: Asserts that the constant is a valid class that inherits from `ActiveRecord::Base`. Raises `ActiveRecord::Undo::Error` if constantization fails or targets non-model classes.
 * **`ensure_column_exists!(klass, column_name)` (Private)**
-  - *Function*: Confirms that the target soft-delete column exists in the class's table schema. Throws `ActiveRecord::Undo::Error` if missing.
+  * *Function*: Confirms that the target soft-delete column exists in the class's table schema. Throws `ActiveRecord::Undo::Error` if missing.
 * **`reset_soft_delete_column!(target, column_name)` (Private)**
-  - *Function*: Bypasses standard callbacks and validations to write a `nil` value to the soft-delete column directly in the database.
+  * *Function*: Bypasses standard callbacks and validations to write a `nil` value to the soft-delete column directly in the database.
+
+### 6.11 `lib/active_record/undo/configuration.rb` (Global Configuration)
+
+* **`Configuration#initialize`**
+  * *Function*: Instantiates default configurations for the gem.
+  * *Details*:
+    * `@retention_period`: Defaults to `30.days`.
+    * `@current_user_method`: Defaults to `nil`. Callable proc to resolve the current user/actor.
+    * `@current_tenant_method`: Defaults to `nil`. Callable proc to resolve the current tenant.
+
+### 6.12 `lib/active_record/undo/purger.rb` (Hard Purging Engine)
+
+* **`Purger.purge_expired!(batch_size: 1000)`**
+  * *Function*: Cleans up all database records and logs that are past their retention limits.
+  * *Steps*:
+    1. Delegates to `purge_expired_logs!(batch_size)` to find and clean up expired `UndoLog` and `UndoLogItem` entries in batches using direct SQL `delete_all` execution.
+    2. Delegates to `purge_expired_records!(batch_size)` to eager-load the host Rails application models (preventing Zeitwerk lazy-load gaps), identify expired records via the `.expired` scope, and hard-delete them and their cascading dependent associations in batches.
+  * *Relational Integrity & Constraint Protection*: Bottom-up recursive cascading deletes are performed first for associations marked as `:destroy`, `:delete_all`, or `:soft_delete`. For `:nullify` configurations, foreign key values are updated to `nil`, falling back to cascading deletion if the column contains a database-level `NOT NULL` constraint.
+
+### 6.13 `lib/active_record/undo/purger/reflection_helper.rb` (Purger Reflection Helper)
+
+* **`nullify_reflections(model)` (Private)**
+  * *Function*: Filters model reflections for `:has_many` or `:has_one` associations configured with `dependent: :nullify` where foreign key is nullable.
+* **`cascade_reflections(model)` (Private)**
+  * *Function*: Filters model reflections for associations requiring cascade deletion (`:destroy`, `:delete_all`, `:soft_delete`, or non-nullable `:nullify`).
+* **`foreign_key_nullable?(ref)` (Private)**
+  * *Function*: Checks table column schema to determine if the foreign key column allows null values.
+
+### 6.14 `lib/active_record/undo/purge_job.rb` (Background Task Worker)
+
+* **`PurgeJob#perform(batch_size: 1000)`**
+  * *Function*: Runs inside ActiveJob (when available) to execute purging asynchronously.
+  * *Details*: Invokes `ActiveRecord::Undo::Purger.purge_expired!(batch_size: batch_size)`.
+
+### 6.15 `lib/active_record/undo/tasks/purge.rake` (Command Line Utility)
+
+* **`active_record_undo:purge_expired`**
+  * *Function*: Exposes CLI Rake task for the purger engine.
+  * *Details*: Checks `ENV['BATCH_SIZE']` for custom batch sizes, falling back to 1000, and triggers `ActiveRecord::Undo::Purger.purge_expired!`.

data/README.md

@@ -14,10 +14,13 @@ Unlike conventional soft-deletion gems, `active_record-undo` automatically captu
 - 🔄 **Cascading Soft Deletes:** Soft deletes parent models along with dependent associations (`dependent: :destroy` / `:delete_all`).
 - ⏪ **Atomic Restores:** Reverses soft deletion for an entire object tree (`undo_log.restore!` or `record.restore!`) within a single database transaction.
 - 🔍 **Restoration Verification:** Provides `#undoable?` to check if a record is soft-deleted and has a valid undo log entry available for restoration.
+- 👤 **User Attribution (`whodunnit`):** Tracks who initiated soft deletions and restores automatically via ambient context (e.g. `Current.user`) or explicit arguments.
+- 🏢 **Multi-Tenant Isolation:** Scopes deletion audit logs to specific tenants/accounts and enforces strict tenant matching security on restoration.
 - ⚙️ **Configurable Columns:** Supports custom soft-delete columns (e.g., `:archived_at`, `:discarded_at`) per model while defaulting to `:deleted_at`.
 - 📦 **Polymorphic Tracking:** Records deletion events via native `UndoLog` and `UndoLogItem` models—no messy JSON payload parsing required.
 - 🚂 **Zero Generator Setup:** Built on top of `Rails::Engine`. Migrations automatically hook into `rails db:migrate`.
 - 🔍 **Default Scopes & Helpers:** Provides `.kept`, `.soft_deleted`, `#soft_deleted?`, and `#undoable?` query methods out of the box.
+- 🧹 **Automatic Expiration & Purging:** Configurable global retention window with automated background purging (`PurgeJob` and Rake task) to clean up old soft-deleted records and logs.
 
 ---
 
@@ -32,19 +35,19 @@ gem "active_record-undo"
 Then execute:
 
 ```bash
-$ bundle install
+bundle install
 ```
 
 Run database migrations. The gem automatically appends its tables (`undo_logs` and `undo_log_items`) to your app's migration path:
 
 ```bash
-$ rails db:migrate
+rails db:migrate
 ```
 
 *(Optional)* If you need to customize the migration, copy it to your host application's `db/migrate` folder:
 
 ```bash
-$ rails active_record_undo:install:migrations
+rails active_record_undo:install:migrations
 ```
 
 ---
@@ -136,9 +139,10 @@ end
 ```
 
 `#undoable?` returns `false` if:
-* The record is currently active (not soft deleted).
-* The record was soft deleted manually via direct SQL/column updates without generating an undo log.
-* The corresponding `UndoLog` record was purged or already restored.
+
+- The record is currently active (not soft deleted).
+- The record was soft deleted manually via direct SQL/column updates without generating an undo log.
+- The corresponding `UndoLog` record was purged or already restored.
 
 ### Inspect Deletion Logs
 
@@ -155,17 +159,19 @@ undo_log.undo_log_items.map(&:item)
 To restore a deleted object tree, you can invoke `restore!` either on the corresponding `UndoLog` or directly on the model instance itself:
 
 #### Option A: Restore from the model instance (Recommended)
+
 Calling `restore!` directly on the soft-deleted model automatically resolves its latest deletion event log, performs the cascading restore, and cleans up the log database rows:
 
 ```ruby
-# Restores the post and all comments deleted in the same batch
+# Restores the post and all comments deleted in the same batch (automatically reloads in-memory)
 post.restore!
 
-post.reload.soft_deleted? # => false
-post.comments.count       # => 2
+post.soft_deleted?  # => false
+post.comments.count # => 2
 ```
 
 #### Option B: Restore from the `UndoLog`
+
 ```ruby
 # Reverses soft deletes for the post and comments
 undo_log.restore!
@@ -199,6 +205,184 @@ Post.unscoped.where(id: 1)
 
 ---
 
+## Expiration, Retention & Auto-Purging
+
+To prevent database bloat, `active_record-undo` supports automated retention periods, expiration checks, and background purging for both soft-deleted records and their associated `UndoLog` audit entries.
+
+### 1. Global Configuration
+
+You can configure a global retention period inside a Rails initializer:
+
+```ruby
+# config/initializers/active_record_undo.rb
+ActiveRecord::Undo.configure do |config|
+  # Default retention period for all soft-deleted records and undo logs (defaults to 30.days)
+  config.retention_period = 30.days
+end
+```
+
+If `retention_period` is set to `nil`, records and logs will never expire.
+
+### 2. Expiration Scopes & Helpers
+
+The gem provides query scopes and instance predicate helpers:
+
+- **Model `.expired` Scope**: Returns soft-deleted records older than the configured retention period.
+
+  ```ruby
+  Post.expired # => ActiveRecord::Relation of posts soft-deleted > 30 days ago
+  ```
+
+- **Model `#expired?` Predicate**: Checks if a record is soft-deleted and past the retention period.
+
+  ```ruby
+  post.expired? # => true/false
+  ```
+
+- **`UndoLog.expired` Scope**: Returns undo log entries older than the retention period.
+
+  ```ruby
+  ActiveRecord::Undo::UndoLog.expired # => logs created > 30 days ago
+  ```
+
+### 3. Background Purging
+
+#### Purger Service
+
+The `ActiveRecord::Undo::Purger` class performs hard SQL deletes on expired records and logs using `delete_all` (bypassing callbacks and validations for efficiency):
+
+```ruby
+# Purge all expired soft-deleted records and undo logs in batches
+ActiveRecord::Undo::Purger.purge_expired!(batch_size: 1000)
+```
+
+> [!NOTE]
+> **Relational Integrity & Constraint Protection**: To prevent database-level foreign key constraint failures (e.g. `FOREIGN KEY constraint failed`), `Purger` dynamically resolves dependent associations (such as `dependent: :destroy`, `dependent: :delete_all`, or `dependent: :soft_delete`) and recursively purges associated child records bottom-up before deleting the parent record. For associations configured with `dependent: :nullify`, it nullifies the foreign key (or cascades the deletion if the foreign key column is database-restricted to be `NOT NULL`).
+
+#### ActiveJob Background Job
+
+The gem provides an ActiveJob class that calls the Purger service:
+
+```ruby
+# Enqueue the purge job to run in the background
+ActiveRecord::Undo::PurgeJob.perform_later(batch_size: 1000)
+```
+
+#### Engine Rake Task
+
+You can run the purge task via Rake. This task is automatically loaded into host applications:
+
+```bash
+# Run with the default batch size of 1000
+$ rails active_record_undo:purge_expired
+
+# Run with a custom batch size
+$ BATCH_SIZE=500 rails active_record_undo:purge_expired
+```
+
+---
+
+## Multi-Tenant Isolation & User Attribution
+
+To support enterprise-grade Rails applications, `active_record-undo` provides native mechanisms for multi-tenant data isolation and user auditing.
+
+### 1. Database Setup
+
+Add a migration to introduce polymorphic tenant and user attribution columns to the `undo_logs` table:
+
+```ruby
+class AddTenantAndUserAttributionToUndoLogs < ActiveRecord::Migration[7.0]
+  def change
+    change_table :undo_logs, bulk: true do |t|
+      t.string :whodunnit_type, null: true
+      t.bigint :whodunnit_id, null: true
+      t.string :tenant_type, null: true
+      t.bigint :tenant_id, null: true
+    end
+
+    add_index :undo_logs, [:whodunnit_type, :whodunnit_id], name: 'index_undo_logs_on_whodunnit'
+    add_index :undo_logs, [:tenant_type, :tenant_id], name: 'index_undo_logs_on_tenant'
+  end
+end
+```
+
+### 2. Global Configuration
+
+Configure global procs (e.g. evaluating `CurrentAttributes`) in your initializer:
+
+```ruby
+# config/initializers/active_record_undo.rb
+ActiveRecord::Undo.configure do |config|
+  # Callable accessors to automatically resolve context
+  config.current_user_method   = -> { Current.user }
+  config.current_tenant_method = -> { Current.account }
+end
+```
+
+### 3. Usage & Thread Context
+
+You can set thread/fiber context explicitly:
+
+```ruby
+ActiveRecord::Undo.whodunnit = current_user
+ActiveRecord::Undo.current_tenant = current_account
+```
+
+Or pass values explicitly as parameters to model operations:
+
+```ruby
+# Capture user and tenant during deletion
+post.soft_delete!(whodunnit: current_user, tenant: current_account)
+
+# Track who performed the restoration
+post.restore!(whodunnit: current_user)
+```
+
+### 4. Tenant Matching Security & Context Enforcement
+
+#### Tenant Matching Security
+
+When restoring a log that belongs to a tenant, the gem verifies that the initiating context's tenant matches the log's tenant. If there is a mismatch (or if no tenant is set in the context), the gem raises an `ActiveRecord::Undo::SecurityError`:
+
+```ruby
+ActiveRecord::Undo.current_tenant = wrong_account
+post.restore! # => raises ActiveRecord::Undo::SecurityError: Tenant mismatch
+```
+
+#### Configured Context Enforcement
+
+When `current_user_method` or `current_tenant_method` is configured via `ActiveRecord::Undo.configure`, operations enforce that the evaluated context is not `nil`:
+
+- Calling `soft_delete!` or `restore!` when a configured method evaluates to `nil` immediately raises an `ActiveRecord::Undo::SecurityError`.
+- If both user and tenant methods are configured, both must return valid non-nil objects for operations to proceed.
+- If neither method is configured, operations proceed normally without requiring user or tenant context.
+
+```ruby
+# If current_user_method is configured (e.g. -> { Current.user }),
+# but the request is unauthenticated (evaluates to nil):
+post.soft_delete! # => raises ActiveRecord::Undo::SecurityError: Configured current_user_method returned nil.
+post.restore!     # => raises ActiveRecord::Undo::SecurityError: Configured current_user_method returned nil.
+```
+
+### 5. Query Scopes & Purging
+
+Query logs scoped to a specific user or tenant:
+
+```ruby
+ActiveRecord::Undo::UndoLog.for_whodunnit(user)
+ActiveRecord::Undo::UndoLog.for_tenant(account)
+```
+
+If `current_tenant` is set in the context when running the `Purger`, purging of both logs and model records will be strictly scoped to that tenant:
+
+```ruby
+# Scoped purge for account_1
+ActiveRecord::Undo.current_tenant = account_1
+ActiveRecord::Undo::Purger.purge_expired!
+```
+
+---
+
 ## How It Works
 
 1. **Cascade Inspection:** When `soft_delete!` is called, `ActiveRecord::Undo::CascadeHandler` reflects on `has_many`, `has_one`, and `belongs_to` associations configured with `dependent: :destroy` or `:delete_all`.
@@ -211,10 +395,14 @@ Post.unscoped.where(id: 1)
 
 ## Error Handling
 
-To ensure database integrity and provide clear debugging context, the gem raises an `ActiveRecord::Undo::Error` in the following scenarios:
-* **Missing Column at Runtime:** If the configured soft-delete column is missing from the database table when calling `soft_delete!` or `restore!`.
-* **Missing Model Class:** If a model class has been renamed or deleted, preventing the polymorphic log items from finding the target class during restore.
-* **Missing Column on Target Class:** If a model class exists but no longer has the target soft-delete column during restore.
+To ensure database integrity and provide clear debugging context, the gem raises errors in the following scenarios:
+
+- **Missing Column at Runtime (`ActiveRecord::Undo::Error`):** If the configured soft-delete column is missing from the database table when calling `soft_delete!` or `restore!`.
+- **Missing Model Class (`ActiveRecord::Undo::Error`):** If a model class has been renamed or deleted, preventing the polymorphic log items from finding the target class during restore.
+- **Missing Column on Target Class (`ActiveRecord::Undo::Error`):** If a model class exists but no longer has the target soft-delete column during restore.
+- **Cross-Tenant Restoration Attempt (`ActiveRecord::Undo::SecurityError`):** If attempting to restore a record whose `UndoLog` belongs to a tenant different from the current context tenant.
+- **Missing Tenant Context on Restoration (`ActiveRecord::Undo::SecurityError`):** If attempting to restore a tenant-scoped record when no tenant is set in the context.
+- **Configured Context Evaluated to Nil (`ActiveRecord::Undo::SecurityError`):** If `current_user_method` or `current_tenant_method` is configured but returns `nil` during `soft_delete!` or `restore!`.
 
 ---
 
@@ -223,21 +411,21 @@ To ensure database integrity and provide clear debugging context, the gem raises
 After cloning the repository, install dependencies:
 
 ```bash
-$ bundle install
+bundle install
 ```
 
 Run test suite via RSpec:
 
 ```bash
-$ bundle exec rspec
+bundle exec rspec
 ```
 
 ---
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/saurabh-activecode/active_record-undo.
+Bug reports and pull requests are welcome on GitHub at <https://github.com/saurabh-activecode/active_record-undo>.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).