SimpleFIN Liability Balance Normalization#

SimpleFIN reports all liability balances (credit cards and loans) as negative from a banking-ledger perspective, regardless of whether the account reflects money owed or an overpayment credit. The app's internal convention is the inverse: positive = debt owed, negative = credit/overpayment. Bridging these two conventions requires type-specific logic in SimplefinAccount::Processor#process_account!.

Sign Convention#

The conversion was introduced in PR #410 and then progressively refined. Loans and credit cards are handled differently because their semantics differ — loans do not have a credit state analogous to a credit-card overpayment.

Loan Accounts#

Loans are short-circuited before any heuristic runs 1. The processor stores observed.abs directly. Rationale (from PR #1574):

• Banks report principal outstanding as a positive value; a paid-off loan has balance 0, never negative.
• Loans rarely have enough transaction history for the heuristic to fire. Without the short-circuit, the :unknown fallback path would negate the value and inflate net worth by 2 × principal.

Credit Card Accounts — OverpaymentAnalyzer#

For CreditCard accounts, SimplefinAccount::Liabilities::OverpaymentAnalyzer is invoked first 2. It returns a Result struct with one of three classifications:

How the Analyzer Works#

1. Transaction gathering 3: Pulls the last 120 days of Entry records for the linked account (app convention: charges > 0, payments < 0). Falls back to raw provider transactions, negating amounts to convert from banking convention.

2. Minimum evidence gate 4: Requires ≥ 10 transactions (min_txns). Returns :unknown if below threshold.

3. Statement boundary guard 5: If there is a very recent payment (within 5 days) with ≤ 2 total payments, returns :unknown to avoid false credit classification just after a statement payment posts before charges catch up.

4. Net-balance sanity check 6: If |computed_net − observed| exceeds 10% of the observed balance (minimum $5), returns :unknown — guards against incomplete transaction history (e.g., pending charges). Added in PR #642.

5. Classification 7: Uses epsilon = max($0.50, observed × 0.5%) to avoid misclassifying near-zero-difference accounts.

6. Sticky caching 8: Confirmed classifications are cached for 7 days (key: simplefin:sfa:<id>:liability_sign_hint) to prevent sign flapping between syncs.

Fallback — normalize_liability_balance#

When the analyzer returns :unknown or raises an error, normalize_liability_balance 9 applies sign-only logic:

• If both current_balance and available_balance are positive: store as -observed.abs (treat as debt, negate).
• If both are negative: store as +observed.abs.
• Otherwise: store as -observed (simple negation).

Configuration#

The overpayment heuristic is enabled by default. It can be toggled or tuned via Setting records (checked first) or environment variables 10:

Decision History#

Key Source Files#

• SimplefinAccount::Processor — orchestrates all balance normalization; liability sign logic in process_account! (lines 81–168)
• SimplefinAccount::Liabilities::OverpaymentAnalyzer — full heuristic implementation