journal source pure

Balance returns the account's balance in its NORMAL direction: for a debit-normal account Debits-Credits, for a credit-normal account Credits-Debits. A normal account therefore has a non-negative balance, and a negative result is a real signal (a contra position) rather than a sign convention.

RawDelta returns Debits-Credits regardless of kind. Summed over every account in a balanced book it is exactly zero, which is what makes it the useful quantity for a consistency check and the wrong one for a report.

Account returns an account by code. The second result is false if no such account is open.

AccountCount returns how many accounts are open.

AccountingEquation returns the two halves of assets+expenses versus liabilities+equity+revenue, in RAW debit-minus-credit terms, and whether they offset.

IT IS WEAKER THAN IT LOOKS, and weaker than this doc used to claim.

What offsets ACTUALLY proves: sum(RawDelta) == 0 over the whole chart, which is the same fact as IsBalanced's first conjunct (d == c) and nothing more. IsBalanced requires three. So this is implied by IsBalanced, is NOT an independent accounting fact, and citing it as a second guarantee alongside IsBalanced is counting one check twice.

What offsets DOES NOT prove, despite the Kind partition sitting right there in the code: anything whatsoever about normal-balance handling. dn and cn are a partition of the same addends, so dn+cn is the total regardless of which bucket each account landed in. Reclassify every account in the chart and BOTH subtotals change while offsets stays true. A Kind set wrongly at Open time is undetectable here and undetectable anywhere else in this package — obligation 7.

It is exported because the two SUBTOTALS are correct and a consumer presenting a balance sheet wants them anyway. They are the product; offsets is a duplicate of a check you already have.

Balance returns an account's balance in its normal direction, and whether the account exists. A missing account returns (0, false) rather than a zero balance, because "no such account" and "balance zero" are different answers and a consumer branching on the number alone would conflate them.

Close seals the period ending at `through`, after which Post and Reverse refuse any entry dated at or before it.

It only moves forward. A first close may name any non-negative instant; a later one must name a strictly greater instant, so a seal can never be loosened and backdating can never be re-enabled.

Fails with ErrInvalidAt (through < 0) or ErrCloseNotForward. On error nothing is modified.

ClosedThrough returns the period seal: entries dated at or before it are refused. The second result is false if the Book has never been closed, in which case the first is meaningless — a Book closed through 0 and a Book never closed differ, and collapsing them would silently reject entries dated at 0.

Entries returns up to limit entries with ID >= from, in ascending ID order, each with a defensive copy of its postings. A limit <= 0 returns nothing. It is the paging read for a consumer that cannot hold the whole journal in one call.

Entry returns an entry by ID, with a defensive copy of its postings. The second result is false if no such entry exists — which, because entries are never removed, means it was never created.

EntryCount returns how many entries the journal holds. It never decreases.

IsBalanced reports whether the Book's two independently-maintained accumulators agree with each other and with themselves.

It scans the chart, sums every account's debit and credit totals, and requires that the two sums are equal AND that each matches the Book's own running total. Those totals are written by different code in Post, so a disagreement is a defect in this package and IsBalanced is how a consumer detects one.

What it does not do is re-read the journal. Read the package doc's "What balanced is actually worth" before quoting it, and use RederiveFromJournal for the strong claim.

An empty Book is balanced.

IsReversed reports whether an entry has already been reversed. It returns false for an entry that does not exist, so pair it with Entry when the distinction matters.

IterateAccounts calls fn for every account in ascending code order. Iteration stops early when fn returns true.

fn receives a COPY: Account is passed by value and holds only scalars and strings, so fn gets no pointer into the Book.

Two rules for fn, and the second is the one that is easy to miss.

• Do not Open, Post, Reverse or Close from inside fn: mutating a tree while iterating it is undefined. Collect what you need first, then act after IterateAccounts returns.

