fix(reconcile): fill earliest month deficit first in multi-month allocations

Replace proportional split with a fill-first loop that allocates
min(remaining, deficit) to each matched month in user-supplied order,
where deficit = expected - already_paid. Prior transactions' contributions
are now properly accounted for, so a second payment on overlapping months
fills only what's still owed instead of splitting proportionally by total
expected. Surplus after all deficits are covered goes to the credit bucket.

Fixes: Matyáš Thér 200+550 showing 566/183 instead of 500/250.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

go/internal/domain/reconcile/reconcile.go

@@ -115,10 +115,11 @@ type monthExpected struct {
 	expected int
 }
 
-// Reconcile matches transactions to members and months using three allocation phases:
-//  1. Greedy: payment ≥ total expected → fill each month exactly; overflow → credit.
-//  2. Proportional: payment < total → distribute by each month's share; last absorbs float remainder.
-//  3. Even-split fallback: all expected fees are 0 (prepayment) → divide equally.
+// Reconcile matches transactions to members and months using two allocation phases:
+//  1. Fill-first: iterate matched months in user-supplied order, allocating min(remaining,
+//     deficit) to each month where deficit = expected − already-paid. Surplus → credit.
+//     Handles both the "greedy" (payment covers all) and "partial" cases in one pass.
+//  2. Even-split fallback: all expected fees are 0 (prepayment) → divide equally.
 //
 // defaultYear seeds czech.ParseMonthReferences in the inference fallback.
 // Pass time.Now().Year() in production; pass a fixed year in tests.
@@ -317,34 +318,26 @@ func Reconcile(
 				totalExpected += mw.expected
 			}
 
