Help wiki Reference
Amounts, balancing and validation
Exact money, declarations, missing amounts, costs, dates and balance assertions.
Exact amounts and commodities
An amount stores a commodity symbol, an arbitrary-size integer mantissa and up to 255 decimal places. Display style is separate from value. For example, 12.50 is mantissa 1250 with two places. An ordinary write with more places than the commodity accepts is refused; import can increase the commodity’s places and reports that change. No write silently rounds away excess precision.
Account and commodity declarations are exact and case-sensitive. Declaring assets:bank does not declare assets:bank:checking, and USD differs from usd. A bare amount has the empty commodity, which also requires a declaration. There is no unchecked mode.
Balancing and omitted amounts
Real postings must balance exactly. Balanced virtual postings, written with [account], balance independently; unbalanced virtual postings, written with (account), do not contribute to the real balance check. At most one real posting and one balanced virtual posting per transaction can omit an amount. The missing amount is inferred from the others in its own group. Several inferred commodities are stored as separate postings.
Supported unit costs (@) and total costs (@@) participate in balancing. They do not change the balances checked by assertions. A posting carrying an assertion must have an explicit amount; Kabacus does not infer it from the asserted balance.
Dates and assertions
Transactions use calendar dates, without a time zone or time of day. Assertions check the end of their day, including every transaction dated on or before that day. Order within one day does not change the result. Moving an edited transaction to another date rechecks assertions from the earlier affected date forward.
| Operator | Checked balance |
|---|---|
| = | This account, only the named commodity. |
| =* | This account and all subaccounts, only the named commodity. |
| == | This account’s entire balance; other commodities must be zero. |
| ==* | The entire balance of this account and its subaccounts; other commodities must be zero. |
New assertions on money accounts are inclusive, so moving cash into their reserves does not break reconciliation. A change that breaks an assertion is refused and names the account, day and asserted and calculated amounts.
Write pipeline
- Compare the expected head with the current revision; refuse a stale write.
- Apply the proposed change in memory and check amounts, balancing, assertions and declarations.
- Store all row changes and their audit record atomically as one revision.
A dry run uses the same validation without storing anything. Batches contain up to 100 writes and become one revision. A refused write, a conflict or saving an unchanged transaction creates no revision. Descriptions cannot contain a line break or semicolon; put structured metadata in the supported fields instead.