/finance-expert

Posting rules — <Acme Wallet>

Copy to docs/POSTING-RULES.md. This table is the heart of the system: it is the complete mapping from business event to journal entry, and it is written before any code.

How to use it

Read this section once, then never again — but do read it once.

1. Whoever owns the books reviews and signs this table before implementation starts. Not the design doc, not the PR — this table. An account or a rule added later without the finance owner's sign-off is a control failure (M11), not a refactor.
2. One row per (event, condition) pair. If an event books differently depending on a condition, that is two rows with the same rule id and different Condition cells — not one row with a sentence of prose in it.
3. Every row is implemented by exactly one function, named after the rule id, and tested by a golden entry (§ How to test a rule). A rule with no golden entry is not implemented, whatever the code coverage says.
4. Amount expressions are exact. total − Σ parts is an expression; "the remainder" is not.

Conventions

The entry envelope

Every entry produced by every rule carries these fields alongside its legs. They are not metadata — they are what makes an entry explainable a year later, and each one is load-bearing for an invariant. A field you cannot populate is a rule you have not finished designing.

The rules

Fill the <…> cells for your product; the rows below are a complete, working set for a wallet-and-marketplace product and are meant to be edited, not admired. Account codes refer to accounts/chart-of-accounts.yaml.

Worked example: one customer, end to end

Run your own rule set through a sequence like this before you write code. If the trial balance does not tie by hand, it will not tie in production — and you will be debugging it against a customer. EUR, integer minor units, user:42 tops up 100.00 and spends 30.00 with merch:7.

Trial balance after step 9

Everything else nets to zero: 1200, 1500, 1510, 2010, 2200 and both memo accounts are transit and hold accounts that must clear — a residual balance in any of them at this point is the bug, and it is much cheaper to find here than in month three.

Read the result: you hold 70.80 in cash, owe 70.50 (70.00 to the customer, 0.50 to the tax authority), and the 0.30 difference is profit — fee income 2.50 less PSP cost 2.00 less bank charge 0.20. Every one of those numbers is a query over postings, not a stored field (M1). Steps 6 and 7 exist because between them the 98.00 is in neither the PSP account nor the bank; without 1500 you either lose sight of it or book the bank credit before it happened.

The sequence stops one step short on purpose. In production a tenth step runs the same evening: SG-01 moves 70.00 out of 1000 into 1050, because that is the customer's money and it may not sit in the operating account. 1000 is then left holding 80 — the 0.50 owed to the tax authority and the 0.30 of margin, both ours — and the daily control holds exactly: 1050 EUR 7 000 = Σ(2000 + 2010) EUR 7 000. Run your own sequence to that point, not to step 9, or you will ship a set of rules that balances beautifully and safeguards nothing.

Rule versioning and replay

Posting rules change. The question is never "can we change it" but "what happens to the entries the old rule produced". A bad answer edits the rule and reruns the job.

Change log

How to test a rule (M18)

A golden entry is the rule's specification in executable form: a fixed input event, and the exact entry it must produce, byte for byte. If a code change alters an entry, the diff appears in the test before it appears in the books.

Every rule needs all four:

def test_PU_02_captures_purchase_with_inclusive_vat():
    """Golden entry: total 30.00 EUR, commission 3.00 incl. 20% VAT."""
    entry = apply_rule("PU-02", purchase(total=3000, commission=300, vat_rate="0.20",
                                         account_id="user:42", merchant_id="merch:7"))
    assert entry.legs == [
        Leg("2010", "user:42",  +3000, "EUR"),   # debit  wallet reserved
        Leg("2200", "merch:7",  -2700, "EUR"),   # credit merchant payable
        Leg("4000", None,        -250, "EUR"),   # credit fee income, net of VAT
        Leg("2100", None,         -50, "EUR"),   # credit VAT payable
    ]
    assert sum(l.minor for l in entry.legs) == 0          # M2, single currency
    assert entry.rule_version == "1.2"

Plus, in CI on every build: a trial-balance assertion over the whole fixture ledger (Σ debits = Σ credits per currency), and python3 scripts/audit_ledger.py fixtures/entries.csv --fail-on warn.

Rules that need a human decision

Do not resolve these in code. Propose, cite the reasoning, get the finance owner's sign-off, and record the answer in FINANCIAL-SYSTEM-SPEC.md §10 until it is signed.