active_record-undo 0.2.0 → 0.3.0

data/README.md

@@ -194,14 +194,115 @@ post.soft_deleted?  # => false
 post.comments.count # => 2
 ```
 
-#### Option B: Restore from the `UndoLog`
-
 ```ruby
 undo_log.restore!
 
 post.reload.soft_deleted? # => false
 ```
 
+### Asynchronous Cascades (`soft_delete_later!` & `restore_later!`)
+
+For deep or massive association trees (5,000+ items), synchronous processing can breach web request timeouts (e.g., Puma 30s limits, Cloudflare 524 timeouts). `active_record-undo` provides non-blocking asynchronous operations powered by ActiveJob, using batched DFS traversal to keep memory flat:
+
+```ruby
+# 1. Soft delete asynchronously: hides root record immediately and enqueues SoftDeleteJob
+undo_log = post.soft_delete_later!
+# Or specify a custom ActiveJob queue:
+undo_log = post.soft_delete_later!(queue: :low_priority)
+
+post.soft_deleted?            # => true (immediately hidden from Post.kept)
+post.soft_delete_status       # => "pending" -> "processing" -> "completed"
+post.soft_delete_processing?  # => true / false
+post.undoable?                # => false until SoftDeleteJob completes
+
+# 2. Restore asynchronously: enqueues RestoreJob to restore all cascaded items bottom-up
+post.restore_later!
+# Or call directly on the UndoLog:
+undo_log.restore_later!(queue: :critical)
+
+post.restore_status           # => "pending" -> "processing"
+post.restore_processing?      # => true / false
+```
+
+### Asynchronous Failure Recovery & Execution Logging
+
+When running asynchronous cascades over thousands of associated records, background jobs can encounter transient failures such as database connection drops, lock acquisition timeouts, deadlocks, or worker restarts. `active_record-undo` provides robust failure tracking, persistent error logging, and idempotent recovery semantics.
+
+#### 1. Lifecycle State Machine
+
+Every asynchronous operation updates execution state directly on the database `undo_logs` record:
+
+```
+[:pending] ────► [:processing] ────► [:completed] (Destroyed on restore completion)
+                       │
+                       ▼
+                   [:failed] (with persistent error_message)
+```
+
+- **`status`**: `:pending` (0), `:processing` (1), `:completed` (2), `:failed` (3).
+- **`action`**: `:soft_delete` (0), `:restore` (1).
+- **`error_message`**: Captures `exception.message` when a job fails.
+
+#### 2. Worker Re-raising & Queue Integration
+
+When an exception occurs during `SoftDeleteJob` or `RestoreJob`:
+1. The job catches `StandardError`.
+2. It immediately updates the `UndoLog` with `status: :failed` and `error_message: exception.message`.
+3. It **re-raises** the exception (`raise e`).
+
+Re-raising guarantees full integration with your ActiveJob backend (Sidekiq, Solid Queue, GoodJob, DelayedJob) and application monitoring:
+- **Queue Retries**: Native queue retries (e.g., `retry_on ActiveRecord::Deadlocked, wait: 5.seconds, attempts: 3`) function normally.
+- **Error Tracking**: Exceptions are automatically sent to Sentry, Honeybadger, Bugsnag, Datadog, etc., with full backtraces.
+- **Custom Base Job**: Set `config.base_job = 'ApplicationJob'` to inherit your application's logging tags, retry strategies, and discard handlers.
+
+#### 3. Idempotency & Safe Resumption
+
+Both jobs are engineered for safe re-entrancy, allowing failed or interrupted jobs to be retried without corrupting data or duplicating log items:
+
+- **Soft Delete Re-entrancy**: `CascadeHandler` uses `in_batches` and checks `associated.reload.soft_deleted?`. If a worker dies halfway or encounters a transient error, retrying the job safely skips already soft-deleted records and continues cascade processing for the remaining associations.
+- **Restore Batches & Row Locking**: `RestoreJob` acquires a database row lock using `undo_log.with_lock` (`SELECT FOR UPDATE`). This prevents duplicate or concurrent worker runs on the same log. Restorations update `deleted_at: nil` in batches (`find_each(batch_size: 1000)`). The `UndoLog` and its `undo_log_items` are only pruned after all batches finish. If an error interrupts restoration, the log and all un-restored items remain preserved in the database for inspection, retry, or manual recovery.
+
+#### 4. Inspecting & Retrying Failed Operations
+
+Engineers or automated recovery tasks can query and inspect failed jobs directly via ActiveRecord:
+
+```ruby
+# Query failed operations
+failed_logs = ActiveRecord::Undo::UndoLog.failed # or .where(status: :failed)
+
+failed_logs.each do |log|
+  puts "UndoLog ##{log.id} (#{log.action}) failed: #{log.error_message}"
+
+  # Re-enqueue restoration
+  log.restore_later! if log.action == "restore"
+
+  # Or execute synchronously to inspect immediately
+  log.restore! if log.action == "restore"
+end
+```
+
+#### 5. Frontend Polling & Error Observability
+
+Frontends can poll status endpoints using the numeric ID or signed token:
+- `GET /undo/logs/:id/status`
+- `GET /undo/status/:token`
+
+On failure, the endpoint returns a `200 OK` JSON payload with error details:
+
+```json
+{
+  "id": 42,
+  "status": "failed",
+  "action": "restore",
+  "error_message": "PG::QueryCanceled: canceling statement due to statement timeout",
+  "completed": false,
+  "failed": true
+}
+```
+
+The view helpers (`undo_status_badge`, `soft_delete_status_badge`, `restore_status_badge`) automatically apply the `.undo-status-failed` CSS class so your UI can display a failure indicator or retry button.
+
+
 ### Status & Eligibility Helpers
 
 `ActiveRecord::Undo` provides fast predicate methods and audit helpers on models:
@@ -210,14 +311,25 @@ post.reload.soft_deleted? # => false
 # Checks if the soft-delete column is set
 post.soft_deleted? # => true / false
 
-# Verifies record is soft-deleted AND has a valid undo log available in the database
-post.undoable?     # => true / false
+# Verifies record is soft-deleted AND has a completed undo log ready to restore
+post.undoable?     # => true / false (false while async soft-delete/restore is in progress)
+
+# Soft-delete & Restore operation statuses (for frontend badges / live polling)
+post.soft_delete_status       # => "pending", "processing", "completed", "failed", or nil
+post.restore_status           # => "pending", "processing", "completed", "failed", or nil
+post.soft_delete_pending?     # => true / false
+post.soft_delete_processing?  # => true / false
+post.soft_delete_completed?   # => true / false
+post.soft_delete_failed?      # => true / false
+post.restore_pending?         # => true / false
+post.restore_processing?      # => true / false
+post.restore_failed?          # => true / false
 
 # Checks if the soft-deleted record has exceeded the configured retention period
 post.expired?      # => true / false
 
 # Retrieves the latest UndoLog audit record associated with this model
-post.undo_log      # => #<ActiveRecord::Undo::UndoLog id: 14, ...>
+post.undo_log      # => #<ActiveRecord::Undo::UndoLog id: 14, status: "completed", ...>
 post.latest_undo_log # alias
 
 # Generates a cryptographic signed restoration token directly from the model
@@ -279,12 +391,14 @@ end
 
 ### Available Endpoints
 
-| Method | Route                    | Controller#Action                    | Description                                |
-| :----- | :----------------------- | :----------------------------------- | :----------------------------------------- |
-| `POST` | `/undo/logs/:id/restore` | `active_record/undo/logs#restore`    | Restores an `UndoLog` by ID                |
-| `POST` | `/undo/restore/:token`   | `active_record/undo/restores#create` | Restores an `UndoLog` using a signed token |
+| Method | Route                    | Controller#Action                    | Description                                         |
+| :----- | :----------------------- | :----------------------------------- | :-------------------------------------------------- |
+| `POST` | `/undo/logs/:id/restore` | `active_record/undo/logs#restore`    | Restores an `UndoLog` by ID (supports `async: true`)|
+| `POST` | `/undo/restore/:token`   | `active_record/undo/restores#create` | Restores using signed token (supports `async: true`)|
+| `GET`  | `/undo/logs/:id/status`  | `active_record/undo/logs#status`     | Polls restoration or soft delete status JSON        |
+| `GET`  | `/undo/status/:token`    | `active_record/undo/restores#status` | Polls status JSON using signed token                |
 
