CashFlow

Cancelling a closed loop preserves net balances and creates no new counterparties. That sounds harmless until someone cannot pay: cancelling the loop can leave less for a creditor outside it. I wanted the app to show both questions—how much debt can disappear, and who is worse off under the resulting payment failures—instead of treating maximum clearing as the only objective.

• Money must stay in integer minor units while the graph is reduced thousands of times.
• Cycle-only clearing must preserve every party's net position and never introduce a counterparty.
• Full path simplification has to disclose every relationship it creates.
• Large-network results should carry a certificate that can be checked without trusting or rerunning the solver.
• A plan that preserves net positions can still change recoveries when someone defaults.
• The search for fewer failures must report a bound, not imply that a heuristic always finds the optimum.
• Group roles govern expenses, exports, membership, and settlement actions.
• A calculated obligation is not proof that money moved between people.

1. 1

   Expense ledger

   The server stores group expenses, roles, audit events, and integer-minor-unit amounts in PostgreSQL.

2. 2

   Obligation graph

   Members are nodes and the actual who-owes-whom relationships are directed, capacity-limited edges.

3. 3

   Three cycle solvers

   Cycle cancelling, shortest-path routing, and network simplex solve the maximum-clearing problem. The large-network paths split work by strongly connected component.

4. 4

   Independent verifier

   Routing and simplex return a potential per party. A separate linear-pass verifier checks conservation, unchanged counterparties, and maximum cycle clearing without running a solver.

5. 5

   Path compensation

   The aggressive mode shortens open chains toward the net-position floor and records any new counterparty pairs it creates.

6. 6

   Default cascade

   An Eisenberg–Noe payment model with Rogers–Veraart recovery rates calculates actual collections and the waves of parties that become unable to pay.

7. 7

   Partial-clearing search

   The rescue search tries smaller cycle cancellations, resolves the whole payment network after each candidate, and compares failures with a max-flow-based unavoidable-failure bound.

8. 8

   Browser engine and graph

   The dependency-free clearing package and hand-built canvas renderer let a user switch modes without a server round trip.

9. 9

   Product boundary

   The surrounding app handles authorization, realtime updates, exports, receipt parsing, and the separate workflow for recording payments.

• Unit and integration coverage spans the clearing package, web app, and server, including the distinction between calculated plans and confirmed payments.
• Clearing tests check net-position conservation, integer inputs, no-new-counterparty guarantees, forbidden pairs, and the difference between cycle and path modes.
• Randomized network tests compare all three clearing solvers. Certificate checks are separate from the optimization algorithms.
• The rescue benchmark enumerates every whole-number clearing on 2,993 small networks in each of two recovery conditions, giving an exact answer to compare with the heuristic.
• Seeded scale benchmarks exercise synthetic supply chains; the reported timings are not measurements of customer transaction data.
• Server tests cover authentication, group authorization, audit scope, settlement confirmation, and fixed-point storage.
• The verify command runs lint, all three test suites, the server TypeScript build, and the production web build.

• A purely hierarchical or acyclic obligation graph gives cycle mode nothing to cancel.
• Path mode can create relationships between people who did not previously owe each other.
• Cancelling a loop can shift recovery away from a creditor outside it when someone in the loop cannot pay.
• A configured circulation iteration limit can stop the reference solver before optimality; the result must report that limit.
• The rescue heuristic can miss the best plan, and a loose lower bound can leave a substantial reported gap.
• Currency conversion context does not remove exchange-rate or rounding policy decisions.
• External receipt OCR can fail and may require consent for third-party data handling.

• The documented five-person example reduces ₹4,800 across eight IOUs to ₹550 across four payments in full-simplification mode.
• Cycle mode guarantees zero new counterparties; path mode reports every new pair it creates.
• On the documented 18,831-party, 51,375-obligation synthetic network, routing took 1.26 seconds and certificate verification took 3 milliseconds.
• A larger synthetic fixture with 122,456 obligations took 4.88 seconds with routing; its certificate checked in 3 milliseconds.
• The rescue search matched the optimum on 99.73% of the 2,993 lossless fixtures and 99.77% with bankruptcy losses. Its misses were one failed party above the optimum.
• The clearing engine is a standalone dependency-free TypeScript package that runs in the browser.
• Role-aware groups, recipient-confirmed settlements, an audit history, exports, and live updates.

I keep these objectives separate because doing well on one does not imply doing well on the others. A computed plan also remains separate from the app's recipient-confirmed record of a real payment.

• Cancel loops: remove the most debt possible while keeping the original counterparty set; routing and simplex can certify this optimum.
• Simplify all: also shorten open chains toward the net-position floor, disclosing every new pair.
• Rescue: search for partial cycle clearing that leaves fewer parties unable to pay under the stated cash and recovery assumptions.
• The optional exact/greedy balance solver answers a fourth, older question: the fewest transfers for a balance vector. Its C++/WASM implementation is not the new clearing engine.

• CashFlow records obligations and confirmations. It does not hold funds or connect to a bank.
• The hosted application is a public beta, not an audited financial product.
• The large benchmark networks are seeded fixtures, not private production transaction data.
• Cash positions in the rescue benchmarks are generated. The results are not forecasts of real defaults.
• The payment model is one-period and pro rata. It does not represent secured creditors, payment due dates, or insolvency law.
• The optional C++/WebAssembly minimum-transfer solver remains in the repository, but it is not the engine behind the browser's obligation-clearing comparison.
• A user should not enter financial data they would be uncomfortable storing in a hosted PostgreSQL database.