A
?
AssetsWorkflowsHandbookDesign system
← Handbook

The attested bank ledger is the source of truth

On 10 September 2026 Alex checked every statement in the bank ledger by hand against the DBS PDF: money in, money out, balance carried forward, 45 statements across both companies' accounts. He then said: *"lock this in somewhere as the truth. this cannot be reset unless I say so. this is the source to follow over all else."*

What the rule means

  • Every finance figure must add up to the attested ledger. If a number anywhere in the portal, a sheet or a report disagrees with the ledger, the number is wrong, not the ledger.
  • Attested statements are frozen. No row belonging to an attested statement may be inserted, deleted, or have its date, amount, direction, balance, account or statement period changed. Categories, counterparties, client links and notes remain editable, because those belong to later layers and do not change what the bank did.
  • Attestations are frozen too. The table bank_statement_attestations holds the figures Alex ticked. Rows cannot be updated or deleted.
  • New statements are not locked until a person attests them. Import a new month, check it against the PDF, then attest. Until then the ledger page shows it as unattested.

How it is enforced

In the database, by two before triggers (ledger_lock_guard, attestation_lock_guard, migration 0117). They refuse the change with an error naming the statement and the date Alex checked it. This is not a UI rule and not a code review rule. A script, a migration or a person with a database console hits the same wall.

The ledger page (/finance/overview) recomputes every statement from the rows on each load and compares it with the attestation. Any drift is shown in red before any total. Drift should be impossible while the lock holds; the check exists so that if the lock is ever bypassed, it is seen.

How to unlock, and when

Only when Alex has said so, for a named statement, in his own words. Then, in the same transaction as the change:

set local atlas.ledger_unlock = 'alex authorised this change';

Record what changed and why in docs/knowledge/, and re-attest the statement afterwards so it is locked again. The phrase is deliberately absent from application code. Nothing the portal does in normal operation can unlock the ledger.

Why this shape

A rule that lives in a document gets skimmed and then forgotten; a rule that lives in the database fails loudly at the moment someone forgets. The figures were checked twice, by the running-balance chain across 4,438 rows and by Alex against 45 PDFs, and the cost of that check is only recovered if nothing can quietly undo it.

Related: docs/knowledge/finance-bank-ledger-is-the-ssot.md, docs/rules/data-safety.md.