-### View Helpers (`undo_button_to` & `undo_link_to`)
+### View Helpers (`undo_button_to`, `undo_link_to`, `undo_status_badge`, `soft_delete_status_badge` & `restore_status_badge`)
 
 Clean view helpers are automatically available in all Rails views and forms:
 
@@ -295,6 +409,18 @@ Clean view helpers are automatically available in all Rails views and forms:
 <%# Pass model instances directly %>
 <%= undo_button_to(post, text: "Undo Delete", class: "btn btn-primary") %>
 
+<%# Asynchronous restore button %>
+<%= undo_button_to(post, params: { async: true }, text: "Restore Asynchronously") %>
+
+<%# Auto-detecting status badge helper for frontend progress %>
+<%= undo_status_badge(post) %>
+<!-- Renders: <span class="undo-status-badge undo-soft-delete-badge undo-status-processing">Processing</span> -->
+
+<%# Explicit status badge helpers for soft delete and restore %>
+<%= soft_delete_status_badge(post) %>
+<%= restore_status_badge(post) %>
+<%= soft_delete_status_badge(post, text: "Deleting...") %>
+
 <%# Secure direct link with signed token (prevents ID enumeration in emails or public links) %>
 <%= undo_button_to(@undo_log, signed: true, class: "btn btn-success") %>
 
