Plan: SAVE (Systematic Alien Verification for Entitlements) Adapter

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

use anyhow::Result;
use chrono::NaiveDate;
use serde::{Deserialize, Serialize};

/// Request to verify immigration status via SAVE.
///
/// Fields correspond to the SAVE Initial Verification (Step 1) input.
/// At least one of `alien_registration_number`, `i94_number`, or
/// `passport_number` must be provided.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SaveVerificationRequest {
    /// USCIS Alien Registration Number (A-Number), 7-9 digits
    pub alien_registration_number: Option<String>,
    /// I-94 Arrival/Departure Record Number
    pub i94_number: Option<String>,
    /// Passport number (travel document)
    pub passport_number: Option<String>,
    /// Country of birth (ISO 3166-1 alpha-3)
    pub country_of_birth: String,
    /// Date of birth
    pub date_of_birth: NaiveDate,
    /// Legal first name as it appears on immigration documents
    pub first_name: String,
    /// Legal last name as it appears on immigration documents
    pub last_name: String,
}

/// SAVE verification response.
///
/// Maps to the three-step SAVE verification process.
/// `verification_status` indicates whether the case is resolved or
/// requires additional verification steps.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SaveVerificationResponse {
    /// SAVE-assigned case verification number (unique per query)
    pub case_number: String,
    /// Current step status
    pub verification_status: SaveVerificationStatus,
    /// SAVE response code (e.g., "IMMIGRATION STATUS VERIFIED",
    /// "INSTITUTE ADDITIONAL VERIFICATION", "DHS MANUAL REVIEW")
    pub save_response_code: String,
    /// Immigration status category if verified (e.g., "LPR", "REFUGEE",
    /// "ASYLEE", "CUBAN_HAITIAN_ENTRANT", "TRAFFICKING_VICTIM",
    /// "MILITARY", "PRUCOL", "UNDOCUMENTED")
    pub immigration_status_category: Option<String>,
    /// Plain-text eligibility statement from SAVE (informational only --
    /// the program service makes the eligibility determination, not SAVE)
    pub eligibility_statement: Option<String>,
    /// Whether lawful presence has been affirmatively verified
    pub lawful_presence_verified: bool,
}

/// Status of the SAVE verification case.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SaveVerificationStatus {
    /// Step 1 complete: immigration status verified or definitively not found
    InitialVerification,
    /// Step 1 inconclusive: system recommends Step 2 additional verification
    AdditionalVerification,
    /// Steps 1-2 inconclusive: requires Step 3 manual DHS review (G-845)
    InstituteStep3,
    /// Step 3 in progress: DHS is reviewing the case
    CaseInContinuance,
}

/// Adapter trait for SAVE immigration status verification.
///
/// Implementations:
/// - `NoopSaveAdapter`: deterministic test responses (UAT)
/// - Future: `DhsSaveAdapter`: live DHS SAVE API (requires MOA)
pub trait SaveAdapter: Send + Sync {
    /// Perform initial SAVE verification (Step 1).
    /// If the response status is `AdditionalVerification`, the caller
    /// should invoke `submit_additional_verification` with the returned
    /// `case_number` for Step 2.
    async fn verify_immigration_status(
        &self,
        req: &SaveVerificationRequest,
    ) -> Result<SaveVerificationResponse>;

    /// Submit for additional verification (Step 2) or institute
    /// Step 3 manual DHS review.
    /// Called with the `case_number` from a prior Step 1 response.
    async fn submit_additional_verification(
        &self,
        case_number: &str,
    ) -> Result<SaveVerificationResponse>;
}

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

use anyhow::{bail, Result};

pub struct NoopSaveAdapter;

