Plan: Intentional Program Violations (IPV) and Administrative Disqualification Hearings (ADH)

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

-- Intentional Program Violation cases (7 CFR 273.16)
-- Agency-initiated enforcement actions tracked through the ADH lifecycle.
CREATE TABLE ipv_cases (
    id UUID PRIMARY KEY,
    household_id UUID NOT NULL,
    person_id UUID NOT NULL,        -- the individual alleged to have committed IPV
    program TEXT NOT NULL,           -- 'snap', 'tanf', etc.
    allegation_type TEXT NOT NULL,   -- 'fraud', 'misrepresentation', 'concealment', 'trafficking'
    allegation_description TEXT NOT NULL,
    evidence_summary TEXT NOT NULL,
    referred_by UUID NOT NULL,       -- worker who referred the case
    referred_at TIMESTAMPTZ NOT NULL,
    overissuance_amount NUMERIC(10,2),  -- estimated overpayment due to IPV
    status TEXT NOT NULL DEFAULT 'referred',
    -- Status lifecycle:
    -- 'referred'          → initial referral by worker
    -- 'adh_scheduled'     → hearing date set
    -- 'adh_notice_sent'   → 30-day advance notice mailed (7 CFR 273.16(b))
    -- 'adh_completed'     → hearing held and decision recorded
    -- 'waiver_accepted'   → individual waived ADH, accepted disqualification (7 CFR 273.16(b)(4))
    -- 'court_referred'    → case sent to court in lieu of ADH (7 CFR 273.16(f))
    -- 'disqualified'      → disqualification imposed
    -- 'cleared'           → IPV not confirmed at ADH
    -- 'withdrawn'         → agency withdrew the referral
    adh_scheduled_date DATE,
    adh_notice_sent_at TIMESTAMPTZ,
    adh_decision TEXT,              -- 'ipv_confirmed', 'ipv_not_confirmed', 'default_decision'
    adh_decision_at TIMESTAMPTZ,
    disqualification_start_date DATE,
    disqualification_end_date DATE,  -- NULL for permanent disqualification
    disqualification_offense_number INTEGER,  -- 1st, 2nd, 3rd
    prior_ipv_count INTEGER NOT NULL DEFAULT 0,
    active BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX ipv_cases_person_idx ON ipv_cases (person_id);
CREATE INDEX ipv_cases_household_idx ON ipv_cases (household_id);
CREATE INDEX ipv_cases_status_idx ON ipv_cases (status) WHERE active = true;

-- Timeline events for audit trail on IPV cases.
-- Every state transition and significant action is recorded.
CREATE TABLE ipv_timeline_events (
    id UUID PRIMARY KEY,
    ipv_case_id UUID NOT NULL REFERENCES ipv_cases(id),
    event_type TEXT NOT NULL,
    -- Event types:
    -- 'referred'                    → case created
    -- 'adh_scheduled'              → hearing date set
    -- 'adh_notice_sent'            → advance notice mailed
    -- 'adh_held'                   → hearing conducted
    -- 'adh_default'                → individual did not appear (7 CFR 273.16(b)(12))
    -- 'adh_decision'               → hearing officer decision recorded
    -- 'waiver_signed'              → individual signed waiver (7 CFR 273.16(b)(4))
    -- 'court_referred'             → case referred to court (7 CFR 273.16(f))
    -- 'disqualification_imposed'   → penalty applied
    -- 'disqualification_ended'     → penalty period expired
    -- 'overissuance_claim_created' → claim established (7 CFR 273.16(i))
    event_data JSONB,
    occurred_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    recorded_by UUID  -- worker who recorded the event; null for system events
);

CREATE INDEX ipv_timeline_case_idx ON ipv_timeline_events (ipv_case_id, occurred_at);

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

use chrono::{NaiveDate, Utc};
use rust_decimal::Decimal;
use serde::{Deserialize, Serialize};
use uuid::Uuid;

/// Allegation type for an IPV case (7 CFR 273.16(a)).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum AllegationType {
    /// Intentional false statement or misrepresentation
    Fraud,
    /// Misrepresentation of identity, residence, or household composition
    Misrepresentation,
    /// Concealment of facts to obtain benefits
    Concealment,
    /// Selling, exchanging, or otherwise trafficking SNAP benefits (7 CFR 273.16(e)(1)(iv))
    Trafficking,
}

/// Status of an IPV case through the ADH lifecycle.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum IpvCaseStatus {
    Referred,
    AdhScheduled,
    AdhNoticeSent,
    AdhCompleted,
    WaiverAccepted,
    CourtReferred,
    Disqualified,
    Cleared,
    Withdrawn,
}

/// ADH decision outcome.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum AdhDecision {
    /// IPV confirmed by hearing officer based on clear and convincing evidence
    IpvConfirmed,
    /// IPV not confirmed — insufficient evidence
    IpvNotConfirmed,
    /// Default decision — individual failed to appear (7 CFR 273.16(b)(12))
    DefaultDecision,
}

/// Request to create a new IPV referral.
pub struct CreateIpvReferralRequest {
    pub household_id: Uuid,
    pub person_id: Uuid,
    pub program: String,
    pub allegation_type: AllegationType,
    pub allegation_description: String,
    pub evidence_summary: String,
    pub referred_by: Uuid,
    pub overissuance_amount: Option<Decimal>,
}