@@ -512,6 +638,10 @@ ActiveRecord::Undo.configure do |config|
   # Defaults to "::ApplicationController" if defined, falling back to ActionController::Base
   config.base_controller = "::ApplicationController"
 
+  # Base job class for asynchronous workers (SoftDeleteJob, RestoreJob, PurgeJob)
+  # Defaults to "::ActiveJob::Base"
+  config.base_job = "::ActiveJob::Base"
+
   # Fallback redirect path after successful restore when no redirect_to or referer exists
   config.default_redirect_path = ->(main_app) { main_app.root_path }
 

data/app/controllers/active_record/undo/application_controller.rb

@@ -9,6 +9,7 @@ module ActiveRecord
 
       protect_from_forgery with: :exception, unless: -> { request.format.json? }
 
+      rescue_from ActiveRecord::Undo::Error, with: :handle_undo_error
       rescue_from ActiveRecord::Undo::SecurityError, with: :handle_security_error
 
       private
@@ -41,6 +42,14 @@ module ActiveRecord
         end
       end
 
+      def handle_undo_error(error)
+        respond_to do |format|
+          format.html { handle_html_error(error.message, :unprocessable_entity) }
+          format.turbo_stream { render_turbo_stream_error(error.message, :unprocessable_entity) }
+          format.json { render json: { error: error.message }, status: :unprocessable_entity }
+        end
+      end
+
       def handle_not_found
         msg = 'Undo log not found or already restored.'
         respond_to do |format|

data/app/controllers/active_record/undo/logs_controller/async_handler.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    class LogsController < ApplicationController
+      module AsyncHandler
+        private
+
+        def async_request?
+          params[:async].to_s == 'true' || request.headers['X-Undo-Async'].to_s == 'true'
+        end
+
+        def execute_async_restore_action
+          tenant = resolve_current_tenant
+          with_tenant_context(tenant) do
+            @undo_log.restore_later!(whodunnit: resolve_whodunnit_user)
+          end
+        end
+
+        def respond_with_async_restore_scheduled
+          notice = 'Restoration has been scheduled and is processing.'
+          respond_to do |format|
+            format.html { redirect_to determine_redirect_path, notice: notice, status: :see_other }
+            format.turbo_stream { render_turbo_stream_notice(notice, :accepted) }
+            format.json { render json: { success: true, status: 'pending', log_id: @undo_log.id }, status: :accepted }
+          end
+        end
+
+        def render_turbo_stream_notice(notice, status)
+          render inline: turbo_stream_template('notice', notice),
+                 content_type: 'text/vnd.turbo-stream.html',
+                 status: status
+        end
+
+        def log_status_payload
+          {
+            id: @undo_log.id,
+            action: @undo_log.action,
+            status: @undo_log.status,
+            soft_delete_status: @undo_log.soft_delete_status,
+            restore_status: @undo_log.restore_status,
+            error_message: @undo_log.error_message,
+            completed: @undo_log.completed?,
+            failed: @undo_log.failed?
+          }
+        end
+      end
+    end
+  end
+end

data/app/controllers/active_record/undo/logs_controller.rb

@@ -1,18 +1,37 @@
 # frozen_string_literal: true
 
+require_relative 'logs_controller/async_handler'
+
 module ActiveRecord
   module Undo
     class LogsController < ApplicationController
+      include AsyncHandler
+
       before_action :set_undo_log
       before_action :check_not_found
       before_action :check_expired
+      before_action :check_tenant_access
 
       def restore
         return unless @undo_log
 
