Apply the IBR and PAYE 10-year cap before spousal proration

changelog.d/idr-cap-before-proration.fixed.md

@@ -0,0 +1 @@
+Apply the Income-Based Repayment and Pay As You Earn 10-year standard payment cap before the spousal balance proration, as 34 CFR 685.209(f)(2)-(3) and (g)(1) order them.

policyengine_us/programs.yaml

@@ -1790,7 +1790,7 @@ programs:
     variable: income_based_repayment_payment
     parameter_prefix: gov.ed.student_loans.income_based_repayment
     verified_start_year: 2026
-    notes: Monthly payment (15% or 10% for new borrowers of income above 150% of the poverty guideline on the latest return's AGI, spousal and FFEL proration, cap at the borrower's own 10-year standard payment on their current Direct and FFEL balances, small payment adjustment); zero for borrowers with a Direct Loan made on or after July 1, 2026; tax-dependent borrowers treated as ineligible; interest and forgiveness not modeled; not subtracted from household net income
+    notes: Monthly payment (15% or 10% for new borrowers of income above 150% of the poverty guideline on the latest return's AGI, cap at the borrower's own 10-year standard payment on their current Direct and FFEL balances, then spousal and FFEL proration, small payment adjustment); zero for borrowers with a Direct Loan made on or after July 1, 2026; tax-dependent borrowers treated as ineligible; interest and forgiveness not modeled; not subtracted from household net income
 
   - id: save_plan
     name: SAVE plan (counterfactual)
@@ -1814,7 +1814,7 @@ programs:
     variable: pay_as_you_earn_payment
     parameter_prefix: gov.ed.student_loans.pay_as_you_earn
     verified_start_year: 2026
-    notes: Monthly payment (10% of income above 150% of the poverty guideline on the latest return's AGI, spousal and FFEL proration, cap at the borrower's own 10-year standard payment on their current Direct and FFEL balances, small payment adjustment); tax-dependent borrowers treated as ineligible; zero for borrowers with a Direct Loan made on or after July 1, 2026; enrollment limits (new borrower, repaying under PAYE on July 1, 2024) and the June 30, 2028 end not modeled; interest and forgiveness not modeled; not subtracted from household net income
+    notes: Monthly payment (10% of income above 150% of the poverty guideline on the latest return's AGI, cap at the borrower's own 10-year standard payment on their current Direct and FFEL balances, then spousal and FFEL proration, small payment adjustment); tax-dependent borrowers treated as ineligible; zero for borrowers with a Direct Loan made on or after July 1, 2026; enrollment limits (new borrower, repaying under PAYE on July 1, 2024) and the June 30, 2028 end not modeled; interest and forgiveness not modeled; not subtracted from household net income
 
   - id: income_contingent_repayment
     name: Income-Contingent Repayment

policyengine_us/tests/policy/baseline/gov/ed/student_loans/income_based_repayment/income_based_repayment_payment.yaml

@@ -2,10 +2,10 @@
 #   discretionary income = max(AGI - 1.5 x poverty guideline, 0)
 #   payment = lesser of
 #     15% (new borrowers 10%) x discretionary income / 12
-#       x own Direct balance / couple's Direct and FFEL balance ((g)(1)(i)-(ii))
 #     and the borrower's own 10-year standard payment on their Direct and FFEL
-#       loans (1098e(b)(6)(A); (f)(2)(ii), (f)(3)(ii))
-#       x own Direct balance / own Direct and FFEL balance ((g)(1)(ii))
+#       loans (1098e(b)(6)(A); (f)(2)(ii), (f)(3)(ii)),
+#   times own Direct balance / couple's Direct and FFEL balance
+#     ((g)(1)(i)-(ii), applied to the lesser-of amount),
 #   rounded to the cent; under 5 -> 0; 5 to under 10 -> 10; at most the
 #   borrower's Direct balance.
 # 2026 guideline in the 48 states: 15,960 + 5,680 per additional person.
@@ -193,10 +193,10 @@
         members: [person1, person2]
         state_code: TX
   output:
-    # 1.5 x 21,640 = 32,460; 15% x 47,540 / 12 = 594.25.
-    # Shares 75% and 25%: 445.69 and 148.56, below the caps of 666.12 and
-    # 222.04.
-    income_based_repayment_payment: [445.69, 148.56]
+    # 1.5 x 21,640 = 32,460; 15% x 47,540 / 12 = 594.25. Own standard
+    # payments 666.12 and 222.04. min(594.25, 666.12) x 75% = 445.69 and
+    # min(594.25, 222.04) x 25% = 55.51 (685.209(f)(2)-(3), then (g)(1)).
+    income_based_repayment_payment: [445.69, 55.51]
 
 - name: Case 9, married filing separately excludes the spouse's income.
   period: 2026-01