impl SaveAdapter for NoopSaveAdapter {
    async fn verify_immigration_status(
        &self,
        req: &SaveVerificationRequest,
    ) -> Result<SaveVerificationResponse> {
        let digits = extract_last_two_digits(req)?;
        let case_number = format!("SAVE-NOOP-{digits:02}");

        match digits {
            0..=29 => Ok(SaveVerificationResponse {
                case_number,
                verification_status: SaveVerificationStatus::InitialVerification,
                save_response_code: "IMMIGRATION STATUS VERIFIED".to_string(),
                immigration_status_category: Some("LPR".to_string()),
                eligibility_statement: Some(
                    "Lawful Permanent Resident status verified".to_string(),
                ),
                lawful_presence_verified: true,
            }),
            30..=39 => Ok(SaveVerificationResponse {
                case_number,
                verification_status: SaveVerificationStatus::InitialVerification,
                save_response_code: "IMMIGRATION STATUS VERIFIED".to_string(),
                immigration_status_category: Some("REFUGEE".to_string()),
                eligibility_statement: Some(
                    "Refugee status verified under INA 207".to_string(),
                ),
                lawful_presence_verified: true,
            }),
            40..=49 => Ok(SaveVerificationResponse {
                case_number,
                verification_status: SaveVerificationStatus::InitialVerification,
                save_response_code: "IMMIGRATION STATUS VERIFIED".to_string(),
                immigration_status_category: Some("ASYLEE".to_string()),
                eligibility_statement: Some(
                    "Asylee status verified under INA 208".to_string(),
                ),
                lawful_presence_verified: true,
            }),
            50..=59 => Ok(SaveVerificationResponse {
                case_number,
                verification_status: SaveVerificationStatus::AdditionalVerification,
                save_response_code: "INSTITUTE ADDITIONAL VERIFICATION".to_string(),
                immigration_status_category: None,
                eligibility_statement: None,
                lawful_presence_verified: false,
            }),
            60..=69 => Ok(SaveVerificationResponse {
                case_number,
                verification_status: SaveVerificationStatus::InstituteStep3,
                save_response_code: "INSTITUTE STEP 3 - DHS MANUAL REVIEW".to_string(),
                immigration_status_category: None,
                eligibility_statement: None,
                lawful_presence_verified: false,
            }),
            70..=79 => Ok(SaveVerificationResponse {
                case_number,
                verification_status: SaveVerificationStatus::InitialVerification,
                save_response_code: "IMMIGRATION STATUS NOT VERIFIED".to_string(),
                immigration_status_category: Some("UNDOCUMENTED".to_string()),
                eligibility_statement: Some(
                    "Immigration status does not match DHS records".to_string(),
                ),
                lawful_presence_verified: false,
            }),
            80..=99 => Ok(SaveVerificationResponse {
                case_number,
                verification_status: SaveVerificationStatus::CaseInContinuance,
                save_response_code: "CASE IN CONTINUANCE".to_string(),
                immigration_status_category: None,
                eligibility_statement: None,
                lawful_presence_verified: false,
            }),
            _ => bail!("unexpected digit value"),
        }
    }

    async fn submit_additional_verification(
        &self,
        case_number: &str,
    ) -> Result<SaveVerificationResponse> {
        let digits: u8 = case_number
            .rsplit('-')
            .next()
            .and_then(|s| s.parse().ok())
            .unwrap_or(0);

        match digits {
            50..=59 => Ok(SaveVerificationResponse {
                case_number: case_number.to_string(),
                verification_status: SaveVerificationStatus::InitialVerification,
                save_response_code: "IMMIGRATION STATUS VERIFIED".to_string(),
                immigration_status_category: Some("LPR".to_string()),
                eligibility_statement: Some(
                    "Lawful Permanent Resident status verified via Step 2"
                        .to_string(),
                ),
                lawful_presence_verified: true,
            }),
            60..=69 => Ok(SaveVerificationResponse {
                case_number: case_number.to_string(),
                verification_status: SaveVerificationStatus::InstituteStep3,
                save_response_code: "INSTITUTE STEP 3 - DHS MANUAL REVIEW".to_string(),
                immigration_status_category: None,
                eligibility_statement: None,
                lawful_presence_verified: false,
            }),
            _ => bail!(
                "case {case_number} is not eligible for additional verification"
            ),
        }
    }
}

/// Extract the last 2 digits from the alien registration number or I-94 number.
fn extract_last_two_digits(req: &SaveVerificationRequest) -> Result<u8> {
    let number = req
        .alien_registration_number
        .as_deref()
        .or(req.i94_number.as_deref())
        .ok_or_else(|| {
            anyhow::anyhow!(
                "at least one of alien_registration_number or i94_number is required"
            )
        })?;
    let last_two = &number[number.len().saturating_sub(2)..];
    last_two
        .parse::<u8>()
        .map(|n| n % 100)
        .map_err(|e| anyhow::anyhow!("failed to parse last 2 digits: {e}"))
}

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

