refactor(income-statement): share scoping SQL across all four query classes (#3408)

#3404 added DailyExpenseTotals with scoping SQL that mirrored Totals, and
the same fragments (classification CASE, currency-converted amount,
entries/accounts/exchange-rates joins, budget-excluded kinds, tax-advantaged
and finance-account scoping) were already duplicated in FamilyStats and
CategoryStats. This extracts them into
IncomeStatement::ScopedTransactionsQuery so every income statement number is
computed from one definition of what counts as a reportable transaction.

No behavior change: only whitespace in the generated SQL differs. A new
equivalence test runs each refactored class against a verbatim legacy copy
(test/support/legacy_income_statement_*.rb) over the class's full option
matrix (trade inclusion, account scoping, stats interval) on a dataset that
exercises every scoping rule, and asserts identical rows.

test/models/income_statement/scoped_transactions_query_equivalence_test.rb

@@ -0,0 +1,122 @@
+require "test_helper"
+
+# Proves the IncomeStatement::ScopedTransactionsQuery refactor preserves
+# behavior: each refactored query class must return exactly what its
+# pre-refactor implementation returned. The legacy implementations are
+# verbatim copies from main (test/support/legacy_income_statement_*.rb), and
+# each test runs both over the same data across the class's full option
+# matrix (account scoping, trade inclusion, stats interval).
+class IncomeStatement::ScopedTransactionsQueryEquivalenceTest < ActiveSupport::TestCase
+  include EntriesTestHelper
+
+  setup do
+    @family = families(:empty)
+
+    @checking = @family.accounts.create! name: "Checking", currency: "USD", balance: 5000, accountable: Depository.new
+    @savings = @family.accounts.create! name: "Savings", currency: "USD", balance: 1000, accountable: Depository.new
+    @eur = @family.accounts.create! name: "EUR Checking", currency: "EUR", balance: 1000, accountable: Depository.new
+    @retirement = @family.accounts.create! name: "401k", currency: "USD", balance: 10000, accountable: Investment.new(subtype: "401k")
+    @unreported = @family.accounts.create! name: "Off the books", currency: "USD", balance: 100, accountable: Depository.new, exclude_from_reports: true
+
+    @food = @family.categories.create! name: "Food"
+    @groceries = @family.categories.create! name: "Groceries", parent: @food
+
+    # Spread across two calendar months (and weeks) so interval grouping varies.
+    create_transaction(account: @checking, amount: 100, date: 40.days.ago.to_date, category: @food)
+    create_transaction(account: @checking, amount: 50, date: 5.days.ago.to_date, category: @groceries)
+    create_transaction(account: @checking, amount: -500, date: 5.days.ago.to_date) # income
+    create_transaction(account: @checking, amount: -200, date: 5.days.ago.to_date, kind: "loan_payment")
+    create_transaction(account: @checking, amount: -300, date: 5.days.ago.to_date, kind: "investment_contribution")
+    create_transaction(account: @checking, amount: 30, date: 5.days.ago.to_date, kind: "funds_movement") # budget-excluded kind
+    create_transaction(account: @checking, amount: 25, date: 5.days.ago.to_date, excluded: true)
+
+    transfer = create_transaction(account: @checking, amount: 60, date: 5.days.ago.to_date)
+    transfer.entryable.update!(investment_activity_label: "Transfer")
+
+    pending = create_transaction(account: @checking, amount: 20, date: 5.days.ago.to_date)
+    pending.entryable.update!(extra: { "simplefin" => { "pending" => true } })
+
+    create_transaction(account: @savings, amount: 75, date: 10.days.ago.to_date)
+
+    ExchangeRate.create! from_currency: "EUR", to_currency: "USD", date: 5.days.ago.to_date, rate: 2
+    create_transaction(account: @eur, amount: 40, currency: "EUR", date: 5.days.ago.to_date)
+    create_transaction(account: @eur, amount: 10, currency: "EUR", date: 10.days.ago.to_date) # no rate row, falls back to 1
+
+    create_transaction(account: @retirement, amount: 300, date: 5.days.ago.to_date) # tax-advantaged, excluded
+    create_transaction(account: @unreported, amount: 45, date: 5.days.ago.to_date) # exclude_from_reports, excluded
+
+    @period = Period.custom(start_date: 45.days.ago.to_date, end_date: Date.current)
+  end
+
+  test "Totals matches its pre-refactor implementation across its option matrix" do
+    [ true, false ].each do |include_trades|
+      account_id_options.each do |included_account_ids|
+        args = { transactions_scope: transactions_scope, date_range: @period.date_range,
+                 include_trades: include_trades, included_account_ids: included_account_ids }
+
+        assert_equal_rows(
+          LegacyIncomeStatementTotals.new(@family, **args).call,
+          IncomeStatement::Totals.new(@family, **args).call,
+          "Totals (include_trades: #{include_trades}, included_account_ids: #{included_account_ids.inspect})"
+        )
+      end
+    end
+  end
+
+  test "DailyExpenseTotals matches its pre-refactor implementation across its option matrix" do
+    account_id_options.each do |included_account_ids|
+      args = { transactions_scope: transactions_scope, date_range: @period.date_range,
+               included_account_ids: included_account_ids }
+
+      assert_equal_rows(
+        LegacyIncomeStatementDailyExpenseTotals.new(@family, **args).call,
+        IncomeStatement::DailyExpenseTotals.new(@family, **args).call,
+        "DailyExpenseTotals (included_account_ids: #{included_account_ids.inspect})"
+      )
+    end
+  end
+
+  test "FamilyStats matches its pre-refactor implementation across its option matrix" do
+    %w[month week].each do |interval|
+      account_id_options.each do |account_ids|
+        assert_equal_rows(
+          LegacyIncomeStatementFamilyStats.new(@family, interval: interval, account_ids: account_ids).call,
+          IncomeStatement::FamilyStats.new(@family, interval: interval, account_ids: account_ids).call,
+          "FamilyStats (interval: #{interval}, account_ids: #{account_ids.inspect})"
+        )
+      end
+    end
+  end
+
+  test "CategoryStats matches its pre-refactor implementation across its option matrix" do
+    %w[month week].each do |interval|
+      account_id_options.each do |account_ids|
+        assert_equal_rows(
+          LegacyIncomeStatementCategoryStats.new(@family, interval: interval, account_ids: account_ids).call,
+          IncomeStatement::CategoryStats.new(@family, interval: interval, account_ids: account_ids).call,
+          "CategoryStats (interval: #{interval}, account_ids: #{account_ids.inspect})"
+        )
+      end
+    end
+  end
+
+  private
+    # Unscoped, scoped to a subset of accounts, and scoped to nothing.
+    def account_id_options
+      [ nil, [ @checking.id, @savings.id ], [] ]
+    end
+
+    # Same production scope used by the dashboard for both implementations.
+    def transactions_scope
+      @family.transactions.visible.excluding_pending.in_period(@period)
+    end
+
+    def assert_equal_rows(legacy_rows, refactored_rows, label)
+      assert_equal normalize(legacy_rows), normalize(refactored_rows), "#{label} returned different rows"
+    end
+
+    # Row order is not guaranteed by GROUP BY, so compare order-insensitively.
+    def normalize(rows)
+      rows.map(&:to_h).sort_by(&:inspect)
+    end
+end

test/support/legacy_income_statement_category_stats.rb

@@ -0,0 +1,104 @@
+# Verbatim copy of IncomeStatement::CategoryStats as it existed on main before the
+# IncomeStatement::ScopedTransactionsQuery refactor (base commit 947fe832),
+# renamed so both implementations can run side by side.
+# ScopedTransactionsQueryEquivalenceTest runs each refactored class and its
+# legacy counterpart over the same data and option matrix and asserts
+# identical results. Delete once the refactor is merged and trusted.
+class LegacyIncomeStatementCategoryStats
+  def initialize(family, interval: "month", account_ids: nil)
+    @family = family
+    @interval = interval
+    @account_ids = account_ids
+  end
+
+  def call
+    return [] if @account_ids&.empty?
+
+    ActiveRecord::Base.connection.select_all(sanitized_query_sql).map do |row|
+      StatRow.new(
+        category_id: row["category_id"],
+        classification: row["classification"],
+        median: row["median"],
+        avg: row["avg"]
+      )
+    end
+  end
+
+  private
+    StatRow = Data.define(:category_id, :classification, :median, :avg)
+
+    def sanitized_query_sql
+      ActiveRecord::Base.sanitize_sql_array([
+        query_sql,
+        sql_params
+      ])
+    end
+
+    def sql_params
+      params = {
+        target_currency: @family.currency,
+        interval: @interval,
+        family_id: @family.id
+      }
+
+      ids = @family.tax_advantaged_account_ids
+      params[:tax_advantaged_account_ids] = ids if ids.present?
+
+      params
+    end
+
+    def budget_excluded_kinds_sql
+      @budget_excluded_kinds_sql ||= Transaction::BUDGET_EXCLUDED_KINDS.map { |k| "'#{k}'" }.join(", ")
+    end
+
+    def pending_providers_sql
+      Transaction.pending_providers_sql("t")
+    end
+
+    def exclude_tax_advantaged_sql
+      ids = @family.tax_advantaged_account_ids
+      return "" if ids.empty?
+      "AND a.id NOT IN (:tax_advantaged_account_ids)"
+    end
+
+    def scope_to_account_ids_sql
+      return "" if @account_ids.nil?
+      ActiveRecord::Base.sanitize_sql([ "AND a.id IN (?)", @account_ids ])
+    end
+
+    def query_sql
+      <<~SQL
+        WITH period_totals AS (
+          SELECT
+            c.id as category_id,
+            date_trunc(:interval, ae.date) as period,
+            CASE WHEN t.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END as classification,
+            SUM(CASE WHEN t.kind IN ('investment_contribution', 'loan_payment') THEN ABS(ae.amount * COALESCE(er.rate, 1)) ELSE ae.amount * COALESCE(er.rate, 1) END) as total
+          FROM transactions t
+          JOIN entries ae ON ae.entryable_id = t.id AND ae.entryable_type = 'Transaction'
+          JOIN accounts a ON a.id = ae.account_id
+          LEFT JOIN categories c ON c.id = t.category_id
+          LEFT JOIN exchange_rates er ON (
+            er.date = ae.date AND
+            er.from_currency = ae.currency AND
+            er.to_currency = :target_currency
+          )
+          WHERE a.family_id = :family_id
+            AND t.kind NOT IN (#{budget_excluded_kinds_sql})
+            AND ae.excluded = false
+            AND a.exclude_from_reports = false
+            #{pending_providers_sql}
+            #{exclude_tax_advantaged_sql}
+            #{scope_to_account_ids_sql}
+          GROUP BY c.id, period, CASE WHEN t.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END
+        )
+        SELECT
+          category_id,
+          classification,
+          ABS(PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY total)) as median,
+          ABS(AVG(total)) as avg
+        FROM period_totals
+        GROUP BY category_id, classification;
+      SQL
+    end
+end

test/support/legacy_income_statement_daily_expense_totals.rb

@@ -0,0 +1,115 @@
+# Verbatim copy of IncomeStatement::DailyExpenseTotals as it existed on main before the
+# IncomeStatement::ScopedTransactionsQuery refactor (base commit 947fe832),
+# renamed so both implementations can run side by side.
+# ScopedTransactionsQueryEquivalenceTest runs each refactored class and its
+# legacy counterpart over the same data and option matrix and asserts
+# identical results. Delete once the refactor is merged and trusted.
+# Per-day expense totals (in the family's currency) for a period, used by the
+# dashboard's cumulative spending chart. Follows the same scoping rules as
+# IncomeStatement::Totals (visible, posted, budget-included transactions in
+# report-included accounts, converted at the day's exchange rate) so the
+# series always agrees with the totals shown elsewhere on the dashboard.
+class LegacyIncomeStatementDailyExpenseTotals
+  def initialize(family, transactions_scope:, date_range:, included_account_ids: nil)
+    @family = family
+    @transactions_scope = transactions_scope
+    @date_range = date_range
+    @included_account_ids = included_account_ids
+
+    validate_date_range!
+  end
+
+  def call
+    # No finance accounts means no transactions to report
+    return [] if @included_account_ids&.empty?
+
+    ActiveRecord::Base.connection.select_all(query_sql).map do |row|
+      DailyTotal.new(date: row["day"].to_date, total: row["total"])
+    end
+  end
+
+  private
+    DailyTotal = Data.define(:date, :total)
+
+    def query_sql
+      ActiveRecord::Base.sanitize_sql_array([ query_sql_body, sql_params ])
+    end
+
+    # Mirrors IncomeStatement::Totals' transactions subquery, but groups by
+    # entry date instead of category and keeps only the expense rows. The
+    # classification CASE is repeated in the GROUP BY (rather than referenced
+    # by alias) because only some databases accept aliases there.
+    def query_sql_body
+      <<~SQL
+        SELECT day, total FROM (
+          SELECT
+            ae.date as day,
+            CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END as classification,
+            ABS(SUM(CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN ABS(ae.amount * COALESCE(er.rate, 1)) ELSE ae.amount * COALESCE(er.rate, 1) END)) as total
+          FROM (#{@transactions_scope.to_sql}) at
+          JOIN entries ae ON ae.entryable_id = at.id AND ae.entryable_type = 'Transaction'
+          JOIN accounts a ON a.id = ae.account_id
+          LEFT JOIN exchange_rates er ON (
+            er.date = ae.date AND
+            er.from_currency = ae.currency AND
+            er.to_currency = :target_currency
+          )
+          WHERE at.kind NOT IN (#{budget_excluded_kinds_sql})
+            AND (
+              at.investment_activity_label IS NULL
+              OR at.investment_activity_label NOT IN ('Transfer', 'Sweep In', 'Sweep Out', 'Exchange')
+            )
+            AND ae.excluded = false
+            AND a.family_id = :family_id
+            AND a.status IN ('draft', 'active')
+            AND a.exclude_from_reports = false
+            #{exclude_tax_advantaged_sql}
+            #{include_finance_accounts_sql}
+          GROUP BY ae.date, CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END
+        ) daily
+        WHERE classification = 'expense'
+        ORDER BY day
+      SQL
+    end
+
+    def sql_params
+      params = {
+        target_currency: @family.currency,
+        family_id: @family.id,
+        start_date: @date_range.begin,
+        end_date: @date_range.end
+      }
+
+      ids = @family.tax_advantaged_account_ids
+      params[:tax_advantaged_account_ids] = ids if ids.present?
+
+      params[:included_account_ids] = @included_account_ids if @included_account_ids
+
+      params
+    end
+
+    def exclude_tax_advantaged_sql
+      ids = @family.tax_advantaged_account_ids
+      return "" if ids.empty?
+      "AND a.id NOT IN (:tax_advantaged_account_ids)"
+    end
+
+    def include_finance_accounts_sql
+      return "" if @included_account_ids.nil?
+      "AND a.id IN (:included_account_ids)"
+    end
+
+    def budget_excluded_kinds_sql
+      @budget_excluded_kinds_sql ||= Transaction::BUDGET_EXCLUDED_KINDS.map { |k| "'#{k}'" }.join(", ")
+    end
+
+    def validate_date_range!
+      unless @date_range.is_a?(Range)
+        raise ArgumentError, "date_range must be a Range, got #{@date_range.class}"
+      end
+
+      unless @date_range.begin.respond_to?(:to_date) && @date_range.end.respond_to?(:to_date)
+        raise ArgumentError, "date_range must contain date-like objects"
+      end
+    end
+end

test/support/legacy_income_statement_family_stats.rb

@@ -0,0 +1,100 @@
+# Verbatim copy of IncomeStatement::FamilyStats as it existed on main before the
+# IncomeStatement::ScopedTransactionsQuery refactor (base commit 947fe832),
+# renamed so both implementations can run side by side.
+# ScopedTransactionsQueryEquivalenceTest runs each refactored class and its
+# legacy counterpart over the same data and option matrix and asserts
+# identical results. Delete once the refactor is merged and trusted.
+class LegacyIncomeStatementFamilyStats
+  def initialize(family, interval: "month", account_ids: nil)
+    @family = family
+    @interval = interval
+    @account_ids = account_ids
+  end
+
+  def call
+    return [] if @account_ids&.empty?
+
+    ActiveRecord::Base.connection.select_all(sanitized_query_sql).map do |row|
+      StatRow.new(
+        classification: row["classification"],
+        median: row["median"],
+        avg: row["avg"]
+      )
+    end
+  end
+
+  private
+    StatRow = Data.define(:classification, :median, :avg)
+
+    def sanitized_query_sql
+      ActiveRecord::Base.sanitize_sql_array([
+        query_sql,
+        sql_params
+      ])
+    end
+
+    def sql_params
+      params = {
+        target_currency: @family.currency,
+        interval: @interval,
+        family_id: @family.id
+      }
+
+      ids = @family.tax_advantaged_account_ids
+      params[:tax_advantaged_account_ids] = ids if ids.present?
+
+      params
+    end
+
+    def budget_excluded_kinds_sql
+      @budget_excluded_kinds_sql ||= Transaction::BUDGET_EXCLUDED_KINDS.map { |k| "'#{k}'" }.join(", ")
+    end
+
+    def pending_providers_sql
+      Transaction.pending_providers_sql("t")
+    end
+
+    def exclude_tax_advantaged_sql
+      ids = @family.tax_advantaged_account_ids
+      return "" if ids.empty?
+      "AND a.id NOT IN (:tax_advantaged_account_ids)"
+    end
+
+    def scope_to_account_ids_sql
+      return "" if @account_ids.nil?
+      ActiveRecord::Base.sanitize_sql([ "AND a.id IN (?)", @account_ids ])
+    end
+
+    def query_sql
+      <<~SQL
+        WITH period_totals AS (
+          SELECT
+            date_trunc(:interval, ae.date) as period,
+            CASE WHEN t.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END as classification,
+            SUM(CASE WHEN t.kind IN ('investment_contribution', 'loan_payment') THEN ABS(ae.amount * COALESCE(er.rate, 1)) ELSE ae.amount * COALESCE(er.rate, 1) END) as total
+          FROM transactions t
+          JOIN entries ae ON ae.entryable_id = t.id AND ae.entryable_type = 'Transaction'
+          JOIN accounts a ON a.id = ae.account_id
+          LEFT JOIN exchange_rates er ON (
+            er.date = ae.date AND
+            er.from_currency = ae.currency AND
+            er.to_currency = :target_currency
+          )
+          WHERE a.family_id = :family_id
+            AND t.kind NOT IN (#{budget_excluded_kinds_sql})
+            AND ae.excluded = false
+            AND a.exclude_from_reports = false
+            #{pending_providers_sql}
+            #{exclude_tax_advantaged_sql}
+            #{scope_to_account_ids_sql}
+          GROUP BY period, CASE WHEN t.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END
+        )
+        SELECT
+          classification,
+          ABS(PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY total)) as median,
+          ABS(AVG(total)) as avg
+        FROM period_totals
+        GROUP BY classification;
+      SQL
+    end
+end

test/support/legacy_income_statement_totals.rb

@@ -0,0 +1,183 @@
+# Verbatim copy of IncomeStatement::Totals as it existed on main before the
+# IncomeStatement::ScopedTransactionsQuery refactor (base commit 947fe832),
+# renamed so both implementations can run side by side.
+# ScopedTransactionsQueryEquivalenceTest runs each refactored class and its
+# legacy counterpart over the same data and option matrix and asserts
+# identical results. Delete once the refactor is merged and trusted.
+class LegacyIncomeStatementTotals
+  def initialize(family, transactions_scope:, date_range:, include_trades: true, included_account_ids: nil)
+    @family = family
+    @transactions_scope = transactions_scope
+    @date_range = date_range
+    @include_trades = include_trades
+    @included_account_ids = included_account_ids
+
+    validate_date_range!
+  end
+
+  def call
+    # No finance accounts means no transactions to report
+    return [] if @included_account_ids&.empty?
+
+    ActiveRecord::Base.connection.select_all(query_sql).map do |row|
+      TotalsRow.new(
+        parent_category_id: row["parent_category_id"],
+        category_id: row["category_id"],
+        classification: row["classification"],
+        total: row["total"],
+        transactions_count: row["transactions_count"],
+        is_uncategorized_investment: row["is_uncategorized_investment"]
+      )
+    end
+  end
+
+  private
+    TotalsRow = Data.define(:parent_category_id, :category_id, :classification, :total, :transactions_count, :is_uncategorized_investment)
+
+    def query_sql
+      ActiveRecord::Base.sanitize_sql_array([
+        @include_trades ? combined_query_sql : transactions_only_query_sql,
+        sql_params
+      ])
+    end
+
+    # Combined query that includes both transactions and trades
+    def combined_query_sql
+      <<~SQL
+        SELECT
+          category_id,
+          parent_category_id,
+          classification,
+          is_uncategorized_investment,
+          SUM(total) as total,
+          SUM(entry_count) as transactions_count
+        FROM (
+          #{transactions_subquery_sql}
+          UNION ALL
+          #{trades_subquery_sql}
+        ) combined
+        GROUP BY category_id, parent_category_id, classification, is_uncategorized_investment;
+      SQL
+    end
+
+    # Original transactions-only query (for backwards compatibility)
+    def transactions_only_query_sql
+      <<~SQL
+        SELECT
+          c.id as category_id,
+          c.parent_id as parent_category_id,
+          CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END as classification,
+          ABS(SUM(CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN ABS(ae.amount * COALESCE(er.rate, 1)) ELSE ae.amount * COALESCE(er.rate, 1) END)) as total,
+          COUNT(ae.id) as transactions_count,
+          false as is_uncategorized_investment
+        FROM (#{@transactions_scope.to_sql}) at
+        JOIN entries ae ON ae.entryable_id = at.id AND ae.entryable_type = 'Transaction'
+        JOIN accounts a ON a.id = ae.account_id
+        LEFT JOIN categories c ON c.id = at.category_id
+        LEFT JOIN exchange_rates er ON (
+          er.date = ae.date AND
+          er.from_currency = ae.currency AND
+          er.to_currency = :target_currency
+        )
+        WHERE at.kind NOT IN (#{budget_excluded_kinds_sql})
+          AND ae.excluded = false
+          AND a.family_id = :family_id
+          AND a.status IN ('draft', 'active')
+          AND a.exclude_from_reports = false
+          #{exclude_tax_advantaged_sql}
+          #{include_finance_accounts_sql}
+        GROUP BY c.id, c.parent_id, CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END;
+      SQL
+    end
+
+    def transactions_subquery_sql
+      <<~SQL
+        SELECT
+          c.id as category_id,
+          c.parent_id as parent_category_id,
+          CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END as classification,
+          ABS(SUM(CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN ABS(ae.amount * COALESCE(er.rate, 1)) ELSE ae.amount * COALESCE(er.rate, 1) END)) as total,
+          COUNT(ae.id) as entry_count,
+          false as is_uncategorized_investment
+        FROM (#{@transactions_scope.to_sql}) at
+        JOIN entries ae ON ae.entryable_id = at.id AND ae.entryable_type = 'Transaction'
+        JOIN accounts a ON a.id = ae.account_id
+        LEFT JOIN categories c ON c.id = at.category_id
+        LEFT JOIN exchange_rates er ON (
+          er.date = ae.date AND
+          er.from_currency = ae.currency AND
+          er.to_currency = :target_currency
+        )
+        WHERE at.kind NOT IN (#{budget_excluded_kinds_sql})
+          AND (
+            at.investment_activity_label IS NULL
+            OR at.investment_activity_label NOT IN ('Transfer', 'Sweep In', 'Sweep Out', 'Exchange')
+          )
+          AND ae.excluded = false
+          AND a.family_id = :family_id
+          AND a.status IN ('draft', 'active')
+          AND a.exclude_from_reports = false
+          #{exclude_tax_advantaged_sql}
+          #{include_finance_accounts_sql}
+        GROUP BY c.id, c.parent_id, CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END
+      SQL
+    end
+
+    def trades_subquery_sql
+      # Trades are completely excluded from income/expense budgets
+      # Rationale: Trades represent portfolio rebalancing, not cash flow
+      # Example: Selling $10k AAPL to buy MSFT = no net worth change, not an expense
+      # Contributions/withdrawals are tracked separately as Transactions with activity labels
+      <<~SQL
+        SELECT NULL as category_id, NULL as parent_category_id, NULL as classification,
+               NULL as total, NULL as entry_count, NULL as is_uncategorized_investment
+        WHERE false
+      SQL
+    end
+
+    def sql_params
+      params = {
+        target_currency: @family.currency,
+        family_id: @family.id,
+        start_date: @date_range.begin,
+        end_date: @date_range.end
+      }
+
+      # Add tax-advantaged account IDs if any exist
+      ids = @family.tax_advantaged_account_ids
+      params[:tax_advantaged_account_ids] = ids if ids.present?
+
+      # Add included account IDs for per-user finance scoping
+      params[:included_account_ids] = @included_account_ids if @included_account_ids
+
+      params
+    end
+
+    # Returns SQL clause to exclude tax-advantaged accounts from budget calculations.
+    # Tax-advantaged accounts (401k, IRA, HSA, etc.) are retirement savings, not daily expenses.
+    def exclude_tax_advantaged_sql
+      ids = @family.tax_advantaged_account_ids
+      return "" if ids.empty?
+      "AND a.id NOT IN (:tax_advantaged_account_ids)"
+    end
+
+    # Returns SQL clause to filter to only accounts included in the user's finances.
+    def include_finance_accounts_sql
+      return "" if @included_account_ids.nil?
+      "AND a.id IN (:included_account_ids)"
+    end
+
+    def budget_excluded_kinds_sql
+      @budget_excluded_kinds_sql ||= Transaction::BUDGET_EXCLUDED_KINDS.map { |k| "'#{k}'" }.join(", ")
+    end
+
+    def validate_date_range!
+      unless @date_range.is_a?(Range)
+        raise ArgumentError, "date_range must be a Range, got #{@date_range.class}"
+      end
+
+      unless @date_range.begin.respond_to?(:to_date) && @date_range.end.respond_to?(:to_date)
+        raise ArgumentError, "date_range must contain date-like objects"
+      end
+    end
+end