@@ -446,10 +446,12 @@
         state_code: TX
   output:
     # Issue #10411 example. 1.5 x 21,640 = 32,460; 15% x 48,000 / 12 = 600,
-    # split 50/50: 300 each. Standard payments: 30,000 / 120 = 250 and
-    # 30,000 x 0.01 / (1 - 1.01 ^ -120) = 430.41. min(300, 250) = 250 and
-    # min(300, 430.41) = 300 (20 U.S.C. 1098e(b)(6)(A)).
-    income_based_repayment_payment: [250, 300]
+    # with balance shares of 50% each. Standard payments: 30,000 / 120 = 250
+    # and 30,000 x 0.01 / (1 - 1.01 ^ -120) = 430.4128. min(600, 250) x 50% =
+    # 125 and min(600, 430.4128) x 50% = 215.2064 -> 215.21 (20 U.S.C.
+    # 1098e(b)(6)(A); 685.209(f)(2)-(3), then (g)(1)). Capping after
+    # proration would give min(300, 250) = 250 and min(300, 430.41) = 300.
+    income_based_repayment_payment: [125, 215.21]
 
 - name: Case 19, each spouse's own standard payment caps a high income.
   period: 2026-01
@@ -474,9 +476,10 @@
         members: [person1, person2]
         state_code: TX
   output:
-    # 15% x (96,460 - 32,460) / 12 = 800, split 50/50: 400 each.
-    # min(400, 250) = 250 and min(400, 430.41) = 400.
-    income_based_repayment_payment: [250, 400]
+    # 15% x (96,460 - 32,460) / 12 = 800, above both standard payments.
+    # min(800, 250) x 50% = 125 and min(800, 430.4128) x 50% = 215.21.
+    # Capping after proration would give 250 and 400.
+    income_based_repayment_payment: [125, 215.21]
 
 - name: Case 20, spouses keep their own new-borrower and other-borrower rates.
   period: 2026-01
@@ -503,9 +506,11 @@
         state_code: TX
   output:
     # Discretionary income (92,460 - 32,460) / 12 = 5,000. Each spouse's own
-    # standard payment is 333.06. New borrower: min(10% x 5,000 x 50%,
-    # 333.06) = 250. Other borrower: min(15% x 5,000 x 50%, 333.06) = 333.06.
-    income_based_repayment_payment: [250, 333.06]
+    # standard payment is 333.0615. New borrower: min(10% x 5,000 = 500,
+    # 333.0615) x 50% = 166.53. Other borrower: min(15% x 5,000 = 750,
+    # 333.0615) x 50% = 166.53. Capping after proration would give 250 and
+    # 333.06.
+    income_based_repayment_payment: [166.53, 166.53]
 
 - name: Case 21, a spouse's FFEL debt counts in the joint proration.
   period: 2026-01
@@ -532,10 +537,12 @@
         state_code: TX
   output:
     # IBR analogue of rulespec-us#1455 C16. 15% x (60,000 - 32,460) / 12 =
-    # 344.25. The borrower pays 344.25 x 10,000 / 40,000 = 86.06
-    # (685.209(g)(1)(i)-(ii)), under their own standard payment of 111.02; the
-    # spouse has no Direct Loans and owes nothing under the plan.
-    income_based_repayment_payment: [86.06, 0]
+    # 344.25, above the borrower's own standard payment of 111.0205. The
+    # borrower pays min(344.25, 111.0205) x 10,000 / 40,000 = 27.7551 ->
+    # 27.76 (685.209(f)(2)-(3), then (g)(1)(i)-(ii)); the spouse has no Direct
+    # Loans and owes nothing under the plan. Capping after proration would
+    # give min(86.06, 111.02) = 86.06.
+    income_based_repayment_payment: [27.76, 0]
 
 - name: Case 22, a borrower's own FFEL loans reduce the Direct Loan payment.
   period: 2026-01
@@ -574,10 +581,11 @@
         members: [person2]
         state_code: TX
   output:
