Release 2.5.6: forward-coverage so upcoming income offsets obligations

Author: rollecode

CHANGELOG.md

@@ -1,3 +1,7 @@
+### 2.5.6: 2026-04-17
+
+* Stop reserving obligations from current balance when upcoming income covers them
+
 ### 2.5.5: 2026-04-16
 
 * Use real BookBeat serif B logo from brand wordmark

src/lib/daily-budget.ts

@@ -80,59 +80,73 @@ export function calculateDailyBudget(params: {
   const totalDays = endAbsDay - today;
   if (totalDays <= 0) return { dailyBudget: 0, tightestSegment: null, segmentCount: 0 };
 
-  // No future income counted — only current balance. Recalculates when income arrives.
-  const windowIncome = 0;
-
-  // Build obligations in window
-  let windowObligations = 0;
-
-  // This month's unpaid bills and debts
+  // Collect obligations in window with absolute due day
+  const obligationEvents: { absDay: number; amount: number }[] = [];
   for (const b of unpaidBills) {
     if (b.dueDay > today && b.dueDay <= Math.min(daysInMonth, endAbsDay)) {
-      windowObligations += b.amount;
+      obligationEvents.push({ absDay: b.dueDay, amount: b.amount });
     }
   }
   for (const d of debts) {
     if (d.dueDay > today && d.dueDay <= Math.min(daysInMonth, endAbsDay) && d.amount > 0) {
-      windowObligations += d.amount;
+      obligationEvents.push({ absDay: d.dueDay, amount: d.amount });
     }
   }
-
-  // Next month's bills and debts if window extends past month end
   if (endAbsDay > daysInMonth) {
     const nextMonthEnd = endAbsDay - daysInMonth;
     if (allBills) {
       for (const b of allBills) {
         if (b.dueDay <= nextMonthEnd) {
-          windowObligations += b.amount;
+          obligationEvents.push({ absDay: daysInMonth + b.dueDay, amount: b.amount });
         }
       }
     }
     if (allDebts) {
       for (const d of allDebts) {
         if (d.dueDay <= nextMonthEnd && d.amount > 0) {
-          windowObligations += d.amount;
+          obligationEvents.push({ absDay: daysInMonth + d.dueDay, amount: d.amount });
         }
       }
     }
   }
+  obligationEvents.sort((a, b) => a.absDay - b.absDay);
+
+  // Forward coverage: walk events chronologically. Credit incomes, debit obligations.
+  // The max drop below starting balance is what current balance must reserve;
+  // obligations covered by incoming income do not reserve against today's pool.
+  // Incomes process before obligations on the same day.
+  const events: { absDay: number; delta: number }[] = [
+    ...incomeEvents.map((e) => ({ absDay: e.absDay, delta: e.amount })),
+    ...obligationEvents.map((e) => ({ absDay: e.absDay, delta: -e.amount })),
+  ].sort((a, b) => a.absDay - b.absDay || b.delta - a.delta);
+
+  let runningLedger = balance;
+  let maxShortfall = 0;
+  for (const ev of events) {
+    runningLedger += ev.delta;
+    const shortfall = balance - runningLedger;
+    if (shortfall > maxShortfall) maxShortfall = shortfall;
+  }
+  const windowObligations = maxShortfall;
 
   // Proportional saving goal for the window
   const dailySaving = daysInMonth > 0 ? savingGoal / daysInMonth : 0;
   const windowSaving = Math.round(dailySaving * totalDays * 100) / 100;
 
-  // Pool = current balance + incoming income - obligations - savings
-  const pool = balance + windowIncome - windowObligations - windowSaving;
+  // Pool = current balance - obligations-net-of-coverage - savings
+  // Future income is NOT added to raise the pool; it only offsets obligations
+  // it arrives in time to cover. This keeps the daily rate sustainable.
+  const pool = balance - windowObligations - windowSaving;
   const dailyBudget = Math.max(0, Math.round((pool / totalDays) * 100) / 100);
 
-  console.info("[daily-budget] balance:", Math.round(balance), "windowIncome:", Math.round(windowIncome), "obligations:", Math.round(windowObligations), "saving:", Math.round(windowSaving), "pool:", Math.round(pool), "days:", totalDays, "daily:", dailyBudget);
+  console.info("[daily-budget] balance:", Math.round(balance), "reservedObligations:", Math.round(windowObligations), "saving:", Math.round(windowSaving), "pool:", Math.round(pool), "days:", totalDays, "daily:", dailyBudget);
 
   const tightestSegment = {
     startDay: today,
     endDay: endAbsDay,
     days: totalDays,
     balanceAtStart: Math.round(balance * 100) / 100,
-    incomeAtStart: Math.round(windowIncome * 100) / 100,
+    incomeAtStart: 0,
     obligations: Math.round(windowObligations * 100) / 100,
     savingGoalDeducted: windowSaving,
     pool: Math.round(pool * 100) / 100,