-        count = @undo_log.undo_log_items.count
-        execute_restore_action
-        respond_with_restored_log(count)
+        if async_request?
+          execute_async_restore_action
+          respond_with_async_restore_scheduled
+        else
+          count = @undo_log.undo_log_items.count
+          execute_restore_action
+          respond_with_restored_log(count)
+        end
+      end
+
+      def status
+        return unless @undo_log
+
+        respond_to do |format|
+          format.json { render json: log_status_payload, status: :ok }
+          format.html { render plain: @undo_log.status, status: :ok }
+        end
       end
 
       private
@@ -29,6 +48,16 @@ module ActiveRecord
         handle_expired if @undo_log&.expired?
       end
 
+      def check_tenant_access
+        tenant = resolve_current_tenant
+        with_tenant_context(tenant) do
+          ActiveRecord::Undo.verify_configured_context!
+          return unless @undo_log && (@undo_log.tenant_id.present? || @undo_log.tenant_type.present?)
+
+          @undo_log.send(:verify_tenant_match!, @undo_log)
+        end
+      end
+
       def find_undo_log
         if params[:token].present?
           ActiveRecord::Undo::UndoLog.find_by_signed_token(params[:token])

data/app/jobs/active_record/undo/restore_job.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    class RestoreJob < ActiveRecord::Undo.base_job_class
+      queue_as :default
+
+      def perform(undo_log_id, whodunnit: nil)
+        undo_log = find_undo_log(undo_log_id)
+        return unless undo_log
+
+        acquired = lock_and_start_processing!(undo_log)
+        return unless acquired
+
+        execute_restore_batches(undo_log, whodunnit)
+      rescue StandardError => e
+        handle_failure(undo_log, e)
+        raise e
+      end
+
+      private
+
+      def find_undo_log(undo_log_id)
+        ActiveRecord::Undo::UndoLog.find_by(id: undo_log_id)
+      end
+
+      def lock_and_start_processing!(undo_log)
+        undo_log.with_lock do
+          return false if undo_log.processing?
+          return false if undo_log.completed?
+
+          undo_log.update!(status: :processing)
+          true
+        end
+      end
+
+      def execute_restore_batches(undo_log, whodunnit)
+        actor = undo_log.send(:resolve_whodunnit, whodunnit)
+        undo_log.send(:with_whodunnit_context, actor) do
+          with_tenant_context(undo_log) do
+            restore_all_items_in_batches(undo_log)
+            cleanup_log!(undo_log)
+          end
+        end
+      end
+
+      def with_tenant_context(undo_log)
+        ten = undo_log.tenant || undo_log.tenant_id
+        orig = ActiveRecord::Undo.current_tenant
+        ActiveRecord::Undo.current_tenant = ten if ten.present?
+        yield
+      ensure
+        ActiveRecord::Undo.current_tenant = orig
+      end
+
+      def restore_all_items_in_batches(undo_log)
+        undo_log.undo_log_items.find_each(batch_size: 1000, order: :desc, &:restore_item!)
+      end
+
+      def cleanup_log!(undo_log)
+        undo_log.undo_log_items.in_batches(of: 1000).delete_all
+        undo_log.destroy!
+      end
+
+      def handle_failure(undo_log, exception)
+        return unless undo_log && ActiveRecord::Undo::UndoLog.exists?(undo_log.id)
+
+        undo_log.update!(status: :failed, error_message: exception.message)
+      end
+    end
+  end
+end