-    # 685.209(g)(1)(ii): x 10,000 / 40,000 = 25%. Cap on all 40,000 of
-    # eligible loans: 444.08, of which the Direct Loans carry 25% = 111.02.
-    # person1: min(200.75 x 25%, 111.02) = 50.19.
-    # person2: min(950.75 x 25%, 111.02) = 111.02.
+    # 685.209(g)(1)(ii): x 10,000 / 40,000 = 25%. Standard payment on all
+    # 40,000 of eligible loans: 444.08. No spouse debt, so the order of cap
+    # and proration does not matter.
+    # person1: min(200.75, 444.08) x 25% = 50.19.
+    # person2: min(950.75, 444.08) x 25% = 111.02.
     income_based_repayment_payment: [50.19, 111.02]
 
 - name: Case 23, a Direct Loan balance under 10 dollars caps the 10 dollar minimum payment.
@@ -634,8 +642,129 @@
   output:
     # The spouse's Direct Loans stay eligible loans (685.209(b)(5)); (d)(5)
     # only stops the plan from repaying them. (60,000 - 1.5 x 20,000) / 12 =
-    # 2,500. Income-Based Repayment 15% = 375 and Pay As You Earn 10% = 250,
-    # each x 30,000 / 60,000 = 187.50 and 125, under the 333.06 standard
-    # payment; the spouse owes 0.
-    income_based_repayment_payment: [187.5, 0]
+    # 2,500. Income-Based Repayment: min(15% x 2,500 = 375, 333.0615) x
+    # 30,000 / 60,000 = 166.53. Pay As You Earn: min(10% x 2,500 = 250,
+    # 333.0615) x 50% = 125. The spouse owes 0. Capping after proration
+    # would give IBR min(187.50, 333.06) = 187.50.
+    income_based_repayment_payment: [166.53, 0]
     pay_as_you_earn_payment: [125, 0]
+
+- name: Case 25, joint filers at 6 percent pay each standard payment times their balance share.
+  period: 2026-01
+  absolute_error_margin: 0.01
+  input:
+    people:
+      person1:
+        age: 40
+        federal_student_loan_balance: 30_000
+        federal_student_loan_interest_rate: 0.06
+      person2:
+        age: 38
+        federal_student_loan_balance: 30_000
+        federal_student_loan_interest_rate: 0.06
+    tax_units:
+      tax_unit:
+        members: [person1, person2]
+        filing_status: JOINT
+        adjusted_gross_income: 80_460
+    households:
+      household:
+        members: [person1, person2]
+        state_code: TX
+  output:
+    # 15% x (80,460 - 32,460) / 12 = 600. Each spouse's own standard payment
+    # is 30,000 x 0.005 / (1 - 1.005 ^ -120) = 333.0615. min(600, 333.0615) x
+    # 50% = 166.53 each. Capping after proration would give min(300, 333.06)
+    # = 300 each.
+    income_based_repayment_payment: [166.53, 166.53]
+
+- name: Case 26, a low income-based amount is prorated the same way under either order.
+  period: 2026-01
+  absolute_error_margin: 0.01
+  input:
+    people:
+      person1:
+        age: 40
+        federal_student_loan_balance: 30_000
+        federal_student_loan_interest_rate: 0.06
+      person2:
+        age: 38
+        federal_student_loan_balance: 30_000
+        federal_student_loan_interest_rate: 0.06
+    tax_units:
+      tax_unit:
+        members: [person1, person2]
+        filing_status: JOINT
+        adjusted_gross_income: 40_460
+    households:
+      household:
+        members: [person1, person2]
+        state_code: TX
+  output:
+    # 15% x (40,460 - 32,460) / 12 = 100, below each 333.0615 standard
+    # payment. min(100, 333.0615) x 50% = 50 each.
+    income_based_repayment_payment: [50, 50]
+
+- name: Case 27, with 10 and 15 percent rates the cap binds on one spouse only.
+  period: 2026-01
+  absolute_error_margin: 0.01
+  input:
+    people:
+      person1:
+        age: 30
+        federal_student_loan_balance: 30_000
+        federal_student_loan_interest_rate: 0.06
+        is_income_based_repayment_new_borrower: true
+      person2:
+        age: 40
+        federal_student_loan_balance: 30_000
+        federal_student_loan_interest_rate: 0.06
+    tax_units:
+      tax_unit:
+        members: [person1, person2]
+        filing_status: JOINT
+        adjusted_gross_income: 68_460
+    households:
+      household:
+        members: [person1, person2]
+        state_code: TX
+  output:
+    # Discretionary income (68,460 - 32,460) / 12 = 3,000. New borrower:
+    # min(10% x 3,000 = 300, 333.0615) x 50% = 150, under the cap. Other
+    # borrower: min(15% x 3,000 = 450, 333.0615) x 50% = 166.53, at the cap.
+    # Capping after proration would give 150 and min(225, 333.06) = 225.
+    income_based_repayment_payment: [150, 166.53]
+
+- name: Case 28, both spouses' FFEL loans enter the proration of each spouse's capped amount.
+  period: 2026-01
+  absolute_error_margin: 0.01
+  input:
+    people:
+      person1:
+        age: 40
+        federal_student_loan_balance: 10_000
+        federal_ffel_loan_balance: 10_000
+        federal_student_loan_interest_rate: 0.06
+      person2:
+        age: 38
+        federal_student_loan_balance: 20_000
+        federal_ffel_loan_balance: 20_000
+        federal_student_loan_interest_rate: 0.06
+    tax_units:
+      tax_unit:
+        members: [person1, person2]
+        filing_status: JOINT
+        adjusted_gross_income: 80_460
+    households:
+      household:
+        members: [person1, person2]
+        state_code: TX
+  output:
+    # 15% x (80,460 - 32,460) / 12 = 600. Own standard payments on Direct and
+    # FFEL loans: 20,000 -> 222.0410 and 40,000 -> 444.0820. Balance shares,
+    # (g)(1)(i) x (g)(1)(ii): 10,000 / 60,000 = 1/6 and 20,000 / 60,000 = 1/3.
+    # person1: min(600, 222.0410) / 6 = 37.0068 -> 37.01.
+    # person2: min(600, 444.0820) / 3 = 148.0273 -> 148.03.
+    # Capping after proration (cap x own Direct fraction of 50%) would give
+    # min(100, 111.02) = 100 and min(200, 222.04) = 200.
+    income_based_repayment_payment: [37.01, 148.03]

