emergency-fund — evidence pack

Model: emergency-fund — v1.0.0 (as-implemented)

Engine: calcEmergencyFund(inputs: EmergencyFundInputs) in src/lib/engine.ts. Months to reach a target of N months of expenses in a high-yield savings account, with a month-by-month balance projection.

Inputs

Name	Type	Unit	Domain
monthlyExpenses	number	USD/mo	500–20,000
targetMonths	integer	months of coverage	1–12
currentSavings	number	USD	0–100,000
monthlySavings	number	USD/mo	50–5,000
savingsAccountRate	number	decimal/yr (0.048 = 4.8% APY)	0.01–0.08

Computation

Let r_m = savingsAccountRate / 12 (nominal monthly convention), MAX = 240.

1. targetAmount = monthlyExpenses × targetMonths.
2. Simulation, months m = 0..240 inclusive (241 iterations), balance starting at currentSavings, monthsToGoal initialized to the sentinel 240. Each iteration, in this exact order:
   1. record projectedBalance[m] = {month: m, balance, target: targetAmount} (target repeated in every element);
   2. record coverageByMonth[m] = {month: m, monthsCovered: monthlyExpenses > 0 ? balance / monthlyExpenses : 0};
   3. if balance ≥ targetAmount and monthsToGoal === 240, set monthsToGoal = m (first-hit latch; the balance recorded is the pre-update balance, so month 0 tests currentSavings itself);
   4. update balance = balance × (1 + r_m) + monthlySavings.
3. finalBalance = projectedBalance[monthsToGoal].balance. (The code writes ?? targetAmount as a fallback, but the array always has indices 0–240 and monthsToGoal ≤ 240, so the fallback is dead.)
4. interestEarned = max(0, finalBalance − currentSavings − monthlySavings × monthsToGoal).
5. yearsToGoal = monthsToGoal / 12 (float, no rounding).
6. The returned projectedBalance and coverageByMonth are the first min(monthsToGoal + 1, 61) elements of the recorded arrays — i.e. truncated at month 60 even when the goal is reached later (or never).

No Math.round anywhere; no wall-clock dependence.

Output keys

targetAmount, monthsToGoal, yearsToGoal, interestEarned, projectedBalance (fields {month, balance, target}), coverageByMonth (fields {month, monthsCovered}). finalBalance is an intermediate, not an output.

Assumptions & exclusions (part of the contract)

• Deposits land end-of-month, after interest; the goal check sees the start-of-month balance, so a deposit that crosses the target counts in the following month.
• No inflation on the expense target; the target is fixed at t = 0.
• If currentSavings ≥ targetAmount, monthsToGoal = 0 and interestEarned = 0.

Known model issues (v1.0.0)

• Sentinel collision: monthsToGoal = 240 means *either* "goal first reached at exactly month 240" *or* "never reached within 240 months" — the two are indistinguishable. The UI treats ≥ 240 as "Never". Correspondingly yearsToGoal = 20 is the never-sentinel in years.
• When the goal is never reached, interestEarned is still computed — over the full 240-month window, not "to goal" as the name implies.
• Chart arrays are hard-truncated at 61 elements (months 0–60): for slow savers the plotted series ends well short of the goal/sentinel.
• target is duplicated into every projectedBalance element.
• The monthlyExpenses > 0 guard on coverage returns 0 (not Infinity/NaN) at zero expenses; note targetAmount is then also 0, so the goal is met at month 0. Out of domain, but defined behavior.

Verification

Vectors: oracle/vectors/emergency-fund.json (seeded fuzz + boundary cases). Tolerance: rel 1e-9 / abs 1e-6 per numeric field; projectedBalance and coverageByMonth element-wise.

Suggested curated edges:

• Already funded: {monthlyExpenses: 500, targetMonths: 1, currentSavings: 100000, monthlySavings: 50, savingsAccountRate: 0.01} → monthsToGoal = 0, single-element arrays, interestEarned = 0.
• Never-sentinel: {monthlyExpenses: 20000, targetMonths: 12, currentSavings: 0, monthlySavings: 50, savingsAccountRate: 0.01} → monthsToGoal = 240, arrays truncated at 61 elements.
• Truncation straddle: inputs tuned so the goal lands between months 61 and 239 (e.g. {monthlyExpenses: 4500, targetMonths: 6, currentSavings: 0, monthlySavings: 300, savingsAccountRate: 0.04}) — exercises monthsToGoal > 60 with 61-element arrays.