Module budget 

Budgets, reserves, and the lines between them.

A budget is an envelope with a goal: credits come in and debits go out over a month or a year, and the balance should reach its target by the end of the period. Lines come from mail (invoices, payment notifications, through mail rules), from presets (automatic payments that send no mail: rent, insurance, wages), and by hand. Reserves (savings accounts) cover the budgets assigned to them: at the end of a period a shortfall is drawn from the reserve, and a surplus can be swept back into it.

A budget keeps its balance from one period to the next, as an envelope keeps what was not spent: money set aside in October for a bill due in December is still there in December, and no reserve is drawn twice.

“On track” does not assume money flows evenly: the balance carried in, what happened so far, and what is known to come before the end of the period (presets and planned lines) are compared with the target (docs/accounting.md).

Modules

dates 🔒

TOML writes dates bare (2026-10-01) and jiff reads them as text: both are accepted.

Structs

Assignment

One movement placed by your hand: in a budget, in parts between budgets, or in none (a transfer between your accounts, a refund already counted).

BankAccount

Where money actually is: a current account, PayPal, Stripe. Its movements, read from its exports (bank::Bank), fill the budgets it pays for (docs/accounting.md, “Bank accounts”).

Budget

An envelope with a goal.

BudgetEdit

A budget as its form gives it.

BudgetStatus

A budget’s current period, at a glance.

Cover

Which reserve covers which budget’s shortfall, at the end of each period.

Flow 🔒

One flow of money in a budget, whatever its source.

Ledger

Everything in sioul-budgets.toml.

Line

One credit or debit of a budget.

MailLine

A message about money, and what becomes of it in the budgets.

MailRule

Mail that becomes a line: an invoice, a payment notification.

Movement

One movement of a budget’s period, as its ledger lists it.

Pace

How a budget’s period is going, at its pace: what is known in advance (presets, planned lines) counts in full; the rest is judged against the part of the period gone. Ten days into thirty, a third of what the period still needs should have come (or no more than a third of what it can spend should be spent): then it is on track.

Part

A movement’s share in one budget.

Point

The balance on a day, and whether that day is still to come.

Preset

A payment that comes back: rent, insurance, wages; or an estimate of what is spent without a trace (food, cash). Mail can stand for one of its occurrences: a line linked to it (preset) replaces a fixed preset’s amount, and is spent from an estimate’s envelope, never added on top.

PresetEdit

A recurring movement, as its form gives it.

Reserve

A savings account that covers budgets: an assurance vie, a Livret A.

ReserveStatus

A reserve, at a glance. Amounts leaving the reserve are positive.

SeenLine

A line of the file as the page showed it, to find it again: lines are named by their place among the lines (sioul:budget/<budget>/<place>), and the file may have changed since the page was made (a line added or taken out on another device, or by hand). Never changed by its place alone.

Split

Where a bank account’s movement goes, when its label holds one of words: a budget (and the recurring payment it stands for), a reserve (money moved with a savings account), or another bank account (money moved between yours, counted in no budget). The first rule that holds wins.

Enums

Direction

MailState

Period

Verdict

How a budget’s period is going, against its target.

Constants

LEDGER

The file’s name, at the root of the notes folder.

SAME_PAYMENT_DAYS 🔒

Days within which a merchant’s confirmation and the processor’s payment are one payment.

SETTLED_DAYS 🔒

Days within which a bill and the message saying it was settled belong together.

Functions

change_line

A line of the file changed in place: its label, amount and date; its links, its budget and the comment saying where it came from stay. A date to come makes it planned. The line is found as remove_line finds it; Ok(false) when it is not found as it was (seen): nothing is changed.

find_line 🔒

Where the line seen is in the file now: at place when it is still there, else the one line of the file that is it. None when it is gone, changed, or not told apart from another line just like it.

kind_of 🔒

mail_line 🔒

mail_lines

Every message about money among items, newest first, with what becomes of it. Mail set aside (forged, spam) and the review queue’s (what your own spam filter flagged or moved) are never read; a rule gives the budget and the preset; ignored holds the keys you said are not payments.

mark_duplicates 🔒

Marks the second message of each pair that tells the same payment: the same message at two addresses; an order and the payment for it (same amount, a few days apart); a bill and its settlement (same sender). What you recorded stays counted, and its partner becomes the duplicate.

record_line

Writes a line at the end of the budget file, keeping its comments, with a comment saying where it came from.

record_preset

Adds a recurring movement to the budget file, its comments kept.

remove_budget

Takes a budget out of the file. Its lines stay, written as they were, and no longer count anywhere.

remove_line

Takes one line out of the file: the one at place among the lines (as sioul:budget/<budget>/<place> names it) when it is still the line seen, else the one line that is (find_line). Ok(false) when the line is not found as it was: nothing is changed, for the page to say so.

same_payment 🔒

Whether a tells the payment b tells, b being the one that counts.

save_budget

Makes a budget (id empty) or changes one, in place, its comments and its other fields kept; returns its id.

settle_line

The planned line link names (an invoice, “sioul:invoice/2026-002”) made real: paid on date, no longer planned. Returns whether there was one.

still_needed 🔒

What the period still needs, beyond what is scheduled in it, to reach the target from opening (pace, tolerance).

tolerance 🔒

“As planned” within this many cents of the target, the same for sioul budgets (status) and the window’s verdict (pace): 5 % of what the period moves (each of its flows, in or out, done or planned, and what it still needed beyond what is scheduled), never closer than 10 units (docs/accounting.md, “On track, without assuming money flows evenly”). Wide enough that a budget whose money comes later in the month is not “short” in its first days.

write_ledger 🔒