policyengine_us/tests/policy/baseline/gov/ed/student_loans/pay_as_you_earn/pay_as_you_earn_payment.yaml

@@ -2,10 +2,10 @@
 #   discretionary income = max(AGI - 1.5 x poverty guideline, 0)
 #   payment = lesser of
 #     10% x discretionary income / 12
-#       x own Direct balance / couple's Direct and FFEL balance ((g)(1)(i)-(ii))
 #     and the borrower's own 10-year standard payment on their Direct and FFEL
-#       loans ((f)(2)(ii))
-#       x own Direct balance / own Direct and FFEL balance ((g)(1)(ii))
+#       loans ((f)(2)(ii)),
+#   times own Direct balance / couple's Direct and FFEL balance
+#     ((g)(1)(i)-(ii), applied to the lesser-of amount),
 #   rounded to the cent; under 5 -> 0; 5 to under 10 -> 10; at most the
 #   borrower's Direct balance.
 # 2026 guideline in the 48 states: 15,960 + 5,680 per additional person.
@@ -79,10 +79,11 @@
         members: [person1, person2]
         state_code: TX
   output:
-    # 1.5 x 21,640 = 32,460; 10% x 47,540 / 12 = 396.17.
-    # Shares 2/3 and 1/3: 264.11 and 132.06, below the caps of 444.08 and
-    # 222.04.
-    pay_as_you_earn_payment: [264.11, 132.06]
+    # 1.5 x 21,640 = 32,460; 10% x 47,540 / 12 = 396.17. Own standard
+    # payments 444.0820 and 222.0410. min(396.17, 444.08) x 2/3 = 264.11 and
+    # min(396.17, 222.0410) x 1/3 = 74.0137 -> 74.01. Capping after
+    # proration would give min(132.06, 222.04) = 132.06 for the spouse.
+    pay_as_you_earn_payment: [264.11, 74.01]
 
 - name: Case 4, each spouse's own standard payment caps joint filers who both borrowed.
   period: 2026-01
@@ -107,9 +108,12 @@
         members: [person1, person2]
         state_code: TX
   output:
-    # 10% x (150,000 - 32,460) / 12 = 979.50; shares 80% and 20%: 783.60 and
-    # 195.90, above each spouse's own standard payment of 444.08 and 111.02.
-    pay_as_you_earn_payment: [444.08, 111.02]
+    # 10% x (150,000 - 32,460) / 12 = 979.50, above each spouse's own
+    # standard payment of 444.0820 and 111.0205. Shares 80% and 20%:
+    # 444.0820 x 80% = 355.2656 -> 355.27 and 111.0205 x 20% = 22.2041 ->
+    # 22.20. Capping after proration would give min(783.60, 444.08) = 444.08
+    # and min(195.90, 111.02) = 111.02.
+    pay_as_you_earn_payment: [355.27, 22.20]
 
 - name: Case 5, a payment under 5 dollars becomes zero.
   period: 2026-01
