OpenSteward

Multi-device sync usually means a server that orders the writes. OpenSteward has none. Each device appends only to its own log file in a folder the person picks, so a file-sync service only ever copies whole files and never merges one. The budget on screen is a pure fold of the union of every log.

Each event carries a Hybrid Logical Clock stamp: physical milliseconds that never move backward, a counter for collisions, and the device id as the final tie-breaker. Packed at fixed width, the stamp sorts correctly as a plain string and doubles as the event id. Reading another device’s log moves the local clock past every stamp seen, so an edit made after reading a colleague’s change sorts after it, whatever the wall clocks say. Sync waits for the device’s own queued writes before reading, money is integer cents, and the reducer still reads older event shapes, because an append-only log keeps them for good.

The HLC is a published technique; the source credits the idea to Actual Budget’s CRDT layer and says it is the only idea taken from it. The implementation, and the serverless design around it, is the part of this I’d defend line by line.

The default was to adopt Actual Budget, a mature, local-first envelope budgeter. Two requirements overruled it. Sync had to work with zero servers, through plain files in a folder the person already syncs, and Actual’s multi-device sync runs through a sync server. And the dependency set had to be small enough to vet end to end, where a fork brings a large transitive tree.

The same requirements shaped the rest. A mutable database file in a synced folder can be grabbed mid-write; per-device append-only files have one writer each. The CSV reader is written in-house, because every dependency must be licence-checked against the AGPL. The money-field calculator is a small shunting-yard evaluator with no eval(). And the desktop shell is Tauri, not Electron, for a smaller attack surface.

The web build reaches the budget folder through Chromium’s File System Access API. Packaged with Tauri, the macOS app renders in WKWebView, Safari’s engine, which has no folder picker, so a naive package quietly falls back to browser storage. The fix is two storage backends behind one interface: a directory handle in the browser, a plain path on the desktop, where all file access goes through four small Rust commands.

Shipping is scripted. The Mac build refuses a dirty tree, because it bundles the working tree rather than HEAD. It bumps the build number, stamps it into the app, then re-signs and verifies the signature before installing. That check arrived after build 1 came out with a signature broken by stamping after signing. The Windows build reuses the number without bumping it, so one commit yields two binaries with one build number.

A bank export names the merchant, not the budget category, and card exports change the store number on every visit. Import uses the file’s own category column when it names an existing category. Otherwise it tries the exact payee from history, then an exact stored default, then a normalised name (processor prefixes, store numbers and reference codes stripped) against each. The most recent use wins, and an exact match beats a normalised one.

No guess lands in the books unseen. Every imported row is stored as needing review and arrives uncleared. A row can’t be confirmed without a budget item, Confirm all stays disabled until every row has one, and because the flag lives in the event log, closing the app halfway approves nothing. In Fig. 1 the gate holds one new merchant and two payee variants the normaliser missed. Import never removes duplicates: an export carries no transaction id, so two identical purchases can’t be told apart, and the dialog warns that rows already imported won’t be detected.

That is the shape AI-assisted workflows need: deterministic suggestions behind a required human gate.

The strategy is to copy YNAB 4’s budgeting behaviour exactly first, on purpose, and diverge later, so that every divergence is chosen against a baseline that has been shown to match. That parity isn’t finished yet. The oracle that checks it is separate from the importer. It computes a live reference budget from first principles, out of the reference app’s own files, folds the app’s live folder through the same selectors the screen uses, compares every envelope, balance and month header, and exits non-zero on any difference. It runs against a private budget, wasn’t passing at its last recorded run, and can’t be re-run for this page.

Beneath it sits an invariant that must hold whatever the reference says: available-to-budget plus every envelope balance equals the working balance. On the invented demo budget it holds.