/// Request to schedule an ADH date.
pub struct ScheduleAdhRequest {
    pub adh_date: NaiveDate,
}

/// Request to record an ADH decision.
pub struct RecordAdhDecisionRequest {
    pub decision: AdhDecision,
}

/// Request to record a waiver acceptance.
pub struct RecordWaiverRequest {
    pub waiver_signed_date: NaiveDate,
}

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

use chrono::{Months, NaiveDate};

/// Disqualification period result.
pub struct DisqualificationPeriod {
    /// Start date of disqualification
    pub start_date: NaiveDate,
    /// End date; None means permanent disqualification
    pub end_date: Option<NaiveDate>,
    /// Which offense number this represents (1, 2, 3+)
    pub offense_number: i32,
    /// Whether this is a permanent disqualification
    pub permanent: bool,
}

/// Calculate the disqualification period per 7 CFR 273.16(e).
///
/// Penalty schedule:
/// - 1st offense: 12 months (7 CFR 273.16(e)(1)(i))
/// - 2nd offense: 24 months (7 CFR 273.16(e)(1)(ii))
/// - 3rd+ offense: permanent (7 CFR 273.16(e)(1)(iii))
/// - Trafficking (any offense): permanent (7 CFR 273.16(e)(1)(iv))
///
/// `prior_ipv_count` includes disqualifications across ALL programs,
/// not just the program in the current case (7 CFR 273.16(e)(1)).
pub fn calculate_disqualification_period(
    start_date: NaiveDate,
    prior_ipv_count: i32,
    is_trafficking: bool,
) -> DisqualificationPeriod {
    let offense_number = prior_ipv_count + 1;

    // Trafficking is always permanent, regardless of offense number
    if is_trafficking {
        return DisqualificationPeriod {
            start_date,
            end_date: None,
            offense_number,
            permanent: true,
        };
    }

    match offense_number {
        1 => DisqualificationPeriod {
            start_date,
            end_date: Some(start_date + Months::new(12)),
            offense_number,
            permanent: false,
        },
        2 => DisqualificationPeriod {
            start_date,
            end_date: Some(start_date + Months::new(24)),
            offense_number,
            permanent: false,
        },
        _ => DisqualificationPeriod {
            start_date,
            end_date: None,
            offense_number,
            permanent: true,
        },
    }
}

referred → adh_scheduled → adh_notice_sent → adh_completed → disqualified
                                                            → cleared
         → waiver_accepted → disqualified
         → court_referred → disqualified
                          → cleared
         → withdrawn

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

use chrono::NaiveDate;
use serde::Serialize;
use uuid::Uuid;

/// Response from the active disqualification check endpoint.
#[derive(Debug, Serialize)]
pub struct ActiveDisqualificationResponse {
    /// Whether the person has an active disqualification
    pub disqualified: bool,
    /// Program the disqualification applies to (if disqualified)
    pub program: Option<String>,
    /// End date of the disqualification; None means permanent
    pub disqualification_end_date: Option<NaiveDate>,
    /// The IPV case ID that imposed the disqualification
    pub ipv_case_id: Option<Uuid>,
}

// Routing key: ipv.case_referred
// Published when: a worker creates an IPV referral
{
  "ipv_case_id": "uuid",
  "person_id": "uuid",
  "program": "snap"
}

// Routing key: ipv.adh_scheduled
// Published when: an ADH date is set
{
  "ipv_case_id": "uuid",
  "person_id": "uuid",
  "adh_date": "2026-08-15"
}

// Routing key: ipv.disqualification_imposed
// Published when: disqualification penalty is applied (after ADH, waiver, or court decision)
{
  "ipv_case_id": "uuid",
  "person_id": "uuid",
  "program": "snap",
  "offense_number": 1,
  "permanent": false
}

// Routing key: ipv.overissuance_claim_created
// Published when: overissuance claim is established upon IPV confirmation (7 CFR 273.16(i))
{
  "ipv_case_id": "uuid",
  "person_id": "uuid",
  "program": "snap"
}

// Routing key: ipv.case_cleared
// Published when: ADH determines IPV not confirmed
{
  "ipv_case_id": "uuid",
  "person_id": "uuid",
  "program": "snap"
}

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

use axum::{Router, routing::{get, post, put}};

pub fn ipv_routes() -> Router<AppState> {
    Router::new()
        .route("/v1/ipv/cases", post(create_ipv_referral).get(list_ipv_cases))
        .route("/v1/ipv/cases/{id}", get(get_ipv_case))
        .route("/v1/ipv/cases/{id}/schedule-adh", put(schedule_adh))
        .route("/v1/ipv/cases/{id}/send-notice", put(send_notice))
        .route("/v1/ipv/cases/{id}/record-decision", put(record_decision))
        .route("/v1/ipv/cases/{id}/waiver", put(record_waiver))
        .route("/v1/ipv/cases/{id}/impose-disqualification", put(impose_disqualification))
        .route("/v1/ipv/disqualifications/active", get(check_active_disqualification))
}