Add splitwise module: equal/exact/percent/share split strategies with largest-remainder paise arithmetic, derived ledger, greedy and exact debt simplification, concurrency control (13 tests, 12 transcripts)

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017ic4b4aCTv6BYCer55YdjZ
This commit is contained in:
Claude
2026-11-17 23:16:53 +05:30
parent c57031aaeb
commit eef175d669
42 changed files with 1772 additions and 0 deletions
+28
View File
@@ -0,0 +1,28 @@
Four friends, five expenses, four split strategies
==================================================
Expenses (shares in paise-exact rupees)
#1 Hotel (equal) paid by asha Rs 12000.00 asha=Rs 3000.00 bala=Rs 3000.00 chitra=Rs 3000.00 dev=Rs 3000.00
#2 Dinner (equal, 3 people) paid by bala Rs 100.00 asha=Rs 33.34 bala=Rs 33.33 chitra=Rs 33.33
#3 Cab (exact) paid by chitra Rs 900.00 asha=Rs 300.00 bala=Rs 200.00 chitra=Rs 100.00 dev=Rs 300.00
#4 Scuba (percent) paid by dev Rs 4000.00 asha=Rs 1600.00 bala=Rs 400.00 chitra=Rs 400.00 dev=Rs 1600.00
#5 Groceries (shares 2:1:1) paid by asha Rs 1000.00 asha=Rs 500.00 bala=Rs 250.00 chitra=Rs 250.00
Net balance per person (positive = the group owes them)
asha Rs 7566.66
bala -Rs 3783.33
chitra -Rs 2883.33
dev -Rs 900.00
Detailed debts, netted pair by pair: 6 payments
bala pays asha Rs 3216.66
chitra pays asha Rs 2950.00
dev pays asha Rs 1400.00
bala pays chitra Rs 166.67
bala pays dev Rs 400.00
chitra pays dev Rs 100.00
Simplified debts (greedy): 3 payments
bala pays asha Rs 3783.33
chitra pays asha Rs 2883.33
dev pays asha Rs 900.00
+14
View File
@@ -0,0 +1,14 @@
Why paise in a long, and why largest remainder
==============================================
double: 0.1 + 0.2 = 0.30000000000000004
double: ten times 0.10 = 0.9999999999999999
long, plain division: 10000 paise / 3 = 3333 each; three of them make 9999 paise
one paisa has vanished: 1
largest remainder, Rs 100.00 in 3 equal parts: [3334, 3333, 3333] sum 10000
largest remainder, 10 paise in 3 equal parts: [4, 3, 3] sum 10
largest remainder, 33.33% / 33.33% / 33.34%: [3333, 3333, 3334] sum 10000
largest remainder, shares 2:1:1 of Rs 1000.00: [50000, 25000, 25000] sum 100000
largest remainder, Rs 100.00 in 7 equal parts: [1429, 1429, 1429, 1429, 1428, 1428, 1428] sum 10000
@@ -0,0 +1,7 @@
Seeded property check: 200000 random divisions
==============================================
trials: 200000
every trial: shares add up to the total exactly
every share: equal to the exact amount rounded down, or one paisa more
largest gap above the rounded-down amount: 1 paisa
+16
View File
@@ -0,0 +1,16 @@
Bad input is rejected before it touches the ledger
==================================================
exact amounts too small -> InvalidSplitException: exact amounts add up to Rs 90.00 but the expense is Rs 100.00
percentages add up to 99.99 -> InvalidSplitException: percentages add up to 99.99 but must add up to 100
percentage with 3 decimal places -> InvalidSplitException: percent for asha has more than 2 decimal places: 33.333
zero shares -> InvalidSplitException: shares for bala must be positive
same person listed twice -> InvalidSplitException: duplicate participant in [asha, asha]
nobody to split with -> InvalidSplitException: an equal split needs at least one participant
participant outside the group -> IllegalArgumentException: esha is not a member of group Goa trip
payer outside the group -> IllegalArgumentException: esha is not a member of group Goa trip
zero-rupee expense -> IllegalArgumentException: an expense must be positive, got Rs 0.00
paying yourself -> IllegalArgumentException: asha cannot pay themselves
amount with three decimals -> IllegalArgumentException: not a whole number of paise: 10.005
After eleven rejected requests: 5 expenses, balances unchanged = true
+16
View File
@@ -0,0 +1,16 @@
Simplifying debts: pairwise vs greedy vs exact
==============================================
Goa trip: 6 pairwise payments, 3 greedy, 3 exact
Balances (Rs): a +4, b +3, c +3, d -4, e -6
greedy: 4 payments
e pays a Rs 4.00
d pays b Rs 3.00
e pays c Rs 2.00
d pays c Rs 1.00
exact: 3 payments
e pays b Rs 3.00
e pays c Rs 3.00
d pays a Rs 4.00
why: {a, d} cancel exactly (+4 -4) and {b, c, e} cancel exactly (+3 +3 -6), so two separate groups need 1 + 2 = 3 payments
+9
View File
@@ -0,0 +1,9 @@
1500 seeded random zero-sum balance sets, up to 9 people
========================================================
cases: 1500
every case: both simplifiers leave every balance at exactly zero
every case: greedy uses at most (people with a balance) - 1 payments
every case: the exact simplifier's count equals an independent backtracking search
cases where greedy used more payments than exact: 448 of 1500
largest difference: 2 payment(s)
+7
View File
@@ -0,0 +1,7 @@
Exact search cost (timing dependent: figures differ from run to run)
====================================================================
people 10: exact 9 payments in about 4 ms, greedy 9 payments in about 32 microseconds
people 14: exact 12 payments in about 18 ms, greedy 13 payments in about 29 microseconds
people 18: exact 15 payments in about 46 ms, greedy 17 payments in about 141 microseconds
people 20: exact 17 payments in about 97 ms, greedy 18 payments in about 44 microseconds
+45
View File
@@ -0,0 +1,45 @@
Recording real payments against the ledger
==========================================
Before settling
asha Rs 7566.66
bala -Rs 3783.33
chitra -Rs 2883.33
dev -Rs 900.00
After bala pays asha Rs 3783.33
asha Rs 3783.33
bala Rs 0.00
chitra -Rs 2883.33
dev -Rs 900.00
pair view after paying the net amount (asha-bala flips direction, because bala paid more than he owed asha directly):
asha pays bala Rs 566.67
chitra pays asha Rs 2950.00
dev pays asha Rs 1400.00
bala pays chitra Rs 166.67
bala pays dev Rs 400.00
chitra pays dev Rs 100.00
After dev pays asha Rs 1000.00 (Rs 100.00 more than dev owes)
asha Rs 2783.33
bala Rs 0.00
chitra -Rs 2883.33
dev Rs 100.00
Now chitra and dev follow the simplified plan
chitra pays asha Rs 2783.33
chitra pays dev Rs 100.00
After the plan
asha Rs 0.00
bala Rs 0.00
chitra Rs 0.00
dev Rs 0.00
net balances all zero: true
pair view still lists 5 debts, because the plan paid net amounts, not the original pairs:
asha pays bala Rs 566.67
chitra pays asha Rs 166.67
dev pays asha Rs 400.00
bala pays chitra Rs 166.67
bala pays dev Rs 400.00
each person's pair debts add up to their net balance: true
+7
View File
@@ -0,0 +1,7 @@
The ledger is derived: replaying the log rebuilds it exactly
============================================================
expenses replayed: 5
settlements replayed: 1
net balances equal: true
pairwise debts equal: true
+7
View File
@@ -0,0 +1,7 @@
Eight threads adding expenses to one group
==========================================
expenses added: 40000 (expected 40000)
distinct expense ids: 40000, highest id: 40000
net balances add up to zero: true
replaying the log gives the same balances: true
@@ -0,0 +1,6 @@
Control: the same idea without a lock (timing dependent: the figure differs every run)
======================================================================================
expected total: 1600000
actual total: 740725
updates lost: 859275 (always zero or more, and usually well above zero)
+25
View File
@@ -0,0 +1,25 @@
Pitfalls that look fine until they are not
==========================================
1. new BigDecimal(33.33) = 33.3299999999999982946974341757595539093017578125
new BigDecimal("33.33") = 33.33
the split rejects the double-built value: percent for asha has more than 2 decimal places: 33.3299999999999982946974341757595539093017578125
2. 3000 dinners of Rs 100.00 between asha, bala and chitra
always the same order: asha Rs 100020.00, bala Rs 99990.00, chitra Rs 99990.00
rotating tie offset: asha Rs 100000.00, bala Rs 100000.00, chitra Rs 100000.00
3. asha pays Rs 600.00 for a gift but is not in the split
asha Rs 600.00
bala -Rs 300.00
chitra -Rs 300.00
4. default fraction digits: INR 2, JPY 0, KWD 3
5. an expense of Rs 0.01 split three ways
asha Rs 0.00
bala Rs 0.00
chitra Rs 0.00
debts: []
6. simplifying balances that do not add up to zero: balances do not add up to zero: the sum is Rs 0.01