@@ -256,10 +260,11 @@
         state_code: TX
   output:
     # Issue #10411 example. 1.5 x 21,640 = 32,460; 10% x 72,000 / 12 = 600,
-    # split 50/50: 300 each. Standard payments: 30,000 / 120 = 250 and
-    # 30,000 x 0.01 / (1 - 1.01 ^ -120) = 430.41. min(300, 250) = 250 and
-    # min(300, 430.41) = 300.
-    pay_as_you_earn_payment: [250, 300]
+    # with balance shares of 50% each. Standard payments: 30,000 / 120 = 250
+    # and 30,000 x 0.01 / (1 - 1.01 ^ -120) = 430.4128. min(600, 250) x 50% =
+    # 125 and min(600, 430.4128) x 50% = 215.2064 -> 215.21. Capping after
+    # proration would give 250 and 300.
+    pay_as_you_earn_payment: [125, 215.21]
 
 - name: Case 11, each spouse's own standard payment caps a high income.
   period: 2026-01
@@ -284,9 +289,10 @@
         members: [person1, person2]
         state_code: TX
   output:
-    # 10% x (128,460 - 32,460) / 12 = 800, split 50/50: 400 each.
-    # min(400, 250) = 250 and min(400, 430.41) = 400.
-    pay_as_you_earn_payment: [250, 400]
+    # 10% x (128,460 - 32,460) / 12 = 800, above both standard payments.
+    # min(800, 250) x 50% = 125 and min(800, 430.4128) x 50% = 215.21.
+    # Capping after proration would give 250 and 400.
+    pay_as_you_earn_payment: [125, 215.21]
 
 - name: Case 12, a spouse's FFEL debt counts in the joint proration.
   period: 2026-01
@@ -312,10 +318,12 @@
         members: [person1, person2]
         state_code: TX
   output:
-    # 10% x (61,000 - 32,460) / 12 = 237.83. The borrower pays
-    # 237.83 x 10,000 / 40,000 = 59.46 (685.209(g)(1)(i)-(ii)), under their own
-    # standard payment of 111.02; the spouse owes nothing.
-    pay_as_you_earn_payment: [59.46, 0]
+    # 10% x (61,000 - 32,460) / 12 = 237.83, above the borrower's own
+    # standard payment of 111.0205. The borrower pays min(237.83, 111.0205) x
+    # 10,000 / 40,000 = 27.7551 -> 27.76 (685.209(f)(2), then
+    # (g)(1)(i)-(ii)); the spouse owes nothing. Capping after proration would
+    # give min(59.46, 111.02) = 59.46.
+    pay_as_you_earn_payment: [27.76, 0]
 
 - name: Case 13, a payment within half a cent below 5 dollars rounds to 5 and rises to 10.
   period: 2026-01
@@ -339,3 +347,33 @@
     # 24,539.52 - 23,940 = 599.52; 10% x 599.52 / 12 = 4.996, which rounds to
     # 5.00 and rises to 10 (the modeling choice in the documentation).
     pay_as_you_earn_payment: 10
+
+- name: Case 14, both spouses' FFEL loans enter the proration of each spouse's capped amount.
+  period: 2026-01
+  absolute_error_margin: 0.01
+  input:
+    people:
+      person1:
+        age: 40
+        federal_student_loan_balance: 10_000
+        federal_ffel_loan_balance: 10_000
+        federal_student_loan_interest_rate: 0.06
+      person2:
+        age: 38
+        federal_student_loan_balance: 20_000
+        federal_ffel_loan_balance: 20_000
+        federal_student_loan_interest_rate: 0.06
+    tax_units:
+      tax_unit:
+        members: [person1, person2]
+        filing_status: JOINT
+        adjusted_gross_income: 104_460
+    households:
+      household:
+        members: [person1, person2]
+        state_code: TX
+  output:
+    # 10% x (104,460 - 32,460) / 12 = 600. Own standard payments 222.0410 and
+    # 444.0820; balance shares 1/6 and 1/3 ((g)(1)(i) x (g)(1)(ii)).
+    # min(600, 222.0410) / 6 = 37.01 and min(600, 444.0820) / 3 = 148.03.
+    pay_as_you_earn_payment: [37.01, 148.03]