-			if totalExpected > 0 && inWindowShare >= float64(totalExpected) {
-				// Greedy: payment covers all expected fees; overflow → credit
-				credits[memberName] += int(inWindowShare - float64(totalExpected))
-				for _, mw := range inWindow {
-					alloc := float64(mw.expected)
-					md := ledger[memberName][mw.month]
-					md.Paid += alloc
-					md.Transactions = append(md.Transactions, TxEntry{
-						Amount:     alloc,
-						Date:       tx.Date,
-						Sender:     tx.Sender,
-						Message:    tx.Message,
-						Confidence: string(m.Confidence),
-					})
-					ledger[memberName][mw.month] = md
-				}
-			} else if totalExpected > 0 {
-				// Proportional: distribute by each month's share; last month absorbs float remainder
+			if totalExpected > 0 {
+				// Fill-first: iterate inWindow in matched-months order (chronological by
+				// convention), allocating min(remaining, deficit) to each month. Deficit
+				// is net of what prior transactions already paid, so a second payment on
+				// the same months correctly fills only what remains due. Any surplus after
+				// all deficits are covered goes to the credit bucket.
 				remaining := inWindowShare
-				for i, mw := range inWindow {
-					var alloc float64
-					if i == len(inWindow)-1 {
-						alloc = remaining
-					} else {
-						alloc = inWindowShare * float64(mw.expected) / float64(totalExpected)
-					}
-					remaining -= alloc
+				for _, mw := range inWindow {
 					md := ledger[memberName][mw.month]
+					deficit := float64(mw.expected) - md.Paid
+					if deficit < 0 {
+						deficit = 0
+					}
+					alloc := remaining
+					if deficit < alloc {
+						alloc = deficit
+					}
+					if alloc <= 0 {
+						continue
+					}
 					md.Paid += alloc
 					md.Transactions = append(md.Transactions, TxEntry{
 						Amount:     alloc,
@@ -354,6 +347,10 @@ func Reconcile(
 						Confidence: string(m.Confidence),
 					})
 					ledger[memberName][mw.month] = md
+					remaining -= alloc
+				}
+				if remaining > 0 {
+					credits[memberName] += int(remaining)
 				}
 			} else {
 				// Even-split fallback: prepayment before attendance recorded

go/internal/domain/reconcile/reconcile_test.go

@@ -111,36 +111,26 @@ func TestReconcileGreedyOverpaymentGoesToCredit(t *testing.T) {
 	}
 }
 
-func TestReconcileProportionalUnderpayment(t *testing.T) {
+func TestReconcileUnderpaymentFillsEarliestFirst(t *testing.T) {
 	t.Parallel()
 	members := []Member{{
 		Name: "Alice", Tier: "A",
 		Fees: map[string]FeeData{"2026-02": {Expected: 750, Attendance: 3}, "2026-03": {Expected: 350, Attendance: 3}, "2026-04": {Expected: 750, Attendance: 3}},
 	}}
 	sortedMonths := []string{"2026-02", "2026-03", "2026-04"}
-	amount := 1250.0
 
-	result := Reconcile(members, sortedMonths, []Transaction{tx("Alice", "2026-02, 2026-03, 2026-04", amount)}, nil, defaultYear)
+	result := Reconcile(members, sortedMonths, []Transaction{tx("Alice", "2026-02, 2026-03, 2026-04", 1250)}, nil, defaultYear)
 
 	months := result.Members["Alice"].Months
-	paid02 := months["2026-02"].Paid
-	paid03 := months["2026-03"].Paid
-	paid04 := months["2026-04"].Paid
-
-	if paid02 >= 750 {
-		t.Errorf("2026-02 should be underpaid, got %f", paid02)
+	// 02 filled first (750), then 03 (350), then remainder 150 to 04
+	if math.Abs(months["2026-02"].Paid-750) > 0.01 {
+		t.Errorf("02: want 750, got %f", months["2026-02"].Paid)
 	}
-	if paid03 >= 350 {
-		t.Errorf("2026-03 should be underpaid, got %f", paid03)
+	if math.Abs(months["2026-03"].Paid-350) > 0.01 {
+		t.Errorf("03: want 350, got %f", months["2026-03"].Paid)
 	}
-	if paid04 >= 750 {
-		t.Errorf("2026-04 should be underpaid, got %f", paid04)
-	}
-	if math.Abs(paid02+paid03+paid04-amount) > 0.01 {
-		t.Errorf("sum of paid want %f, got %f", amount, paid02+paid03+paid04)
-	}
-	if math.Abs(paid02-paid04) > 0.01 {
-		t.Errorf("02 and 04 have equal expected, want equal paid: %f vs %f", paid02, paid04)
+	if math.Abs(months["2026-04"].Paid-150) > 0.01 {
+		t.Errorf("04: want 150, got %f", months["2026-04"].Paid)
 	}
 }
 
@@ -374,3 +364,52 @@ func TestReconcileNoTransactionsAllUnpaid(t *testing.T) {
 		t.Errorf("no txs: want empty unmatched, got %v", result.Unmatched)
 	}
 }
+
+// Payment < total expected → fill earliest months first, spill remainder to later.
+func TestUnderpaymentFillsEarliestFirst(t *testing.T) {
+	t.Parallel()
+	members := []Member{{Name: "Alice", Tier: "A", Fees: map[string]FeeData{
+		"2026-02": {Expected: 750, Attendance: 3},
+		"2026-03": {Expected: 350, Attendance: 3},
+		"2026-04": {Expected: 750, Attendance: 3},
+	}}}
+	txs := []Transaction{tx("Alice", "2026-02, 2026-03, 2026-04", 1250)}
+
+	result := Reconcile(members, []string{"2026-02", "2026-03", "2026-04"}, txs, nil, defaultYear)
+	months := result.Members["Alice"].Months
+
+	// 02 filled first (750), then 03 (350), then remainder 150 to 04
+	if math.Abs(months["2026-02"].Paid-750) > 0.01 {
+		t.Errorf("02: want 750, got %f", months["2026-02"].Paid)
+	}
+	if math.Abs(months["2026-03"].Paid-350) > 0.01 {
+		t.Errorf("03: want 350, got %f", months["2026-03"].Paid)
+	}
+	if math.Abs(months["2026-04"].Paid-150) > 0.01 {
+		t.Errorf("04: want 150, got %f", months["2026-04"].Paid)
+	}
+}
+
+// Prior txn fills 02 partially; later txn finishes 02 then spills to 03.
+func TestFillFirstAcrossTwoTransactions(t *testing.T) {
+	t.Parallel()
+	members := []Member{{Name: "Matyáš", Tier: "A", Fees: map[string]FeeData{
+		"2026-02": {Expected: 500, Attendance: 2},
+		"2026-03": {Expected: 250, Attendance: 1},
+	}}}
+	sortedMonths := []string{"2026-02", "2026-03"}
+	txs := []Transaction{
+		tx("Matyáš", "2026-02", 200),
+		tx("Matyáš", "2026-02, 2026-03", 550),
+	}
+
+	result := Reconcile(members, sortedMonths, txs, nil, defaultYear)
+	months := result.Members["Matyáš"].Months
+
+	if math.Abs(months["2026-02"].Paid-500) > 0.01 {
+		t.Errorf("02: want 500, got %f", months["2026-02"].Paid)
+	}
+	if math.Abs(months["2026-03"].Paid-250) > 0.01 {
+		t.Errorf("03: want 250, got %f", months["2026-03"].Paid)
+	}
+}

go/tests/fixtures/reconcile/03_proportional_remainder.json

@@ -1,7 +1,7 @@
 {
   "case": "03_proportional_remainder",
   "func": "scripts.match_payments.reconcile",
-  "captured_at": "2026-05-06",
+  "captured_at": "2026-05-11",
   "input": {
     "members": [
       {
@@ -54,10 +54,10 @@
             "original_expected": 750,
             "attendance_count": 3,
             "exception": null,
-            "paid": 324.3243243243243,
+            "paid": 750.0,
             "transactions": [
               {
-                "amount": 324.3243243243243,
+                "amount": 750.0,
                 "date": "2026-03-10",
                 "sender": "Member_d035d9f9",
                 "message": "",
@@ -70,10 +70,10 @@
             "original_expected": 750,
             "attendance_count": 2,
             "exception": null,
-            "paid": 324.3243243243243,
+            "paid": 50.0,
             "transactions": [
               {
-                "amount": 324.3243243243243,
+                "amount": 50.0,
                 "date": "2026-03-10",
                 "sender": "Member_d035d9f9",
                 "message": "",
@@ -86,25 +86,17 @@
             "original_expected": 350,
             "attendance_count": 2,
             "exception": null,
-            "paid": 151.35135135135135,
-            "transactions": [
-              {
-                "amount": 151.35135135135135,
-                "date": "2026-03-10",
-                "sender": "Member_d035d9f9",
-                "message": "",
-                "confidence": "auto"
-              }
-            ]
+            "paid": 0,
+            "transactions": []
           }
         },
         "other_transactions": [],
-        "total_balance": -1051
+        "total_balance": -1050
       }
     },
     "unmatched": [],
     "credits": {
-      "Member_d035d9f9": -1051
+      "Member_d035d9f9": -1050
     }
   }
 }

go/tests/fixtures/reconcile/09_multiperson_multimonth.json

@@ -1,7 +1,7 @@
 {
   "case": "09_multiperson_multimonth",
   "func": "scripts.match_payments.reconcile",
-  "captured_at": "2026-05-06",
+  "captured_at": "2026-05-11",
   "input": {
     "members": [
       {
@@ -63,10 +63,10 @@
             "original_expected": 750,
             "attendance_count": 3,
             "exception": null,
-            "paid": 500.0,
+            "paid": 750.0,
             "transactions": [
               {
-                "amount": 500.0,
+                "amount": 750.0,
                 "date": "2026-02-15",
                 "sender": "Member_d035d9f9",
                 "message": "",
@@ -79,10 +79,10 @@
             "original_expected": 750,
             "attendance_count": 2,
             "exception": null,
-            "paid": 500.0,
+            "paid": 250.0,
             "transactions": [
               {
-                "amount": 500.0,
+                "amount": 250.0,
                 "date": "2026-02-15",
                 "sender": "Member_d035d9f9",
                 "message": "",
@@ -102,10 +102,10 @@
             "original_expected": 750,
             "attendance_count": 2,
             "exception": null,
-            "paid": 681.8181818181819,
+            "paid": 750.0,
             "transactions": [
               {
-                "amount": 681.8181818181819,
+                "amount": 750.0,
                 "date": "2026-02-15",
                 "sender": "Member_d035d9f9",
                 "message": "",
@@ -118,10 +118,10 @@
             "original_expected": 350,
             "attendance_count": 2,
             "exception": null,
-            "paid": 318.18181818181813,
+            "paid": 250.0,
             "transactions": [
               {
-                "amount": 318.18181818181813,
+                "amount": 250.0,
                 "date": "2026-02-15",
                 "sender": "Member_d035d9f9",
                 "message": "",
@@ -131,13 +131,13 @@
           }
         },
         "other_transactions": [],
-        "total_balance": -101
+        "total_balance": -100
       }
     },
     "unmatched": [],
     "credits": {
       "Member_d035d9f9": -500,
-      "Member_f4a93e46": -101
+      "Member_f4a93e46": -100
     }
   }
 }