Typical Spending Forecast — Math Spec

What this number represents

SafeToSpend’s Runway line tells you how much cash is available today after settling all committed liabilities (known bills, CC balances) and adding expected income up to your next payday. Runway answers: "if nothing non-recurring happens, where do I land?"

Real life isn’t that clean. Users swipe cards at restaurants, hit Target, grab Ubers. Those outflows don’t show up in Runway because they aren’t recurring bills. The Typical Spending Forecast projects that unplanned spending from the user’s actual history — checking/debit accounts only since v5.4 — so the accordion can show “you’d likely have $X left by {date}” as a realistic projection.

Which transactions feed the forecast?

Only transactions that match all of these rules in the last up to 365 days (adaptive: min(365, daysOfHistoryAvailable); returns null below 60 days):

• user_id = current_user
• transaction_type = 'debit' (outflow from the account)
• recurring_stream_id IS NULL — not part of a detected recurring stream (so Netflix, rent, Amazon Prime are excluded; that stuff is already in the Runway’s “Bills before payday” line)
• is_pending = false (cleared only)
• bank_accounts.account_type = 'depository' AND account_subtype = 'checking' (v5.4) — checking/debit only, like essentials and the runway itself. Credit cards are out (the ccDue ladder carries them); savings/prepaid/PayPal subtypes are out (set-aside, never draw on the runway); loans are out
• plaid_category_detailed NOT LIKE any ESSENTIALS_PFC_PREFIXES prefix (v5.4, NULL categories kept) — necessities belong to the essentials term; counting them here double-subtracts
• Not already superseded by a posted version (via excludeSupersededPending)
• categories.parent_code NOT IN ('INCOME','TRANSFER_IN','TRANSFER_OUT','LOAN_PAYMENTS','BANK_FEES') — these are never discretionary spending
• Not the CC-account side of a CC bill payment (via excludeCreditCardSideOfCcPayment)

The algorithm, step-by-step

Why robust mean and not median?

Previous iteration used median per weekday. It breaks on sparse-data users: if Monday has 14 samples with 10 zeros and 4 non-zero spend days, the median is zero. The forecast collapses to zero. Wrong — the user does sometimes spend on Mondays.

Plain mean is too fragile the other way: one $4,210 Thursday pulls the Thursday average up by $4,210 / n. A single Costco run warps the whole forecast.

Robust mean with p90 cap gets both: zero-heavy weekdays still produce non-zero estimates (because the non-zeros count at full weight), and outliers get pulled down to the 90th-percentile value. Simple enough to explain, strong enough to survive real user data.

Known limitation: day-of-week seasonality only. Month-of-year patterns (December holiday spike, summer travel) need multi-year data to denoise. We have at most 1 year. When we have 3+, we’ll layer month-of-year as a second signal.

Worked example — user 53, April 23 2026

Lookback: 101 days (oldest transaction is 2026-01-13; today is 2026-04-23; capped at 365).
Sample size after filters: 160 non-recurring discretionary transactions.
Observed days (days with any qualifying spend): 67 of 101 ≈ 66%.

Step A: daily spend (top recent days shown)

From the filtered query, grouping by date:

Step B: walk all 101 days, bucket by weekday

Every day in the 101-day lookback is pushed into exactly one weekday bucket with its spend (zero if no qualifying transactions). Example — all 15 Thursdays in the window:

Step C: compute the robust mean for Thursday

Sort the 15 samples ascending:

[0, 0, 0, 0, 7.25, 11.95, 15, 17.04, 37.31, 69.38, 166, 357, 957.12, 4180.56, 4210]

90th-percentile index: floor(15 × 0.9) = floor(13.5) = 13. sorted[13] = 4180.56. That’s the cap.

Apply the cap (replace values above $4,180.56): the single $4,210 outlier gets pulled down to $4,180.56. Everything else unchanged.

capped = [0, 0, 0, 0, 7.25, 11.95, 15, 17.04, 37.31, 69.38, 166, 357, 957.12, 4180.56, 4180.56]

Mean: sum(capped) / 15 = 9999.17 / 15 = $666.61. That’s the Thursday number you see on the Typical Spending card.

Step D: all seven weekday averages