data/app/jobs/active_record/undo/soft_delete_job.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    class SoftDeleteJob < ActiveRecord::Undo.base_job_class
+      queue_as :default
+
+      def perform(record_class_name, record_id, undo_log_id, whodunnit: nil, tenant: nil)
+        undo_log = find_undo_log(undo_log_id)
+        return unless undo_log
+
+        acquired = lock_and_start_processing!(undo_log)
+        return unless acquired
+
+        execute_soft_delete_cascade(record_class_name, record_id, undo_log, whodunnit, tenant)
+      rescue StandardError => e
+        handle_failure(undo_log, e)
+        raise e
+      end
+
+      private
+
+      def find_undo_log(undo_log_id)
+        ActiveRecord::Undo::UndoLog.find_by(id: undo_log_id)
+      end
+
+      def lock_and_start_processing!(undo_log)
+        undo_log.with_lock do
+          return false if undo_log.processing?
+          return false if undo_log.completed?
+
+          undo_log.update!(status: :processing)
+          true
+        end
+      end
+
+      def execute_soft_delete_cascade(class_name, record_id, undo_log, whodunnit, tenant)
+        record = class_name.constantize.unscoped.find(record_id)
+        timestamp = record_timestamp(record, undo_log)
+
+        run_cascade_with_context(record, timestamp, undo_log, whodunnit, tenant)
+        undo_log.update!(status: :completed)
+      end
+
+      def record_timestamp(record, undo_log)
+        col = record.class.respond_to?(:undoable_column) ? record.class.undoable_column : :deleted_at
+        record.public_send(col) || undo_log.created_at || Time.current
+      end
+
+      def run_cascade_with_context(record, timestamp, undo_log, whodunnit, tenant)
+        with_execution_context(record, whodunnit, tenant) do
+          CascadeHandler.new(record).soft_delete_associations_batched!(timestamp, undo_log)
+        end
+      end
+
+      def with_execution_context(record, whodunnit, tenant)
+        actor = whodunnit || record.send(:resolve_whodunnit, nil)
+        ten = tenant || record.send(:resolve_tenant, nil)
+        record.send(:with_whodunnit_context, actor) do
+          orig = ActiveRecord::Undo.current_tenant
+          ActiveRecord::Undo.current_tenant = ten if ten.present?
+          yield
+        ensure
+          ActiveRecord::Undo.current_tenant = orig
+        end
+      end
+
+      def handle_failure(undo_log, exception)
+        return unless undo_log && ActiveRecord::Undo::UndoLog.exists?(undo_log.id)
+
+        undo_log.update!(status: :failed, error_message: exception.message)
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -4,8 +4,10 @@ ActiveRecord::Undo::Engine.routes.draw do
   resources :logs, only: [] do
     member do
       post :restore
+      get :status
     end
   end
 
   post '/restore/:token', to: 'restores#create', as: :signed_restore
+  get '/status/:token', to: 'restores#status', as: :signed_status
 end

data/db/migrate/20260920000000_add_status_and_error_message_to_undo_logs.rb

@@ -0,0 +1,15 @@
+# db/migrate/20260920000000_add_status_and_error_message_to_undo_logs.rb
+# frozen_string_literal: true
+
+class AddStatusAndErrorMessageToUndoLogs < ActiveRecord::Migration[7.0]
+  def change
+    change_table :undo_logs, bulk: true do |t|
+      t.integer :status, default: 2, null: false unless column_exists?(:undo_logs, :status)
+      t.integer :action, default: 0, null: false unless column_exists?(:undo_logs, :action)
+      t.text :error_message unless column_exists?(:undo_logs, :error_message)
+    end
+
+    add_index :undo_logs, :status unless index_exists?(:undo_logs, :status)
+    add_index :undo_logs, :action unless index_exists?(:undo_logs, :action)
+  end
+end

data/lib/active_record/undo/cascade_handler.rb

@@ -20,8 +20,74 @@ module ActiveRecord
         undo_log.undo_log_items.build(item: @record)
       end
 
+      def soft_delete_associations_batched!(timestamp, undo_log, batch_size: 1000)
+        associations_to_cascade.each do |reflection|
+          cascade_association_batched!(reflection, timestamp, undo_log, batch_size)
+        end
+      end
+
       private
 
