Skip to content

v1.16.10: Fix starting balance ignored by "All time", the AI summary, Buckets and Forecast - #33

Open
gitluis wants to merge 3 commits into
fix-drawer-flag-overridesfrom
fix-all-time-start-balance
Open

gitluis wants to merge 3 commits into
fix-drawer-flag-overridesfrom
fix-all-time-start-balance

Conversation

@gitluis

@gitluis gitluis commented Nov 2, 2026 •

Copy link
Copy Markdown
Owner

Stacked on #32 (fix-drawer-flag-overrides), in a chain of fixes on top of the Clarity redesign (#16 → #17 → #19 → #20 → #21). Merge in order: #16, #17, #19, #20, #21, then the fixes #24–#38 and #39–#50 in order, then #10, then #23. #18 is a separate patch on master (already merged).
This fix doesn't use any earlier fix's code; it is stacked only so versions and the CHANGELOG merge cleanly.

Summary

A bank account's starting balance (Settings → Accounts) now counts in every date range, All time included, wherever a balance is shown.

Before, All time on the Overview left it out, so net worth and the account cards changed with the range. The AI summary, Savings buckets and Forecast left it out in every range. One function was missing it: currentBalances().

Cause

  • currentBalances() (aggregation.js) works in three steps: a balance override, then a running balance from the CSV (never present), then the sum of the account's transactions. The last step never added manualBalances[id+'_initial'].
  • periodEndBalance() returns currentBalances() for All time. For every other range it adds the starting balance to the transactions up to the range end itself.
  • balanceAt() (net worth chart, account sparklines, Trends) also adds the starting balance.
  • So on All time, the net worth disagreed with its own chart. With the samples and starting balances of $1,000 (checking) and $250.50 (savings), All time showed $15,499.81 and its chart ended at $16,750.31. Last 6 months showed $16,750.31.
  • The cause is broader than All time. buildFinancialSummary(), Savings buckets ("Unassigned savings") and Forecast → Savings (starting checking and savings) call currentBalances() directly, so they left the starting balance out in every range.
  • Why it shows up now: the All-time shortcut is old, but before v1.16.0 no input wrote _initial. v1.16.0 made the starting balance the field you fill in for a bank account.

Trends was reported as not affected, and it wasn't: it uses balanceAt(). It disagreed with the Overview's All time only because the Overview was wrong.

What changed

  • currentBalances() adds the starting balance in its last step. This is the fix.
  • startingBalance(accountId) (new, aggregation.js) reads manualBalances[id+'_initial'], or 0 when unset. periodEndBalance() and balanceAt() call it instead of their own copies of the same expression. What they return doesn't change.
  • periodEndBalance(): besides the helper, only its All-time comment changed.
  • Overrides keep their meaning. manualBalances[id] still wins wherever it did: a card's amount owed, and a bank "current balance" saved before v1.16.0. Settings → Accounts shows that one with a button to drop it. With an override, the starting balance is ignored, as before, in all three helpers. The 7-day rule in periodEndBalance() is unchanged: a range ending within 7 days of today shows the override as it is.
  • Cards: a card's override wins as before. A card with an _initial now counts it on All time too, as the other ranges, the chart and Trends already did. I chose one rule for every account kind over a card exception. Settings can't set a card's _initial since v1.16.0; it can only come from older data or a JSON import.
  • Docs and version (v1.16.10): CHANGELOG, the index.html footer, README (badge and footer), Settings → General, CLAUDE.md §1 and "Last updated". CLAUDE.md §8 (startingBalance(), currentBalances()), §13 (summary balances) and §18 (the one balance rule).

Where it shows, with a starting balance set:

Screen Before After
Overview, All time: net worth, account cards, the savings card's "assigned to buckets" note left out included
Overview, every other range; net worth chart; sparklines; Trends included unchanged
AI summary: Accounts and Total Cash lines, every range left out included
Savings buckets "Unassigned savings"; Forecast → Savings starting amounts left out included
Transactions → Payments "Card balance now"; Credit cards; linked debts card override or sum unchanged, unless a card has an _initial

AI summary and the eval (§13, §21):

  • No manual balances: the summary is byte-identical before and after, in every range (checked). The AI tab's requests are byte-identical to v1.15.0's (test-insights.js).
  • The eval: its sandbox sets manualBalances: {} and All time. Its summary is byte-identical before and after, and the same whatever balances you have set. The published docs/EVAL.md results still hold, so I didn't re-run it.
  • With a starting balance, only lines 2–3 change. Samples, All time, $1,000 checking and $250.50 savings:
 Period: All time (transactions from May 1, 2026 to Oct 20, 2026: 173 days, about 5.7 months)