-- Citizenship verification outcomes for SNAP applicants.
-- Stores the result of SAVE queries; raw SAVE responses are NOT stored.
-- Only the verification outcome (pass/fail/pending) and category are persisted.
CREATE TABLE citizenship_verifications (
    id UUID PRIMARY KEY,
    application_id UUID NOT NULL,
    person_id UUID NOT NULL,
    -- SAVE case verification number (unique per SAVE query)
    verification_case_number TEXT NOT NULL,
    -- Current verification status
    verification_status TEXT NOT NULL DEFAULT 'pending',
    -- 'verified', 'unverified', 'pending_step_2', 'pending_step_3',
    -- 'case_in_continuance'
    -- Qualified alien category if verified
    -- (e.g., 'LPR', 'REFUGEE', 'ASYLEE', 'CUBAN_HAITIAN_ENTRANT',
    --  'TRAFFICKING_VICTIM', 'MILITARY', 'PRUCOL', 'UNDOCUMENTED')
    alien_eligibility_category TEXT,
    -- SAVE response code (text, e.g., "IMMIGRATION STATUS VERIFIED")
    save_response_code TEXT NOT NULL,
    -- Whether lawful presence was affirmatively verified
    lawful_presence_verified BOOLEAN NOT NULL DEFAULT FALSE,
    -- Timestamp when verification was completed (NULL if pending)
    verified_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX citizenship_verifications_application
    ON citizenship_verifications (application_id);
CREATE INDEX citizenship_verifications_person
    ON citizenship_verifications (person_id);
CREATE INDEX citizenship_verifications_case_number
    ON citizenship_verifications (verification_case_number);

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

use anyhow::Result;
use chrono::{NaiveDate, Utc};

/// Input for SNAP alien eligibility determination per 7 CFR 273.4.
pub struct AlienEligibilityInput {
    /// Immigration status category from SAVE (e.g., "LPR", "REFUGEE")
    pub immigration_status_category: String,
    /// Date the person entered the U.S. or was granted qualified status
    pub qualified_status_date: NaiveDate,
    /// Person's date of birth
    pub date_of_birth: NaiveDate,
    /// Whether the person is disabled (SSI, SSDI, or state-determined)
    pub is_disabled: bool,
    /// Whether the person has active-duty military service or is a
    /// veteran, or spouse/dependent of such
    pub is_military_connected: bool,
}

/// Result of the SNAP alien eligibility check.
pub struct AlienEligibilityResult {
    /// Whether the person is eligible for SNAP based on alien status
    pub eligible: bool,
    /// Reason for eligibility or ineligibility
    pub reason: String,
    /// Regulatory citation supporting the determination
    pub citation: String,
}

/// Determine SNAP eligibility based on alien/immigration status.
///
/// Rules per 7 CFR 273.4:
///
/// 1. U.S. citizens are always eligible (not checked here -- this
///    function is only called for non-citizens after SAVE verification).
/// 2. Undocumented immigrants are categorically ineligible.
/// 3. Refugees and asylees are eligible from date of entry/grant
///    for the first 7 years (no 5-year bar).
/// 4. Cuban/Haitian entrants and trafficking victims are eligible
///    from date of entry/certification (no 5-year bar).
/// 5. Military-connected qualified aliens are exempt from the 5-year bar.
/// 6. Children under 18 who are otherwise qualified aliens are eligible
///    regardless of entry date (no 5-year bar per 7 CFR 273.4(a)(6)).
/// 7. Elderly persons born before 8/22/1996 who are lawfully residing
///    are eligible (7 CFR 273.4(a)(6)).
/// 8. Disabled qualified aliens receiving SSI/SSDI are eligible
///    (7 CFR 273.4(a)(6)).
/// 9. LPRs admitted after 8/22/1996: 5-year bar before SNAP eligibility.
/// 10. LPRs admitted before 8/22/1996: eligible (grandfathered).
pub fn determine_snap_alien_eligibility(
    input: &AlienEligibilityInput,
) -> Result<AlienEligibilityResult> {
    let today = Utc::now().date_naive();
    let prwora_date = NaiveDate::from_ymd_opt(1996, 8, 22)
        .expect("valid date");
    let age = (today - input.date_of_birth).num_days() / 365;
    let years_qualified =
        (today - input.qualified_status_date).num_days() as f64 / 365.25;

    // Rule 2: Undocumented -- categorical prohibition
    if input.immigration_status_category == "UNDOCUMENTED" {
        return Ok(AlienEligibilityResult {
            eligible: false,
            reason: "Undocumented immigration status; categorically \
                     ineligible for SNAP"
                .to_string(),
            citation: "7 CFR 273.4(a)".to_string(),
        });
    }

    // Rule 3: Refugees -- eligible for 7 years from entry
    if input.immigration_status_category == "REFUGEE" {
        return if years_qualified <= 7.0 {
            Ok(AlienEligibilityResult {
                eligible: true,
                reason: "Refugee; eligible for 7 years from date of entry"
                    .to_string(),
                citation: "7 CFR 273.4(a)(1)".to_string(),
            })
        } else {
            // After 7 years, treated as LPR for eligibility purposes
            Ok(AlienEligibilityResult {
                eligible: true,
                reason: "Refugee with 7+ years of qualified status; \
                         eligible as qualified alien"
                    .to_string(),
                citation: "7 CFR 273.4(a)(6)".to_string(),
            })
        };
    }

    // Rule 3: Asylees -- eligible for 7 years from grant date
    if input.immigration_status_category == "ASYLEE" {
        return if years_qualified <= 7.0 {
            Ok(AlienEligibilityResult {
                eligible: true,
                reason: "Asylee; eligible for 7 years from date of grant"
                    .to_string(),
                citation: "7 CFR 273.4(a)(2)".to_string(),
            })
        } else {
            Ok(AlienEligibilityResult {
                eligible: true,
                reason: "Asylee with 7+ years of qualified status; \
                         eligible as qualified alien"
                    .to_string(),
                citation: "7 CFR 273.4(a)(6)".to_string(),
            })
        };
    }

    // Rule 4: Cuban/Haitian entrants and trafficking victims
    if input.immigration_status_category == "CUBAN_HAITIAN_ENTRANT"
        || input.immigration_status_category == "TRAFFICKING_VICTIM"
    {
        return Ok(AlienEligibilityResult {
            eligible: true,
            reason: format!(
                "{}; eligible from date of entry/certification",
                input.immigration_status_category
            ),
            citation: "7 CFR 273.4(a)(3)".to_string(),
        });
    }

    // Rule 5: Military-connected -- exempt from 5-year bar
    if input.is_military_connected {
        return Ok(AlienEligibilityResult {
            eligible: true,
            reason: "Military-connected qualified alien; exempt from \
                     5-year bar"
                .to_string(),
            citation: "7 CFR 273.4(a)(4)".to_string(),
        });
    }

    // Rule 6: Children under 18 -- no 5-year bar
    if age < 18 {
        return Ok(AlienEligibilityResult {
            eligible: true,
            reason: "Child under 18; qualified alien exempt from \
                     5-year bar"
                .to_string(),
            citation: "7 CFR 273.4(a)(6)".to_string(),
        });
    }

    // Rule 7: Elderly (born before 8/22/1996) lawfully residing
    if input.date_of_birth < prwora_date
        && input.immigration_status_category == "LPR"
    {
        return Ok(AlienEligibilityResult {
            eligible: true,
            reason: "Elderly LPR born before 8/22/1996; eligible as \
                     lawfully residing"
                .to_string(),
            citation: "7 CFR 273.4(a)(6)".to_string(),
        });
    }

    // Rule 8: Disabled qualified aliens
    if input.is_disabled {
        return Ok(AlienEligibilityResult {
            eligible: true,
            reason: "Disabled qualified alien; eligible".to_string(),
            citation: "7 CFR 273.4(a)(6)".to_string(),
        });
    }

    // Rule 9-10: LPR 5-year bar
    if input.immigration_status_category == "LPR" {
        if input.qualified_status_date <= prwora_date {
            // Rule 10: LPR admitted before 8/22/1996 -- grandfathered
            return Ok(AlienEligibilityResult {
                eligible: true,
                reason: "LPR admitted on or before 8/22/1996; \
                         grandfathered"
                    .to_string(),
                citation: "7 CFR 273.4(a)(6)".to_string(),
            });
        }

        // Rule 9: LPR admitted after 8/22/1996 -- 5-year bar
        return if years_qualified >= 5.0 {
            Ok(AlienEligibilityResult {
                eligible: true,
                reason: "LPR with 5+ years of qualified status; \
                         5-year bar satisfied"
                    .to_string(),
                citation: "7 CFR 273.4(a)(6)".to_string(),
            })
        } else {
            Ok(AlienEligibilityResult {
                eligible: false,
                reason: format!(
                    "LPR admitted after 8/22/1996 with {:.1} years of \
                     qualified status; 5-year bar not yet satisfied",
                    years_qualified
                ),
                citation: "8 USC 1613; 7 CFR 273.4(a)(6)".to_string(),
            })
        };
    }

    // Default: unrecognized category -- deny with explanation
    Ok(AlienEligibilityResult {
        eligible: false,
        reason: format!(
            "Immigration status category '{}' is not a recognized \
             qualified alien category for SNAP",
            input.immigration_status_category
        ),
        citation: "7 CFR 273.4(a)".to_string(),
    })
}