Step E: per-tab window forecasts

For each SafeToSpend tab, walk today through the tab’s windowEnd inclusive, sum perDayOfWeek[weekday] for every day walked. Today is Thursday April 23, 2026.

Why Until Payday > This Month. Until Payday’s 9-day window stretches past end-of-month into May 1 (Friday — your next payday). Friday is a heavy-spend weekday ($461.49). That single extra Friday explains why Until Payday is $461.49 more than This Month, even though both end within 24 hours of each other.

Projection-at-{windowEnd} math

The number users see as "You’d likely have $X left at payday (May 1)" is:

projection = runway − typicalDiscretionary.windows[selectedTab].forecastAmount

For user 53 today:

Runway stays constant across tabs — it’s a snapshot of the moment. What changes is how much typical spending gets subtracted, because each tab projects over a different length of time.

What’s excluded and why

Why is user 53’s Thursday so high? — the BILT story

$666 felt high. Here’s why: your monthly rent ($4,200/mo on Bilt Rewards card) is misclassified as discretionary because the recurrence detector hasn’t caught it yet. Bilt has only fired twice in your 102-day lookback (Mar 12, Apr 2 — about 21 days apart, not exactly biweekly or monthly), so the detector hasn’t built a stream for it. With recurring_stream_id IS NULL on those transactions, they fall into typical-discretionary’s sample.

The two big Thursdays

Even with the p90 cap, both contribute heavily: cap = sorted[13] = $4,180.56, so Apr 2’s $4,210 gets clamped to $4,180.56 but Mar 12’s $4,170.55 is below the cap and contributes its full value.

What it would look like if BILT were detected as a stream

If BILT were classified as a recurring bill:

• $4,200 would be subtracted from runway as Upcoming Bills before payday (correct — it IS a known committed expense)
• BILT’s past occurrences would have recurring_stream_id != NULL and would be EXCLUDED from typical-discretionary's sample
• Thursday's robust mean would drop from $666.61 to roughly $15-50 — reflecting actual non-recurring Thursday spending

The fix — "Confirm a recurring bill" UX (planned)

Mirror of the existing “Confirm your paycheck” pattern. User taps a transaction in their history → it gets user_confirmed=true on a recurring_streams row → bypasses the detector's occurrence-count threshold. Same plumbing exists; just needs UI and the bill-side flag. Documented as planned post-MVP feature.

What this means for everyone, not just you

Any user with thin Plaid history (less than ~3 months), irregular-cadence bills (quarterly insurance, semiannual property tax), or just-started bills (new gym, first month of rent on a new card) will see the same misclassification. The typical-discretionary bucket over-counts in those cases, projection-at-payday under-counts what they’ll have left. Resolved by Confirm-a-recurring-bill once we ship it.

Code references

• apps/backend/app/services/typical_discretionary_service.ts — the whole algorithm. computeTypicalDiscretionary() is the entry point.
• apps/backend/app/services/transaction_filters.ts — the NON_DISCRETIONARY_PRIMARIES constant, excludeNonDiscretionary(), excludeCreditCardSideOfCcPayment(), excludeSupersededPending() helpers. Note: excludeCreditCardSideOfCcPayment is defense-in-depth in this query — the CC-account side of CC bill payments is already filtered out by transaction_type = 'debit' (it's a credit on the CC), and the checking-account side is filtered out by the LOAN_PAYMENTS parent-code exclusion. The explicit filter is redundant but cheap; it protects against future regressions if filter 1 or 3 ever loosens.
• apps/backend/app/services/recurrence_detection_service.ts — writes transactions.recurring_stream_id on the detector’s upsert pass. That’s the FK the service uses to exclude recurring spend.
• apps/backend/app/services/safe_to_spend_service.ts — calls computeTypicalDiscretionary, attaches result to the API response.
• apps/mobile/src/components/dashboard/SafeToSpend.tsx — renders the Projection block with the per-day cards.

Single caller, single source of truth. Both the Home dashboard and the AI Coach’s calculate_safe_to_spend tool read the same numbers from the same service. If a user asks the Coach “what would I typically spend by payday?” the answer comes from exactly this math, not a second implementation.