-Accounts: Bank Checking ($13,321.43), Bank Credit Card (credit_card_sample) (-$617.33), Bank Savings ($2,795.71)
-Total Cash: $16,117.14, Total Debt: $617.33, Net Worth: $15,499.81
+Accounts: Bank Checking ($14,321.43), Bank Credit Card (credit_card_sample) (-$617.33), Bank Savings ($3,046.21)
+Total Cash: $17,367.64, Total Debt: $617.33, Net Worth: $16,750.31

This is the correctness fix: Claude now gets the balances the Overview shows. Before, it was told $15,499.81 for someone who had entered a $1,000 starting balance on checking.

Left as is (found while checking, not part of this fix):

  • The 7-day override rule in periodEndBalance() has no match in balanceAt(). With an override, a range that ends within the last 7 days, and transactions between that end and today, the net worth and the chart's last point can differ. The samples can't show it, because their data ends on Oct 20.
  • The AI summary reports today's balances in every range, under the range's "Period" line. That was already so. The task was not to change anything else in the summary. (v1.16.11: Fix the AI summary sending today's balances for a past date range #34, stacked on this one, fixes it.)
  • The running-balance branch (t.balance) ignores the starting balance, and balanceAt() ignores running balances. It's dormant: no format fills t.balance.

Not verified

  • No manual testing in a real browser; only headless Chromium. Not tested in Safari or Firefox.
  • No real bank data, and no real finlens-state.json or JSON import carrying an _initial on a card.
  • The AI eval was not re-run against the API. Its input is byte-identical, so it shouldn't need one.
  • Dates: range ends come from today's date (2026-11-02). The sample data ends Oct 20, so This week, Past 7 days and This month hold no transactions. The 7-day override rule was never tested with transactions between a range end and today.
  • Chaining: done. This was built on v1.16.0 as v1.16.10; in the stack it is v1.16.10, on top of v1.16.9: Fix the edit drawer freezing a transaction's flags when you only change its category #32. Only the version strings, the CHANGELOG top and CLAUDE.md §1 / "Last updated" conflicted. The code merged as written.
Automated checks: earlier run, not re-run · b79d82a

Moved unchanged from this PR's "Test results" comment on 2026-11-04; not re-run, so not in the new table format. Originally a description section titled "How it was tested".

Headless Chromium (Playwright) at 1280×900 against samples/ (257 transactions), with the pinned CDN libraries served from npm, on this branch's final commit b79d82a, chained on #32. Each script ran as NODE_PATH=$(npm root -g) node <script> <repo> <outdir>, from one harness shared by every branch in the stack: the base suites, plus every test added by this PR or by a PR below it (cumulative regression).

Script Result on b79d82a
test-clarity.js 55/55
test-insights.js 137/137
test-finances.js 126/126
test-plan.js 127/127
boot.js 257 transactions, 24 views, 0 errors
race.js 8 errors, all renderImportLog (the race #18 fixes on master; not in this stack)
test-clear-edits.js (from #24) 47/47
test-rebuild-folder.js (from #25) 57/57
test-partial-import.js (from #26) 47/47
test-json-import.js (from #27) 28/28
test-new-browser-copy.js (from #28) 10/10
test-json-export.js (from #29) 31/31
test-plan-links.js (from #30) 60/60
test-rule-flags.js (from #31, as updated by #32) 67/67
test-drawer-flags.js (from #32) 36/36
test-start-balance.js (new in this PR) 193/193

Measured before the chain

By the agent that wrote the fix, on 6231659 (built on ddc8a5f, v1.16.0; then numbered v1.16.3). Its start-balance baseline was captured on ddc8a5f; the same baseline is used on this branch's commit.

Headless Chromium (Playwright) against samples/, with the CDN libraries served from npm by the harness. Every script was run on the final commit with NODE_PATH=$(npm root -g) node <script> <repo> <outdir>.

Script Result
test-clarity.js 55/55
test-finances.js 126/126
test-plan.js 127/127
test-insights.js 137/137 (one check edited for the version, below)
test-start-balance.js (new) 193/193
boot.js 0 errors, every view in light and dark
race.js 8 errors, all renderImportLog / importLogsBody (fixed by #18). The base gave 6 of the same. None come from this change.

test-start-balance.js:

  • Expectations are computed in the test. It parses the three sample CSVs in Node and works out each balance from the rows, in cents, not with the app's helpers.

  • The starting balance is entered the way a user does: in Settings → Accounts, by typing it and leaving the field. The test checks it saves as <id>_initial.

  • 7 scenarios:

    • no manual balances;
    • a card override;
    • an old bank override plus a card override;
    • a starting balance on checking and savings;
    • starting balances plus a card override;
    • a checking override and a checking starting balance (the override wins), plus a savings starting balance;
    • a card starting balance.
  • 11 ranges: every preset (This week through Last year, and All time), a custom range (Jul 1 – Aug 15, 2026) and a custom range with no end.

  • For each scenario and range:

    • the Overview's net worth, each account card and its footnote;
    • every point of the 1M, 3M and All net worth chart, and that the chart ends at the net worth shown.
  • For each scenario:

    • the AI summary's Accounts and Total Cash lines in every range;
    • Trends' balance rows, and that they equal the Overview's All-time cards;
    • Buckets' unassigned savings, Forecast's starting amounts and the Payments card balance.
  • Against the code before the fix: the baseline was captured on the base commit (ddc8a5f) with --capture.

    • With no manual balances, a card override, or an old bank override, every screen in every range and the AI summary are byte-identical.
    • With a starting balance, only these differ: All time's net worth and account cards, summary lines 2–3, and Buckets / Forecast / Payments. The All-time chart itself is unchanged.
  • The eval: the summary from AIEval.loadSamples() is byte-identical to the base, and the same whatever balances are set.

  • Reproducing the bug: on the base, the same test gives 169/193. All 24 failures are in the four starting-balance scenarios:

    • All time's Overview and its chart;
    • the AI summary;
    • Trends against the Overview;
    • Buckets and Forecast;
    • "compared with before the fix", which can't pass on the base.

    Every other range passes on the base.

Existing suite edited: in test-insights.js, the "General: version line" check expected FinLens v1.16.0. It now expects v1.16.10 because of the version bump. Nothing else changed in any existing suite.

How to reproduce the bug

Run this on the base branch, fix-drawer-flag-overrides (#32).

  1. Do the Setup from the testing steps below, but check out fix-drawer-flag-overrides instead of fix-all-time-start-balance. You end with the samples loaded and starting balances of 1000 on Bank Checking and 250.50 on Bank Savings.
  2. Open the date range button (calendar icon, top bar) and choose All time.
  3. Go to Overview. Read the Net worth figure.
  4. On the chart, click All and hover the last point.
  5. Read the Bank Checking and Bank Savings account cards.
  6. Choose Last 6 months and read Net worth again.

What goes wrong:

  • On All time, Net worth reads $15,499.81, but the chart's last point is $16,750.31. Last 6 months also shows $16,750.31.
  • The account cards read $13,321.43 and $2,795.71: the $1,000 and $250.50 starting balances are left out.
  • Optional: buildFinancialSummary() in the Console says Bank Checking ($13,321.43) … Net Worth: $15,499.81 in every range.
Manual QA steps

Setup

  1. git checkout fix-all-time-start-balance, then open index.html in Edge.
  2. If FinLens already has data in this browser, go to Settings → Data & reset → Start over, type RESET and click Erase and start over. (This PR doesn't change saving, so no scratch folder is needed.)
  3. On the welcome screen, click the choose the files link and select the three CSVs in samples/.
  4. Go to Settings → Accounts. In Bank Checking's Starting balance field type 1000, press Tab. In Bank Savings's field type 250.50, press Tab. Each shows a "Saved the starting balance…" message.

The numbers below assume the unedited samples and these two starting balances.

1. Overview net worth on All time includes the starting balance (the main fix)

  1. Open the date range button (calendar icon, top bar) and choose All time.
  2. Go to Overview. Read the Net worth figure.
  3. On the chart, click All and hover the last point.
  4. Read the Bank Checking and Bank Savings account cards.

Expected:

  • Net worth is $16,750.31, the same as the chart's last point.
  • Bank Checking shows $14,321.43, Bank Savings $3,046.21. Bank Checking's footer says Starting balance plus imported transactions.

Before this fix: All time showed $15,499.81 while the chart ended at $16,750.31; the cards were $13,321.43 and $2,795.71.

2. Same figure in other ranges (regression)

  1. Choose Last 6 months, then Year to date, from the date range button. Read Net worth each time.
  2. With All time set, go to Trends and read the Bank Checking and Bank Savings rows in the account balances section.

Expected:

  • Net worth is $16,750.31 in both ranges (unchanged from before the fix).
  • Trends shows $14,321.43 and $3,046.21, matching the Overview cards (Trends was already right; it should not change).

3. AI summary carries the starting balance

  1. Set the range to All time.
  2. Press F12 → Console. Type buildFinancialSummary() and press Enter.
  3. Read lines 2 and 3 of the output.
  4. Set the range to Last 3 months and run it again.

Expected:

Before this fix: Bank Checking ($13,321.43) … Net Worth: $15,499.81, in every range.

4. Savings buckets and Forecast

  1. Go to Plan → Buckets. Click + New bucket, name it Trip, set Saved so far ($) to 0, click Create bucket.
  2. Read the Unassigned savings tile.
  3. Go to Plan → Forecast, Savings tab, and click Reset (so the inputs come from your current balances).
  4. Read the Checking ($) and Savings ($) inputs.

Expected:

  • Unassigned savings is $3,046.21; its line below reads Bank Savings · $3,046.21.
  • Forecast shows Checking 14321 and Savings 3046.

Before this fix: $2,795.71, and Forecast started from 13321 and 2796.

5. No starting balance: nothing changes

  1. In Settings → Accounts, clear both starting balance fields (delete the text, press Tab).
  2. Set All time and check Overview → Net worth.
  3. Run buildFinancialSummary() in the Console.

Expected:

  • Net worth is $15,499.81, the same as on the base branch.
  • The summary shows Bank Checking ($13,321.43) and Net Worth: $15,499.81.

6. Credit card balance owed still wins (regression)

  1. In Settings → Accounts, set Bank Credit Card's Balance owed today ($) to 500.
  2. Set All time, go to Overview and read the credit card's account card.
  3. Go to Transactions, click the Payments pill, and read Card balance now.

Expected:

  • The card shows $500.00 owed and footer Balance entered in Settings → Accounts, in All time and in Last 6 months.
  • Card balance now shows $500.00.

7. Survives a reload

  1. Put the 1000 / 250.50 starting balances back and remove the card's 500.
  2. Press F5. Set All time.

Expected:

  • Net worth is $16,750.31 again.
  • The footer and Settings → General show v1.16.10.

Please check before merging

  • With a starting balance set in Settings → Accounts, the Overview shows the same net worth on All time as on Last 6 months, and the number above the chart matches the chart's last point.
  • You're fine with the AI summary's balances changing when a starting balance is set (lines 2–3 only). With none set it's unchanged, so there's no eval re-run.
  • Buckets' "Unassigned savings" and Forecast's starting checking and savings now include the starting balance. That's what you want.
  • A card with an _initial (old data or a JSON import only) now counts it on All time too. Is it OK to treat cards like every other account here?
  • An old bank "current balance" override still replaces the starting balance, as Settings → Accounts says.
  • v1.16.10 everywhere: footer, README badge and footer, Settings → General, CHANGELOG, CLAUDE.md §1.
  • Manual QA passed in Edge/Chrome with a real folder

https://claude.ai/code/session_013Z8iBXzUjiQbYziDZ8CZft


Generated by Claude Code

…16.10)

currentBalances() added up an account's transactions but never its
starting balance (manualBalances[id+'_initial']). periodEndBalance() uses
it for All time, and the AI summary, Savings buckets and Forecast read it
directly, so all of them left the starting balance out. Every other
range, the net worth chart, the sparklines and Trends (balanceAt())
added it, so the Overview's numbers changed with the range.

- aggregation.js: currentBalances() adds the starting balance. A new
  startingBalance() reads it; periodEndBalance() and balanceAt() share it.
- A balance override (a card's amount owed, or a bank balance saved
  before v1.16.0) still wins and still replaces the starting balance.
- With no manual balances every number and the AI summary are
  unchanged. The AI Eval's sandbox sets none, so its summary is
  byte-identical and the published results still hold.
- CHANGELOG; version in index.html, README and Settings → General;
  CLAUDE.md §1, §8, §13, §18 and Last updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Z8iBXzUjiQbYziDZ8CZft
…time-start-balance

Carries master's v1.10.3-v1.10.5 up the stack: declined answers (#14),
literal single "~" (#15) and the Import Logs race fix (#18), with
clarity-insights' port of #14 to the rebuilt AI tab.

One conflict: CLAUDE.md's "Last updated" line. Kept this branch's
line and added the v1.10.3-v1.10.5 history. The CHANGELOG merged cleanly.
Versions stay 1.16.10. renderImportLog() keeps #18's guards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Z8iBXzUjiQbYziDZ8CZft
…o fix-all-time-start-balance

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Z8iBUZo6LRYpLthSp2PRi

# Conflicts:
#	js/views-settings.js
@gitluis gitluis changed the title v1.16.10: fix starting balance ignored by "All time", the AI summary, Buckets and Forecast v1.16.10: Fix starting balance ignored by "All time", the AI summary, Buckets and Forecast Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants