Plan: Enrollment Partial-Month Retention (Issue #407)

-- services/canopy-enrollment/migrations/20260511000000_add_partial_retention_to_snap_enrollments.sql
-- SPDX-License-Identifier: AGPL-3.0-or-later
-- Per ADR-001: canopy-enrollment owns this schema.
-- Per ADR-016: forward-only; correcting changes ship as new migrations.
-- Per PAMMS 2415: surface mid-month closure retention so workers and
-- downstream overpayment math can distinguish retained vs recoverable months.

ALTER TABLE snap_enrollments
    ADD COLUMN partial_retention BOOLEAN NOT NULL DEFAULT false,
    ADD COLUMN retained_through  DATE;

[snap.closure]
partial_retention_cutoff_day = 16  # PAMMS 2415: closures on or after this day of month retain the issued benefit

[citations."snap.closure.partial_retention_cutoff_day"]
value = 16
authority = "pamms"
source_ref = "dfcs-snap/modules/snap/pages/2415.adoc"
effective_date = "2026-03-01"
verified_date = "2026-05-11"
notes = "Closures on or after this calendar day of the month allow the household to retain the already-issued allotment for that month (PAMMS 2415)."

#[derive(Debug, Deserialize, utoipa::ToSchema)]
#[serde(deny_unknown_fields)]
pub struct TerminateEnrollmentRequest {
    pub reason: String,
    /// Defaults to today (server clock) if omitted. Workers may backdate for
    /// closures that took effect before the worker logged the action.
    pub closure_date: Option<NaiveDate>,
}

async fn terminate_enrollment(
    Extension(claims): Extension<Claims>,
    State(state): State<AppState>,
    Extension(closure_params): Extension<std::sync::Arc<closure::ClosureParams>>,
    Path(id): Path<EnrollmentId>,
    Json(req): Json<TerminateEnrollmentRequest>,
) -> Result<Json<SnapEnrollment>, ApiError> {
    claims.require_service_caller()?;
    let close_date = req.closure_date.unwrap_or_else(|| Utc::now().date_naive());
    let (partial_retention, retained_through) =
        closure::partial_retention(close_date, closure_params.cutoff_day);

    store::terminate_enrollment(
        state.db.inner(), id, &req.reason, close_date,
        partial_retention, retained_through,
    )
    .await
    .map_err(ApiError::from)?
    .map(Json)
    .ok_or_else(|| ApiError::NotFound("enrollment not found".into()))
}

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

//! Partial-month retention rule per PAMMS 2415.

use chrono::{Datelike, Months, NaiveDate};

pub struct ClosureParams {
    /// Calendar day of month on/after which the household retains the
    /// already-issued allotment. Loaded from
    /// `jurisdiction.toml :: snap.closure.partial_retention_cutoff_day`.
    pub cutoff_day: u32,
}

/// Returns `(partial_retention, retained_through)` for a closure on
/// `close_date`. Retention is asserted only when the closure happens on
/// the cutoff day or later -- earlier closures fall under whole-month
/// recoupment per the existing overpayment pipeline.
pub fn partial_retention(close_date: NaiveDate, cutoff_day: u32) -> (bool, Option<NaiveDate>) {
    if close_date.day() < cutoff_day {
        return (false, None);
    }
    let end_of_month = close_date
        .with_day(1)
        .and_then(|d| d.checked_add_months(Months::new(1)))
        .and_then(|d| d.pred_opt())
        .unwrap_or(close_date);
    (true, Some(end_of_month))
}

pub async fn terminate_enrollment(
    pool: &PgPool,
    id: EnrollmentId,
    reason: &str,
    terminated_date: NaiveDate,
    partial_retention: bool,
    retained_through: Option<NaiveDate>,
) -> Result<Option<SnapEnrollment>, sqlx::Error> {
    sqlx::query_as::<_, SnapEnrollment>(
        r#"UPDATE snap_enrollments
           SET status = 'terminated', terminated_reason = $2,
               terminated_date = $3,
               partial_retention = $4,
               retained_through = $5,
               updated_at = now()
           WHERE id = $1 AND active = true
           RETURNING *"#,
    )
    .bind(id).bind(reason).bind(terminated_date)
    .bind(partial_retention).bind(retained_through)
    .fetch_optional(pool).await
}

pub partial_retention: bool,
pub retained_through: Option<NaiveDate>,