Practical use and limits
Use it for: Reuse the boundary matrix when changing a formula: reconcile one hand-checkable case, then test zero, complete, impossible, invalid, timing, fee, and exhausted-budget states before reviewing the rendered page.
Limits: The report verifies three formula modules at one repository commit. It does not validate future returns, personal targets, current vendor prices, tax treatment, every UI path, or the suitability of any financial or technical decision.
The question and the tested boundary#
This study asks whether three calculation engines on this site behave predictably when the comfortable assumptions disappear. The scope is the compound-interest engine, the emergency-fund engine, and the LLM API cost engine. They cover different decisions, but each converts a small set of inputs into a result that may look authoritative. The tests therefore target declared mathematical contracts: totals must reconcile, zero cases must remain finite, impossible goals must be identified, invalid rates must fail explicitly, and budget outputs must not become negative. The study does not claim that a correct formula can choose an investment, emergency reserve, or model provider for a reader.
How the regression harness works#
The repository loads the TypeScript calculation modules in a Node test process, calls their exported functions directly, and compares results with independently recorded expectations. Exact structural results use strict equality; currency-like values use a small numerical tolerance so floating-point representation does not create false failures. The commands run without a browser, network request, database, or vendor API. That makes the formula layer fast and repeatable, while deliberately leaving rendering, localization, accessibility, live prices, and production analytics to separate checks. A passing run is evidence about these named functions at this commit, not a universal certificate for every calculator page.
Reference case: reconcile value, contributions, and growth#
The compound-growth reference starts with 10,000, adds 1,000 at the end of every month, applies a 3% effective annual return, and runs for ten years. The expected final value is 152,887.16: 130,000 of starting money and contributions plus 22,887.16 of modeled growth. The engine must also return exactly ten year-end rows. This single case checks more than the headline total because the identity value equals contributed capital plus growth must remain true. It also documents the timing convention: each contribution enters after that period's growth, so a beginning-of-period calculator will legitimately produce a different result.
Zero return removes the formula's hiding place#
With a 1,000 starting balance, a 100 monthly contribution, zero return, and ten years, the only valid final value is 13,000. The inverse goal function must say that 100 per month is required to reach the same amount, and the time-to-goal function must return 120 months. These assertions are valuable because exponential formulas often divide by the periodic rate; at zero, that denominator disappears. The implementation uses a linear contribution count for this case. If the zero-return test fails, an attractive positive-return example can conceal a discontinuity exactly where a cautious planning scenario needs the clearest behavior.
Contribution frequency is a timing test, not free return#
The harness contributes the same 1,200 annual budget three ways for one year at a 3% effective annual rate: about 3.29 daily, 100 monthly, or 1,200 yearly. Because contributions are made at each period end, the results are 1,217.86, 1,216.41, and 1,200 respectively. Daily is slightly higher because more of the annual budget enters earlier; the yearly contribution arrives only at the final period and earns no growth inside that year. This does not mean changing a dropdown creates investment performance. It documents a cash-flow timing assumption that readers must keep constant when comparing scenarios.
Fee math must state its convention#
The fee test applies a 5% gross annual return and then a 0.5% annual fee as two multiplicative steps, producing a modeled net return of 4.475%, not a simple 4.5% subtraction. Other products may deduct charges at different times, add transaction costs, or calculate expenses from average assets, so this convention is not an invoice model. Its value is transparency: the projection can show exactly what it assumes. Investor.gov warns that recurring fees reduce both the invested balance and the return that balance could have earned. A regression test prevents a future interface change from silently ignoring the fee or applying it twice.
Goals need successful, complete, and impossible states#
A target function should distinguish three outcomes. If the starting balance already meets the target, the required period count is zero. If the balance is zero, the contribution is zero, and a positive return has nothing to grow, the target is unreachable within the model and the function returns no period rather than an invented date. For a reachable 200,000 target from 10,000 over ten years at 3%, the harness solves the required monthly contribution, feeds that answer back into the forward projection, and confirms that the reconstructed value reaches 200,000. This round trip catches mismatched timing or rate conventions between forward and inverse formulas.
Invalid rates should fail loudly#
An annual return of minus 100% or below makes the periodic root used by this model invalid and would imply that no value remains to compound. The engine rejects that input with a range error instead of returning NaN, Infinity, or a misleading chart. This is a contract decision rather than a claim that losses cannot exceed an initial position in every financial instrument. Calculator boundaries should match the product being modeled, and the interface should explain them. The reusable lesson is to identify the domain where a formula is meaningful, reject inputs outside it, and test the rejection path as carefully as the normal result.
Emergency reserves combine runway and uncovered exposure#
The emergency-fund engine separates a base reserve from a one-off exposure gap. With 8,000 of essential monthly spending, six months of runway, a 10,000 exposure, and 2,000 already dedicated to that exposure, it returns a 48,000 base, an 8,000 gap, and a 56,000 target. A second zero-yield case uses 3,000 of monthly essentials, six months, a 2,500 uncovered exposure, and 5,000 already saved. The resulting target is 20,500 and the remaining gap is 15,500. This structure follows the practical distinction between income interruption and identifiable unexpected costs without pretending that every possible emergency should be added at once.
Savings timelines need a no-progress result#
Saving 500 per month toward the remaining 15,500 with zero yield takes 31 months, while reaching it in 24 months requires 645.83 per month. The harness also verifies that a fully funded target takes zero months and that a positive gap with no contribution and no yield is unreachable. A negative 100% yield is rejected. These cases stop the interface from showing a false completion date when the balance cannot move. They also expose the difference between a target calculation and a forecast: job changes, withdrawals, interest, inflation, insurance, and real emergencies can alter the path even when the arithmetic is exact.
An LLM cost model must reconcile units and budget#
The API-cost fixture uses 2,000 input tokens, 500 output tokens, a 25% cached-input share, prices of 2, 0.5, and 8 per million tokens, 100 requests per day for 30 days, a fixed monthly cost of 10, and a budget of 100. The expected variable cost is 0.00725 per request, the monthly total is 31.75, modeled cache savings are 2.25, and the remaining budget supports 12,413 requests at that unit cost. A second case puts fixed cost above the entire budget while all token rates are zero; capacity must be zero, not infinite. The official Usage and Costs endpoints remain the reconciliation source after deployment.
What these passing tests do not prove#
The assertions do not establish that 3% is a future return, six months is the right reserve, a provider price will remain current, or a cache hit will occur. They do not cover taxes, exchange rates, irregular contributions, investment volatility, sequence risk, every vendor tool charge, or every browser and assistive technology. Several expected values were recorded from a review of the formulas, but a defect copied into both implementation and expectation could still survive. That is why the site also needs source review, worked examples, UI testing, bilingual rendered-page checks, production monitoring, and clear educational disclaimers. Formula regression is one layer in a larger evidence chain.
A reusable boundary matrix#
For any planning calculator, start with one hand-checkable reference case and reconcile every displayed component. Add a zero-rate or zero-price case, a target already achieved, a target that cannot progress, the lowest and highest permitted inputs, and one invalid input that must be rejected. Test inverse functions by feeding their answer back into the forward model. When frequency or timing changes, hold the annual cash budget constant. When costs exist, separate variable and fixed amounts and exhaust the budget deliberately. Finally, write down what the test cannot validate. This matrix makes future changes safer without turning a green test suite into financial, operational, or product advice.
Frequently asked questions
Why test formulas separately from the calculator page?
Direct function tests are faster and make a numerical failure easier to diagnose. The rendered page still needs separate checks for labels, localization, formatting, keyboard use, responsive layout, metadata, and whether inputs are connected to the correct function.
Does a passing compound-interest test make the projection realistic?
No. It shows that the code follows its stated rate, timing, fee, and contribution assumptions. Actual returns vary, inflation and taxes matter, and a smooth projection is not a market forecast.
Why include an LLM API calculator in a planning-calculator study?
It has the same trust problem: several units, rates, volumes, and fixed costs are compressed into one confident total. Boundary tests make the arithmetic contract visible, while provider usage and billing data remain necessary for reconciliation.