siddharthd
89300450a7
ci / lint-test (push) Successful in 50s
The 2026-07-26 document was a proposal marked "nothing built". Everything it described as broken is now fixed, and the fix is not the one it proposed, so leaving it in place would misdescribe the system to whoever reads it next. Records what the code now does: settled as the single balance gate, settled and trip_id as orthogonal axes, settling up by recording a payment rather than flipping a flag, and the reasons duplicates are superseded rather than deleted. Keeps the loan design intact and clearly marked as still a proposal -- it was never built and nothing in this work touched it. Also records that the proposal's own recommendation not to restate history from the CSVs was overturned, and why it was wrong: it measured the value in balances, where it is nil, and missed it in spend, where it is $35,259.
214 lines
10 KiB
Markdown
214 lines
10 KiB
Markdown
# Shared expenses and settlement
|
||
|
||
Status: **built and live**, as of 2026-07-28. The loan section at the end is
|
||
still a proposal — nothing there is built.
|
||
|
||
This replaces the 2026-07-26 proposal. That document described three problems
|
||
and proposed a `settlement_contexts` table to solve them. The problems were
|
||
real; the table was not built, and the reasoning for not building it is
|
||
recorded under [What was rejected](#what-was-rejected).
|
||
|
||
---
|
||
|
||
## The one rule
|
||
|
||
**Spend and owed are different questions asked of the same table, and the line
|
||
between them is `transaction_splits.settled`.**
|
||
|
||
| | Counts settled splits? | Why |
|
||
|---|---|---|
|
||
| **Spend** (`myShare`, `mySplitOf`) | **Yes** | Half a 2025 grocery shop was my expense whether or not the other half was ever repaid. |
|
||
| **Owed** (balances, trip figures) | **No** | A discharged obligation is not outstanding. |
|
||
|
||
Getting this backwards in either direction is the failure the model exists to
|
||
prevent. Filtering settled rows out of spend would re-inflate exactly the
|
||
figures that importing settled history exists to correct.
|
||
|
||
The predicate is `ACTIVE_OBLIGATION` in `src/lib/analytics-sql.ts`.
|
||
|
||
## Two orthogonal axes
|
||
|
||
`settled` and `trip_id` answer different questions and neither implies the
|
||
other:
|
||
|
||
- **`transaction_splits.settled`** — *is this obligation still live?*
|
||
- **`split_payments.trip_id`** — *which tab does this payment settle?*
|
||
NULL means the ongoing household tab.
|
||
|
||
A trip can be fully paid while the household tab runs a balance, and vice
|
||
versa. Before migration 0022 there was one global pool and this could not be
|
||
expressed, so every trip reported 100% unsettled forever — including trips paid
|
||
in full.
|
||
|
||
## How settling up actually works
|
||
|
||
**By recording a payment.** There is deliberately no "mark settled" action
|
||
anywhere in the app.
|
||
|
||
`settled` marks obligations discharged *outside* this app — the imported
|
||
SplitMyExpenses history, whose repayments happened on a platform we no longer
|
||
run and which therefore have no `split_payments` row here. A live obligation is
|
||
settled by recording the payment, and the balance nets to zero on its own.
|
||
|
||
Doing both would subtract the settlement twice: the splits leave the sum *and*
|
||
the payment is deducted, driving the balance negative by the amount repaid.
|
||
|
||
## What is built
|
||
|
||
| Piece | Where | Note |
|
||
|---|---|---|
|
||
| `settled` as the single balance gate | `ACTIVE_OBLIGATION` | Applied in both arms of the balances UNION and in the trip owed query |
|
||
| Payment scope | `split_payments.trip_id` (migration 0022) | Household payments do not settle a trip, and vice versa |
|
||
| Owner-scoped owed | `OWNER_SCOPE` in the trip owed query | Without it, a debt between the *other two* participants was reported as owed to the owner — $1,605.49 on Europe 2026 |
|
||
| Direction on screen | `/trips/[id]`, `/shared` | all square / owes you / ahead — you owe them |
|
||
| Historical splits | `scripts/split_csv_match.py` | 1,242 rows across 657 transactions, all `settled` |
|
||
| Duplicate suppression | `transactions.superseded_by_id` (migration 0023) | 31 rows, $42,040.68 |
|
||
| Overlap detection | `STATEMENT_OVERLAPS` → statements page | Red badge; catches the cause rather than the symptom |
|
||
|
||
## The historical import
|
||
|
||
The five SplitMyExpenses CSVs are the record of how expenses were shared before
|
||
this app existed. 676 of 1,536 shareable rows matched (44%), and 1,242 split
|
||
rows were written as `settled = true`.
|
||
|
||
**The deliverable is historical spend, not balances.** $35,259 left my spend —
|
||
$13,088 in 2024 and $22,117 in 2025 — because a $200 grocery shop that was
|
||
always half hers no longer reads as $200 of mine. Balances were byte-identical
|
||
before and after, which is the assertion that mattered.
|
||
|
||
Three things the matcher has to get right, each of which has bitten:
|
||
|
||
1. **Date format is decided per file.** The household export writes D/M/YYYY and
|
||
the four trip exports write ISO; 474 rows parse validly under both readings.
|
||
Guessing per row silently swaps January and February for some rows and not
|
||
others.
|
||
2. **A person's column is net balance impact, not their share.** The payer is
|
||
whoever is positive; the other's share is `|their negative| / cost`. So a
|
||
`+cost / -cost` row means the other party owes **100%** — not that the
|
||
expense was unshared, which is the reading that fakes an arrangement change.
|
||
3. **Matching is one-to-one, best pair first.** The NZ trip has two identical
|
||
$10.16 Uber rows against three ledger rows; without this a ledger row is
|
||
claimed repeatedly while the second CSV row looks matched and is not.
|
||
|
||
**The 44% is a coverage ceiling, not a matcher weakness.** The CSVs describe 678
|
||
shared expenses in 2024; the ledger holds 591 rows for all of 2024, 3 to 72 a
|
||
month, far less than a household actually spends. South Korea April 2024 matches
|
||
4 of 158. Chasing a higher rate is chasing transactions that were never
|
||
imported.
|
||
|
||
### A reversed recommendation
|
||
|
||
The 2026-07-26 proposal said, under *What I would not do*: "**Do not** restate
|
||
history from the SplitMyExpenses CSVs… the value is low: those balances are
|
||
settled and will not change."
|
||
|
||
That was overturned on 2026-07-28, and it was wrong in an instructive way: it
|
||
measured the value in *balances*, where it is indeed nil, and missed the value
|
||
in *spend*, where it is $35,259. Importing as `settled` gets the second without
|
||
touching the first. The "combining problem" it cited is real and is why the
|
||
match rate is capped — but a partial restatement of spend beats none, and rows
|
||
that cannot be matched simply keep their current treatment.
|
||
|
||
## What was rejected
|
||
|
||
**`settlement_contexts` as a table.** The need was real — a payment must say
|
||
what it settles. But trips already exist and already carry membership on
|
||
`transaction_overrides.trip_id`, so scope is a read of existing data rather
|
||
than a new grouping key. One nullable column on `split_payments` expressed it.
|
||
|
||
A general context table would have meant a new entity to create and maintain
|
||
before a payment could be recorded, in a two-person household with two trips.
|
||
|
||
**Deleting duplicate transactions.** Every child of `transactions` is
|
||
`ON DELETE CASCADE`, and which member of a duplicate pair holds the curation is
|
||
an accident of import order. Duplicates are superseded instead: the row stays,
|
||
keeps its children, and points at the row that replaces it.
|
||
|
||
**Reusing `reconciled_with_id` for duplicates.** Its predicate is scoped to
|
||
`statement_id IS NULL` on purpose — a statement line pointing at something else
|
||
is the survivor, not the duplicate. In the duplicate-import case both rows are
|
||
statement lines, so that predicate can never hide either.
|
||
|
||
## Scale note
|
||
|
||
This is a home app for one user, occasionally two, and the second user consumes
|
||
the splits view and little else. Reviews of this subsystem have repeatedly
|
||
proposed enterprise-grade reconciliation, lineage and audit machinery; the
|
||
*findings* are often right and the *sizing* is not. A one-column solution a
|
||
person can hold in their head beats a correct-but-unmaintainable one here.
|
||
|
||
---
|
||
|
||
## Still a proposal: the shared loan
|
||
|
||
**Nothing in this section is built.**
|
||
|
||
Sonu's contributions are in the ledger and unrecognised. All are categorised
|
||
`transfers` — correct for spend, but it makes a loan contribution and an expense
|
||
settlement indistinguishable:
|
||
|
||
| Pattern in offset credits | Rows | Total | Meaning |
|
||
|---|---:|---:|---|
|
||
| `…emi` | 39 | $37,980.24 | Sonu's loan contribution |
|
||
| `…mummy…` | 6 | $29,721.24 | Molina's money, forwarded by Sonu |
|
||
| other Meghalee | 15 | $71,130.27 | Sonu's own settlements |
|
||
|
||
### The loan is separate from shared expenses
|
||
|
||
Different obligations, different rhythms, different nature: one funds an asset,
|
||
the other funds consumption. They do not share a settlement scope, and a
|
||
contribution must never settle a dinner.
|
||
|
||
### The share is 50/50 fixed, with the shortfall tracked
|
||
|
||
Not derived from actual payments, which fluctuate. Over 2025-07-01 → 2026-06-30:
|
||
|
||
| | |
|
||
|---|---:|
|
||
| Repayments | $63,500.00 |
|
||
| Sonu's 50% obligation | $31,750.00 |
|
||
| Actually contributed (26 payments) | $27,750.00 |
|
||
| **Shortfall** | **$4,000.00** |
|
||
|
||
She never missed a fortnight; the rate changed — $1,250 × 15 (Aug 2025–Feb
|
||
2026, the correct 50%), $1,000 × 3 (Jul 2025, pre-adjustment), $750 × 8
|
||
(Mar–Jun 2026, leave).
|
||
|
||
So the model needs a **contribution schedule** (expected per period) alongside
|
||
actual contributions, with the running difference as a tracked receivable. A
|
||
flat percentage-of-actual cannot express "obligation unchanged, payment
|
||
temporarily reduced, difference owed" — it would silently redefine her share as
|
||
30% and make the shortfall disappear.
|
||
|
||
### Interest: recommended as expense, pending final call
|
||
|
||
Over 12 months $63,500 of cash left and debt fell by $44,127.36. The $16,523.64
|
||
difference bought nothing and is not recoverable — an expense by definition.
|
||
Excluding it leaves the balance sheet unable to reconcile cash out against
|
||
equity gained, and understates annual cost by ~10%.
|
||
|
||
The legitimate concern is that interest is non-discretionary. The answer is a
|
||
fixed-commitments grouping alongside rent, insurance and utilities — a
|
||
presentation change, not an exclusion.
|
||
|
||
**Do not** model the loan as a recurring split: that would put $2,500 a
|
||
fortnight of principal into spend, the error migration 0014 exists to prevent.
|
||
|
||
## Open questions
|
||
|
||
1. **Does equity need tracking per person?** If Sonu accrues a share of the
|
||
principal, that is a balance-sheet item the app has no concept of. Probably
|
||
belongs in a net-worth view rather than here.
|
||
2. **Attribution of forwarded payments.** `mummy` in the description reliably
|
||
marks Molina's money in all six known cases, but it is a description match on
|
||
a free-text field. Acceptable as a *suggestion* requiring confirmation, not
|
||
as an automatic rule.
|
||
3. **Untracked travel, Apr–May 2026.** France ($7,020.99, 68 rows) and Singapore
|
||
($2,242.05, 40 rows) between 13 April and 9 May 2026 belong to no trip. The
|
||
France rows begin the day after Europe 2026's end date, so this is either an
|
||
extension of that trip or one or two new ones.
|
||
4. **Two unattributable Sonu payments.** #3 ($3,779.33, 12 Apr) and #8
|
||
($4,794.06, 16 May) are narrated only as "transfer". Both currently sit on
|
||
the household tab; scoping them elsewhere moves money between tabs without
|
||
changing her overall balance.
|