• fn runs under the CALLING REALM'S STORAGE AUTHORITY. This method's receiver is stamped with the importing realm's PkgID, so the borrow rules leave the realm context set to that realm for the whole callback, and a top-level fn has no receiver and no declaring realm to anchor it elsewhere. A callback that re-enters the calling realm's own mutators therefore does so with that realm's authority. Never pass a caller-supplied function here from inside a permission-gated path; pass only a closure this package's consumer wrote itself.

IterateEntries calls fn for every entry in ascending ID order, which for an append-only journal is also chronological by insertion. Iteration stops early when fn returns true.

fn receives an Entry whose Postings slice is a DEFENSIVE COPY, so a callback cannot write through it into Book state. The two rules on IterateAccounts's fn apply here unchanged, including the storage-authority one.

MaxAccounts returns the Book's cap on chart size.

MaxEntries returns the Book's lifetime cap on entries.

MustClose is Close but panics on error.

MustOpen is Open but panics on error.

MustPost is Post but panics on error.

MustReverse is Reverse but panics on error.

NextID returns the identifier the next entry will take. It only ever increases, so an entry ID identifies one entry for the life of the Book.

Open adds an account to the chart. Codes are unique and immutable: there is no Rename and no Close, because an account's cumulative totals are part of the derivation of every balance that cites it, and removing one would make the journal unreplayable.

Fails with ErrEmptyCode, ErrCodeTooLong, ErrNameTooLong, ErrInvalidKind, ErrAccountExists, or ErrChartFull. On error nothing is modified.

Post appends a balanced entry and returns its ID.

The postings must number at least two and at most MaxPostingsPerEntry, each naming an open account, a valid Side, and a positive Amount. The entry must contain at least one debit and at least one credit, and the two column totals must be equal — an inequality is reported as ErrDebitShort or ErrCreditShort, naming the column that needs more.

Fails with ErrInvalidAt, ErrMemoTooLong, ErrPeriodClosed, ErrBookFull, ErrIDExhausted, ErrTooFewPostings, ErrTooManyPostings, ErrInvalidSide, ErrInvalidAmount, ErrUnknownAccount, ErrNoDebit, ErrNoCredit, ErrDebitShort, ErrCreditShort, or ErrOverflow. On error nothing is modified — every posting is validated and every total computed before the first write.

RederiveFromJournal replays every posting of every entry and reports the debit and credit totals it finds, together with whether they agree with both the per-account accumulators and the Book's running totals.

This is the strong check and the expensive one: its cost is proportional to every posting ever made, so it is meant to be called deliberately — by an auditor, or by a consumer's own invariant view — and not from a hot path. `agrees` false on a Book this package built is a defect in this package.

Reverse appends the mirror of an existing entry — every posting repeated on the opposite side, for the same amount — and returns the new entry's ID. The original is left exactly as it was.

An entry may be reversed at most once. Reversing a reversal IS permitted (it re-applies the original's effect) and is itself subject to the same once-only rule, so a correction cannot be looped.

`at` dates the correction and must be in the open period: a sealed period cannot be corrected in place, by construction. Correcting one means posting into the current period, which is the consumer's decision to make explicitly rather than this package's to make silently.

Fails with ErrInvalidAt, ErrMemoTooLong, ErrPeriodClosed, ErrEntryNotFound, ErrAlreadyReversed, ErrBookFull, ErrIDExhausted, or ErrOverflow. On error nothing is modified.

TotalCredits returns the Book's running credit total across every entry.

TotalDebits returns the Book's running debit total across every entry.

IsReversal reports whether this entry was produced by Reverse.

Total returns the entry's debit total, which for any entry a Book accepted equals its credit total.

IsDebitNormal reports whether an increase in k is recorded as a debit. Asset and Expense are debit-normal; the other three are credit-normal. An invalid Kind reports false, which is why callers validate first.

String returns the kind's name, or "invalid" for the zero value and any unrecognised code.

Valid reports whether k is one of the five kinds.

Opposite returns the other side. An invalid Side returns itself, so a caller that skipped validation gets an invalid posting rather than a plausible one.

String returns "debit", "credit", or "invalid".

Valid reports whether s is Debit or Credit.