Plan: Reference Type Extensions

// SPDX-License-Identifier: AGPL-3.0-or-later
// Add these variants to the existing DeterminationStatus enum in enums.rs:

/// Benefits ended at the natural conclusion of the certification period.
Terminated,
/// Benefits reduced or eliminated due to work/cooperation requirement violation.
/// Used for TANF work non-compliance and SNAP IPV-adjacent sanctions.
Sanctioned,
/// Recipient has exhausted the federal 60-month TANF lifetime limit.
/// 42 USC §608(a)(7).
TimeLimitExceeded,
/// SNAP ABAWD 3-month time limit within the 36-month tracking window exhausted.
/// 7 USC §2015(o); 7 CFR 273.24.
AbawdExceeded,
/// Disqualified due to Intentional Program Violation (IPV) finding.
/// Separate from denial — IPV carries a disqualification period (1 year, 2 years, permanent).
Disqualified,

/// TANF cash assistance. Countable for SNAP; also required to identify categorical eligibility triggers.
Tanf,
/// VA benefits (disability compensation, pension, dependency and indemnity). Countable for SNAP.
Veterans,
/// Rental income from property. Countable; net of allowable expenses for self-employment method.
Rental,
/// Workers' compensation payments. Countable as unearned income.
WorkersCompensation,
/// Strike benefits from a union. Countable per 7 CFR 273.9(b). Striker households subject to special rules.
StrikeBenefits,
/// Irregular or infrequent income. May be excludable if under threshold (7 CFR 273.9(b)(2)).
Irregular,
/// Net self-employment income after allowable business expenses.
/// Separate from SelfEmployment (gross) to support both gross and net reporting.
SelfEmploymentNet,
/// Child support paid OUT to non-household members. Deduction, not income — tracked here for deduction calculation.
/// 7 CFR 273.9(d)(7).
ChildSupportPaid,

/// Individual Development Account. Excluded for SNAP per 7 CFR 273.8(e)(19).
IdaAccount,
/// ABLE Act account. Excluded from all federal means-tested programs.
AbleAccount,
/// 529 education savings account. Excluded for SNAP and Medicaid.
Plan529,
/// Tribal land held in trust by federal government. Excluded for SNAP per 7 CFR 273.8(e).
IndianTrustLand,
/// Equity in business property essential to self-employment.
/// Excludable for SNAP per 7 CFR 273.8(e)(5) if essential to earning self-employment income.
BusinessEquity,

/// Expedited service identification notice. Informs household of 7-day processing timeline.
/// Required by 7 CFR 273.2(i)(3).
ExpeditedNotice,
/// ABAWD time limit warning notice. Sent in months 1 and 2 of the 3-month window.
/// Good practice; technically required by adequate notice principles.
AbawdNotice,
/// Sanction notice. TANF work non-compliance or SNAP IPV sanction.
SanctionNotice,
/// TANF 60-month time limit approaching notice. Sent at months 54, 57, 59.
TimeLimitNotice,
/// EBT stale benefit pre-expungement notice. Required 30 days before expungement.
/// 7 USC §2016(h)(9).
ExpungementNotice,
/// TANF IV-D child support referral notice. Notifies household of referral to child support agency.
IvdReferralNotice,
/// Confirmation that benefits continue pending fair hearing decision.
/// Issued when continued benefits are granted on appeal. 7 CFR 273.15(g).
ContinuedBenefitsNotice,
/// Notice of change in benefit amount or household circumstances.
ChangeInCircumstancesNotice,
/// Overpayment claim notice. Issued after hearing decided in agency favor when continued benefits were paid.
OverpaymentNotice,

/// WIC Participant Characteristics biennial report. 7 CFR 246.25(b).
WicPc,
/// CCDF ACF-801 annual case-level data report. 45 CFR 98.70.
CcdfAcf801,

/// Source that provided verification evidence.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, ToSchema)]
#[serde(rename_all = "snake_case")]
pub enum VerificationSource {
    /// Self-reported by the applicant on the application form.
    Attestation,
    /// Documentary evidence provided by the applicant (pay stubs, lease, etc.).
    DocumentaryEvidence,
    /// Income and Eligibility Verification System (7 USC §2025(e); 42 USC §1320b-7).
    Ievs,
    /// DHS SAVE system for immigration status verification (8 USC §1642).
    SaveMatch,
    /// Collateral contact when documents are unavailable (7 CFR 273.2(f)(5)).
    CollateralContact,
    /// Cross-program enrollment verification (adjunctive eligibility, categorical eligibility).
    CrossProgramQuery,
    /// State childcare provider registry (CAPS provider validation).
    ProviderRegistry,
}

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

use chrono::{DateTime, NaiveDate, Utc};
use serde::{Deserialize, Serialize};
use utoipa::ToSchema;

use crate::VerificationSource;

/// A specific item that must be verified before a determination can be finalized.
/// Used when DeterminationStatus is PendingVerification.
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct VerificationItem {
    pub requirement: VerificationRequirement,
    pub source: Option<VerificationSource>,
    pub due_date: Option<NaiveDate>,
    pub resolved_at: Option<DateTime<Utc>>,
    pub notes: Option<String>,
}

/// What must be verified.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, ToSchema)]
#[serde(rename_all = "snake_case")]
pub enum VerificationRequirement {
    Identity,
    Residency,
    SocialSecurityNumber,
    GrossIncome,
    SelfEmploymentIncome,
    Assets,
    ChildSupport,
    CitizenshipAlienStatus,
    StudentStatus,
    DisabilityStatus,
    PregnancyStatus,
    HouseholdComposition,
    ShelterExpenses,
    DependentCareExpenses,
    MedicalExpenses,
    TaxFilingStatus,
    AbawdWorkActivity,
    ImmigrationEntryDate,
}

/// Regulatory citation codes for denial reasons. Required for NOA content (7 CFR 273.13(a)).
/// Example: ["7CFR273.9.a.gross_income_exceeded", "7CFR273.9.c.net_income_exceeded"]
pub denial_reason_codes: Vec<String>,

/// Verification items that must be resolved before this determination is finalized.
/// Non-empty when status is PendingVerification.
pub verification_items_required: Vec<canopy_reference::VerificationItem>,

/// Basis of categorical eligibility, if applicable.
/// Example: "tanf_cash_receipt", "ssi_recipient", "bbce"
pub categorical_eligibility_basis: Option<String>,

/// For SNAP: months of ABAWD time limit used in the current 36-month tracking window.
/// None if household has no ABAWD members or is in a waiver area.
pub abawd_month_count: Option<u8>,

denial_reason_codes: vec![],
verification_items_required: vec![],
categorical_eligibility_basis: None,
abawd_month_count: None,