+      def cascade_association_batched!(reflection, timestamp, undo_log, batch_size)
+        target = @record.public_send(reflection.name)
+        return if target.nil?
+
+        if reflection.collection? || target.is_a?(ActiveRecord::Relation)
+          cascade_collection_batched!(target, reflection, timestamp, undo_log, batch_size)
+        else
+          cascade_record_batched!(target, reflection, timestamp, undo_log, batch_size)
+        end
+      end
+
+      def cascade_collection_batched!(target, reflection, timestamp, undo_log, batch_size)
+        each_collection_batch(target, batch_size) do |batch|
+          batch.each do |associated|
+            cascade_record_batched!(associated, reflection, timestamp, undo_log, batch_size)
+          end
+        end
+      end
+
+      def each_collection_batch(target, batch_size, &)
+        if target.respond_to?(:in_batches)
+          target.in_batches(of: batch_size, &)
+        else
+          target.each_slice(batch_size, &)
+        end
+      end
+
+      def cascade_record_batched!(associated, reflection, timestamp, undo_log, batch_size)
+        return if skip_cascade?(associated)
+
+        if undoable_record?(associated)
+          process_undoable_child!(associated, timestamp, undo_log, batch_size)
+        elsif reflection.options[:dependent] == :destroy
+          associated.destroy!
+        end
+      end
+
+      def skip_cascade?(associated)
+        return true if associated.nil?
+        return true if associated.respond_to?(:soft_deleted?) && associated.soft_deleted?
+
+        if associated.respond_to?(:soft_deleted?) && associated.persisted?
+          associated.reload
+          return true if associated.soft_deleted?
+        end
+
+        false
+      end
+
+      def undoable_record?(associated)
+        associated.respond_to?(:acts_as_undoable) || associated.class.respond_to?(:undoable_column)
+      end
+
+      def process_undoable_child!(associated, timestamp, undo_log, batch_size)
+        self.class.new(associated).soft_delete_associations_batched!(timestamp, undo_log, batch_size: batch_size)
+        column_name = associated.class.respond_to?(:undoable_column) ? associated.class.undoable_column : :deleted_at
+        associated.update_columns(column_name => timestamp, updated_at: timestamp)
+        ActiveRecord::Undo::UndoLogItem.create!(undo_log_id: undo_log.id, item: associated)
+      end
+
       def cascade_to_associations!(timestamp, undo_log)
         associations_to_cascade.each do |reflection|
           associated_records_for(reflection).each do |associated|

data/lib/active_record/undo/configuration.rb

@@ -4,7 +4,7 @@ module ActiveRecord
   module Undo
     class Configuration
       attr_accessor :retention_period, :current_user_method, :current_tenant_method,
-                    :base_controller, :default_redirect_path, :token_secret_key,
+                    :base_controller, :base_job, :default_redirect_path, :token_secret_key,
                     :token_expires_in, :error_handling
 
       def initialize
@@ -12,6 +12,7 @@ module ActiveRecord
         @current_user_method = nil
         @current_tenant_method = nil
         @base_controller = '::ApplicationController'
+        @base_job = '::ActiveJob::Base'
         @default_redirect_path = ->(main_app) { main_app.respond_to?(:root_path) ? main_app.root_path : '/' }
         @token_secret_key = nil
         @token_expires_in = 24.hours

data/lib/active_record/undo/model_extension/async_methods.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    module ModelExtension
+      module AsyncMethods
+        def soft_delete_status
+          return nil unless soft_deleted?
+          return 'completed' unless undo_log
+
+          undo_log.soft_delete_status
+        end
+
+        def restore_status
+          return nil unless undo_log
+
+          undo_log.restore_status
+        end
+
+        def soft_delete_later!(whodunnit: nil, tenant: nil, queue: nil)
+          ensure_undoable_column_exists!
+          return false if soft_deleted?
+
+          ActiveRecord::Undo.verify_configured_context!
+          attrs = build_undo_log_attributes(whodunnit, tenant)
+          undo_log = execute_initial_soft_delete_later!(attrs)
+          enqueue_soft_delete_job!(undo_log, whodunnit, tenant, queue)
+          undo_log
+        end
+
+        def restore_later!(whodunnit: nil, queue: nil)
+          ensure_undoable_column_exists!
+          return false unless soft_deleted?
+
+          ActiveRecord::Undo.verify_configured_context!
+          log = undo_log
+          raise ActiveRecord::Undo::Error, 'No undo log found to restore.' unless log
+
+          log.restore_later!(whodunnit: whodunnit, queue: queue)
+          log
+        end
+
+        private
+
+        def execute_initial_soft_delete_later!(attrs)
+          transaction do
+            timestamp = Time.current
+            undo_log = ActiveRecord::Undo::UndoLog.create!(attrs.merge(action: :soft_delete, status: :pending))
+            update_soft_delete_timestamps!(timestamp)
+            ActiveRecord::Undo::UndoLogItem.create!(undo_log_id: undo_log.id, item: self)
+            undo_log
+          end
+        end
+
+        def update_soft_delete_timestamps!(timestamp)
+          column_name = self.class.undoable_column
+          update_columns(column_name => timestamp, updated_at: timestamp)
+        end
+
+        def enqueue_soft_delete_job!(undo_log, whodunnit, tenant, queue)
+          job_class = ActiveRecord::Undo::SoftDeleteJob
+          job = queue.present? ? job_class.set(queue: queue) : job_class
+          job.perform_later(self.class.name, id, undo_log.id, whodunnit: whodunnit, tenant: tenant)
+        end
+      end
+    end
+  end
+end