The Complete Production SOP: How to Deploy and Run Active Record Named Scopes & Life-Cycle Callbacks in Autonomous AI Agents

---
name: "rails-active-record-scopes-callbacks"
description: "Write expressive, composable database queries and safe model lifecycle hooks in Rails."
metadata:
  author: "Ruby on Rails"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "write active record scope"
  - "after_commit callback rails"
  - "active record transaction"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Active Record Named Scopes & Life-Cycle Callbacks

Implements Active Record: defining reusable scopes (scope :active, -> { where(...) }), chaining scopes, lifecycle callbacks (before_validation, after_commit), avoiding callback side-effect traps, and transactions.

# Base record configuration ensuring transaction isolation standards
class ApplicationRecord < ActiveRecord::Base
  primary_abstract_class

  # Restrict agent patterns: ensure default scope is never injected globally
  self.implicit_order_column = "created_at"
end

class Invoice < ApplicationRecord
  enum :status, { draft: 0, pending: 1, paid: 2, voided: 3 }, default: :draft

  # Always evaluate dynamic scopes at call time via lambdas
  scope :overdue, -> { pending.where("due_date < ?", Time.current) }
  scope :for_account, ->(account_id) { where(account_id: account_id) }

  # Restrict side effects to post-commit to prevent phantom job dispatch
  after_commit :enqueue_delivery, on: :create

  private

  def enqueue_delivery
    InvoiceDeliveryJob.perform_later(id)
  end
end

RSpec.describe Invoice, type: :model do
  describe ".overdue" do
    it "returns pending invoices past their due date" do
      past_invoice = create(:invoice, :pending, due_date: 2.days.ago)
      future_invoice = create(:invoice, :pending, due_date: 2.days.from_now)
      
      expect(described_class.overdue).to include(past_invoice)
      expect(described_class.overdue).not_to include(future_invoice)
    end
  end

  describe "callbacks" do
    it "enqueues delivery job only after commit" do
      expect {
        create(:invoice)
      }.to have_enqueued_job(InvoiceDeliveryJob)
    end
  end
end