Proposal: financial statement definitions over the balance ledger

[delchev]

Adds proposals/0021-financial-statement-definitions.md. Proposal-first, per CONTRIBUTING — the version document is untouched.

The gap

A balance report describes opening / period / closing debit and credit totals over a signed ledger, per dimension, between two runtime dates. A statutory statement — a balance sheet, an income statement — is a fixed line structure over the same ledger, where each line is a formula over the chart of accounts and some lines are arithmetic over other lines.

Those are different shapes, and the whole mapping between them falls outside the format today: an account-level balance is the raw material, and turning it into a balance sheet happens in a hand-written query or a spreadsheet. It is the last ledger report family with nothing in the format behind it, and the one most clearly a declaration rather than code — a jurisdiction change or a chart extension is a mapping edit.

The shape

reports:
  - name: BalanceSheet
    kind: statement
    source: JournalEntryItem
    date: journalEntry.entryDate
    debit: debit
    credit: credit
    account: account.code
    filter: "journalEntry.status == 2"
    lines:
      - { code: A.I,  label: Fixed assets, accounts: "20*,21*", measure: closingNetDebit }
      - { code: A.II, label: Receivables,  accounts: "41*",     measure: closingNetDebit }
      - { code: A,    label: Total assets, sum: [A.I, A.II] }
      - { code: B.I,  label: Payables,     accounts: "40-49",   measure: closingNetCredit }
      - { code: B,    label: Net assets,   sum: [A], less: [B.I] }

What the proposal states normatively

The rule that carries the most weight is the Net measures': an account's two sides are netted before a line sums it, and only what remains on the named side is kept. That is observable, not an implementation detail — it is what lets one settlement account appear in both the asset and the liability section of a statement and contribute to whichever one its actual balance puts it on. Netting after the sum would report gross turnover, which is a different figure and is what the four plain measures are for.

Alongside it: the rows are the declared lines in the authored order (statutory codes do not sort into their own structure), an empty line renders as zero rather than disappearing, and a range selector compares equally long code prefixes (60-69 takes 601 and 6999; comparing whole codes would drop both).

Boundary

The statement's numbers are the format's contribution. The legally mandated print layout stays a hand-authored print template — the same boundary between model and document designer the format already draws.

Left open deliberately

Whether a statement's lines should additionally be maintainable as seeded, tenant-editable data is a genuine second question, and the proposal says so rather than deciding it: the authored form is what makes a statement reviewable and versioned with the model, and a tenant-editable variant can be layered over the same semantics later.

Implementation

Eclipse Dirigible: eclipse-dirigible/dirigible#6912 (issue eclipse-dirigible/dirigible#6909). The emitted query is exercised against a real ledger on both of that project's CI databases.