Plan: SNAP Income Deduction Calculation and Benefit Amount

-- SPDX-License-Identifier: AGPL-3.0-or-later

-- Standard deduction by household size (7 CFR 273.9(d)(1))
-- FNS publishes annually in the Federal Register
CREATE TABLE snap_standard_deductions (
    id UUID PRIMARY KEY,
    fiscal_year INTEGER NOT NULL,
    household_size_min INTEGER NOT NULL,  -- 1
    household_size_max INTEGER NOT NULL,  -- 3, or 99 for "4+"
    amount NUMERIC(10,2) NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE UNIQUE INDEX snap_std_deduction_fy_size
    ON snap_standard_deductions (fiscal_year, household_size_min, household_size_max);

-- FY2026 seed values (confirm with FNS COLA memo before implementation)
INSERT INTO snap_standard_deductions (id, fiscal_year, household_size_min, household_size_max, amount) VALUES
    (gen_random_uuid(), 2026, 1, 3, 198.00),
    (gen_random_uuid(), 2026, 4, 99, 208.00);

-- Maximum monthly allotment by household size (7 CFR 273.10)
-- Used for benefit calculation: benefit = max_allotment - 30% of net_income
CREATE TABLE snap_max_allotments (
    id UUID PRIMARY KEY,
    fiscal_year INTEGER NOT NULL,
    household_size INTEGER NOT NULL,  -- 1 through 8; 9+ uses per_additional_member
    max_allotment NUMERIC(10,2) NOT NULL,
    per_additional_member NUMERIC(10,2),  -- only populated for household_size = 8 row
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE UNIQUE INDEX snap_max_allotment_fy_size
    ON snap_max_allotments (fiscal_year, household_size);

-- FY2026 seed values (48 contiguous states; confirm with FNS COLA memo)
INSERT INTO snap_max_allotments (id, fiscal_year, household_size, max_allotment, per_additional_member) VALUES
    (gen_random_uuid(), 2026, 1, 292.00, NULL),
    (gen_random_uuid(), 2026, 2, 536.00, NULL),
    (gen_random_uuid(), 2026, 3, 768.00, NULL),
    (gen_random_uuid(), 2026, 4, 975.00, NULL),
    (gen_random_uuid(), 2026, 5, 1158.00, NULL),
    (gen_random_uuid(), 2026, 6, 1390.00, NULL),
    (gen_random_uuid(), 2026, 7, 1536.00, NULL),
    (gen_random_uuid(), 2026, 8, 1756.00, 220.00);

-- Standard Utility Allowance amounts by jurisdiction and tier
-- Georgia has three tiers: SUA (heating/cooling), LUA (non-heating), Telephone
-- Updated annually by state; requires FNS approval
CREATE TABLE snap_sua_amounts (
    id UUID PRIMARY KEY,
    jurisdiction TEXT NOT NULL,  -- e.g., 'georgia'
    fiscal_year INTEGER NOT NULL,
    tier TEXT NOT NULL,  -- 'sua', 'lua', 'telephone'
    amount NUMERIC(10,2) NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE UNIQUE INDEX snap_sua_jurisdiction_fy_tier
    ON snap_sua_amounts (jurisdiction, fiscal_year, tier);

-- FY2026 Georgia SUA values (confirm with Georgia DFCS before implementation)
INSERT INTO snap_sua_amounts (id, jurisdiction, fiscal_year, tier, amount) VALUES
    (gen_random_uuid(), 'georgia', 2026, 'sua', 399.00),
    (gen_random_uuid(), 'georgia', 2026, 'lua', 268.00),
    (gen_random_uuid(), 'georgia', 2026, 'telephone', 49.00);

-- Maximum excess shelter deduction cap (applies to non-elderly/non-disabled households)
-- FNS publishes annually; elderly/disabled households have no cap
CREATE TABLE snap_shelter_deduction_caps (
    id UUID PRIMARY KEY,
    fiscal_year INTEGER NOT NULL,
    max_excess_shelter NUMERIC(10,2) NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE UNIQUE INDEX snap_shelter_cap_fy
    ON snap_shelter_deduction_caps (fiscal_year);

INSERT INTO snap_shelter_deduction_caps (id, fiscal_year, max_excess_shelter) VALUES
    (gen_random_uuid(), 2026, 672.00);

[snap.sua]
# Which SUA tiers are offered in this jurisdiction
# Values: "sua", "lua", "telephone"
available_tiers = ["sua", "lua", "telephone"]

# Whether households may use actual utility costs instead of SUA
# Georgia: yes, household chooses higher of SUA or actual
allow_actual_utility_costs = true

[snap.deductions]
# Dependent care monthly cap: under age 2
dependent_care_cap_under_2 = 200.00
# Dependent care monthly cap: age 2 and older
dependent_care_cap_2_and_over = 175.00
# Medical expense threshold for elderly/disabled
medical_expense_threshold = 35.00

[snap.benefit]
# Minimum monthly benefit for 1-2 person households
minimum_benefit_household_max_size = 2
minimum_benefit_amount = 23.00

// SPDX-License-Identifier: AGPL-3.0-or-later

use rust_decimal::Decimal;
use rust_decimal_macros::dec;

/// Input to the deduction pipeline — assembled by snap-eligibility from
/// canopy-persons income/expense data and the household composition.
pub struct DeductionInput {
    /// Total gross earned income (all IncomeType variants classified as earned)
    pub gross_earned_income: Decimal,
    /// Total gross unearned income
    pub gross_unearned_income: Decimal,
    /// Household size (adjusted for ineligible students per snap-categorical-eligibility)
    pub household_size: u32,
    /// Whether any household member is elderly (age >= 60) or disabled
    pub has_elderly_or_disabled: bool,
    /// Dependent care expenses: Vec of (child_age_under_2: bool, monthly_cost: Decimal)
    pub dependent_care_expenses: Vec<DependentCareExpense>,
    /// Medical expenses for elderly/disabled members only (monthly total)
    pub medical_expenses: Decimal,
    /// Shelter expenses: rent/mortgage + property tax + insurance (monthly)
    pub shelter_costs: Decimal,
    /// Utility expense election (SUA tier, actual costs, or none)
    pub utility_election: UtilityElection,
    /// Legally obligated child support paid to non-household member (monthly)
    pub child_support_paid: Decimal,
    /// Fiscal year for parameter lookups
    pub fiscal_year: i32,
}

pub struct DependentCareExpense {
    pub under_age_2: bool,
    pub monthly_cost: Decimal,
}

pub enum UtilityElection {
    /// Household claims SUA (heating/cooling costs)
    Sua,
    /// Household claims LUA (non-heating utilities only)
    Lua,
    /// Household claims telephone allowance only
    Telephone,
    /// Household uses actual documented utility costs
    ActualCosts(Decimal),
    /// Household has no utility costs (included in rent)
    None,
}

/// Output of the deduction pipeline — every intermediate value is preserved
/// for notice generation and QC review.
pub struct DeductionResult {
    pub gross_income: Decimal,
    pub earned_income_deduction: Decimal,
    pub standard_deduction: Decimal,
    pub dependent_care_deduction: Decimal,
    pub medical_deduction: Decimal,
    pub child_support_deduction: Decimal,
    pub total_shelter_costs: Decimal,       // rent + utilities (SUA or actual)
    pub shelter_half_income: Decimal,       // 50% of income after other deductions
    pub excess_shelter_raw: Decimal,        // shelter - 50% threshold (before cap)
    pub excess_shelter_deduction: Decimal,  // after cap (uncapped if elderly/disabled)
    pub net_income: Decimal,
    pub net_income_test_passed: bool,       // net_income <= 100% FPL for household_size
}

/// Calculate all deductions in mandatory federal order (7 CFR 273.10(e)).
///
/// Order:
/// 1. Earned income deduction (20%)
/// 2. Standard deduction (by household size)
/// 3. Dependent care deduction (capped per dependent)
/// 4. Child support paid deduction
/// 5. Sum deductions 1-4, subtract from gross → adjusted income
/// 6. Medical expense deduction (elderly/disabled only, excess over $35)
/// 7. Compute 50% of adjusted income after medical deduction
/// 8. Excess shelter = total shelter costs − 50% adjusted income
/// 9. Cap excess shelter unless elderly/disabled
/// 10. Net income = gross − all deductions
pub fn calculate_deductions(
    input: &DeductionInput,
    params: &DeductionParams,
) -> DeductionResult {
    let gross_income = input.gross_earned_income + input.gross_unearned_income;

    // Step 1: Earned income deduction — 20% of gross earned income
    let earned_income_deduction = (input.gross_earned_income * dec!(0.20)).round_dp(2);

    // Step 2: Standard deduction — looked up by household_size and fiscal_year
    let standard_deduction = params.standard_deduction;

    // Step 3: Dependent care deduction — actual costs capped per dependent
    let dependent_care_deduction = input.dependent_care_expenses.iter()
        .map(|dep| {
            let cap = if dep.under_age_2 {
                params.dependent_care_cap_under_2
            } else {
                params.dependent_care_cap_2_and_over
            };
            dep.monthly_cost.min(cap)
        })
        .sum::<Decimal>();

    // Step 4: Child support paid deduction — full amount, no cap
    let child_support_deduction = input.child_support_paid;

    // Step 5: Compute adjusted income after deductions 1-4
    let adjusted_after_non_shelter = gross_income
        - earned_income_deduction
        - standard_deduction
        - dependent_care_deduction
        - child_support_deduction;

    // Step 6: Medical expense deduction — elderly/disabled only, excess over threshold
    let medical_deduction = if input.has_elderly_or_disabled && input.medical_expenses > params.medical_threshold {
        input.medical_expenses - params.medical_threshold
    } else {
        Decimal::ZERO
    };

    let adjusted_after_medical = adjusted_after_non_shelter - medical_deduction;

    // Step 7: Compute 50% of adjusted income (for shelter test)
    let shelter_half_income = (adjusted_after_medical * dec!(0.50)).round_dp(2);

    // Step 8: Total shelter costs = shelter + utility (SUA or actual)
    let utility_amount = match &input.utility_election {
        UtilityElection::Sua => params.sua_amount,
        UtilityElection::Lua => params.lua_amount,
        UtilityElection::Telephone => params.telephone_amount,
        UtilityElection::ActualCosts(actual) => *actual,
        UtilityElection::None => Decimal::ZERO,
    };
    let total_shelter_costs = input.shelter_costs + utility_amount;

    // Step 9: Excess shelter = total shelter − 50% adjusted income
    let excess_shelter_raw = (total_shelter_costs - shelter_half_income).max(Decimal::ZERO);

    // Step 10: Cap excess shelter unless household has elderly/disabled member
    let excess_shelter_deduction = if input.has_elderly_or_disabled {
        excess_shelter_raw  // No cap for elderly/disabled households
    } else {
        excess_shelter_raw.min(params.max_excess_shelter)
    };

    // Final: Net income = gross − all deductions
    let net_income = gross_income
        - earned_income_deduction
        - standard_deduction
        - dependent_care_deduction
        - child_support_deduction
        - medical_deduction
        - excess_shelter_deduction;

    let net_income = net_income.max(Decimal::ZERO);

    DeductionResult {
        gross_income,
        earned_income_deduction,
        standard_deduction,
        dependent_care_deduction,
        medical_deduction,
        child_support_deduction,
        total_shelter_costs,
        shelter_half_income,
        excess_shelter_raw,
        excess_shelter_deduction,
        net_income,
        net_income_test_passed: net_income <= params.net_income_limit,
    }
}

/// Parameters loaded from database tables and jurisdiction.toml at startup.
pub struct DeductionParams {
    pub standard_deduction: Decimal,
    pub dependent_care_cap_under_2: Decimal,
    pub dependent_care_cap_2_and_over: Decimal,
    pub medical_threshold: Decimal,
    pub sua_amount: Decimal,
    pub lua_amount: Decimal,
    pub telephone_amount: Decimal,
    pub max_excess_shelter: Decimal,
    pub net_income_limit: Decimal,  // 100% FPL for household_size
}

// SPDX-License-Identifier: AGPL-3.0-or-later

use rust_decimal::Decimal;
use rust_decimal_macros::dec;

/// Calculate the monthly SNAP benefit allotment.
///
/// Formula (7 CFR 273.10(e)(2)(ii)):
///   benefit = max_allotment_for_household_size − (30% × net_income)
///   Round the 30% product DOWN to the nearest cent.
///   Round the benefit DOWN to the nearest dollar.
///
/// Minimum benefit: $23/month for 1-2 person households (FY2026).
/// Households larger than 2 have no minimum benefit — if the formula
/// yields $0, the benefit is $0 (household may still be eligible but
/// receives zero allotment).
pub fn calculate_allotment(
    net_income: Decimal,
    household_size: u32,
    max_allotment: Decimal,
    minimum_benefit: Decimal,
    minimum_benefit_max_household_size: u32,
) -> Decimal {
    let thirty_pct = (net_income * dec!(0.30)).round_dp(2);
    let raw_benefit = (max_allotment - thirty_pct).max(Decimal::ZERO);
    let benefit = raw_benefit.round_dp(0); // Round down to nearest dollar

    // Apply minimum benefit floor for small households
    if household_size <= minimum_benefit_max_household_size && benefit < minimum_benefit {
        minimum_benefit
    } else {
        benefit
    }
}

// SPDX-License-Identifier: AGPL-3.0-or-later

use rust_decimal::Decimal;

pub struct HouseholdExpenses {
    pub has_heating_cooling: bool,
    pub has_non_heating_utility: bool,
    pub has_telephone_only: bool,
    pub actual_utility_costs: Decimal,
    pub utilities_included_in_rent: bool,
}

pub struct SuaConfig {
    pub available_tiers: Vec<String>,
    pub allow_actual_utility_costs: bool,
    pub sua_amount: Decimal,
    pub lua_amount: Decimal,
    pub telephone_amount: Decimal,
}

/// Determine the utility election for the shelter deduction.
pub fn determine_utility_election(
    expenses: &HouseholdExpenses,
    config: &SuaConfig,
) -> UtilityElection {
    if expenses.utilities_included_in_rent {
        return UtilityElection::None;
    }

    if expenses.has_heating_cooling && config.available_tiers.contains(&"sua".to_string()) {
        if config.allow_actual_utility_costs
            && expenses.actual_utility_costs > config.sua_amount
        {
            UtilityElection::ActualCosts(expenses.actual_utility_costs)
        } else {
            UtilityElection::Sua
        }
    } else if expenses.has_non_heating_utility
        && config.available_tiers.contains(&"lua".to_string())
    {
        UtilityElection::Lua
    } else if expenses.has_telephone_only
        && config.available_tiers.contains(&"telephone".to_string())
    {
        UtilityElection::Telephone
    } else {
        UtilityElection::None
    }
}