# Ledger

A cash book with receivables and payables. It records what you invoiced, what you were billed, what was paid, and money that moved without an invoice, then tells you what is still outstanding.

## What it is not

It is not double-entry bookkeeping. There is no chart of accounts, no journals, no trial balance. It computes no VAT and handles a single currency. It does not read bank feeds and it does not talk to QuickBooks.

If you need statutory accounts, this is not that. It is the answer to "who owes me what, what do I owe, and where did the money go".

## The seven things you can ask for

**Record an invoice you raised.** A reference, who owes you, the amount, and when it is due.

**Record a bill you received.** The same, in the other direction.

**Record a payment.** Against either an invoice or a bill. You give the reference, the amount, the date and how it was paid.

**Record a credit.** Against an invoice you raised. It reduces what is owed exactly as a payment does.

**Record a cash movement.** Money in or out that belongs to no invoice: bank charges, a cash sale, drawings, a refund.

**Ask what is outstanding on one document.** You get the total, what has been paid, what has been credited, and what remains.

**Ask for a statement.** Everything owed to you and everything you owe, sorted into 0-30, 31-60, 61-90 and 90+ days overdue, plus net cash.

## You look the customer up first

When you record an invoice or a cash movement, the agent finds the company or person in your records first, then attaches the money to that exact record. It will not create a new company for you, and the name that appears on the invoice is taken from the record it attached to, so the two can never disagree.

That is on purpose. Deciding whether "Beagle Direct Ltd" is the same firm as an existing "Beagle Direct" is a judgement about your records, not a bookkeeping step, and getting it wrong quietly splits one customer's payment history across two entries.

## Three behaviours worth knowing about

**What is outstanding is never stored.** It is worked out from the payments each time you ask. This means the figure cannot fall out of step with the payments behind it. If it were stored, a payment recorded by any route that forgot to update it would leave the invoice quietly reporting a wrong number, and nothing would fail.

**Paying more than is owed is refused.** If an invoice has 4,400 left and you try to record 5,000, nothing is written and you are told the figure that would settle it. It is not rounded down to 4,400 and it is not recorded anyway. A ledger that quietly accepts an impossible payment is worse than one that says no.

**Every payment is read back.** After a payment is written, the invoice is re-read from the graph and the outstanding figure is checked against what was expected. If they disagree you are told to stop recording against that invoice until it is sorted out. Writing something is not the same as it having landed.

## The health check

Some ways this can go wrong announce themselves. Others do not: a payment that ends up attached to no invoice, a stale balance field reappearing, or the same payment recorded twice under two different ids. None of those produce an error at the time, because nothing goes wrong at the moment they happen.

So there is a check that runs by itself every fifteen minutes and writes one line to the log beginning `[ledger-census]`. When it is healthy the counters are all zero. When something is wrong the line ends with `alarm=true` and says which of them it found.

One of those counters is the number of writes that were refused in the last day. It is there because of a real failure: for a whole day every attempt to record money was refused, and the check still read as healthy, because a ledger nobody has used and a ledger that cannot be written to both show nothing.

You can also ask for that check on demand at any time, and it reports the same thing in plain words.

If you never see the line at all, that is itself the problem: it means the periodic check is not running.