> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vinmake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nothing stored that can be derived

> The paste-over-value failure class, why a derived value cannot drift, and the honest decision not to reproduce a workbook check that was true by construction.

# Nothing stored that can be derived

## What it guarantees

No balance in GreatBook is stored.

A bill's outstanding amount, a payment's unapplied balance, the AP and AR control totals, the advance pools, the rail balances, the employee float, stock on hand, weighted-average unit cost, WIP, the 627 overhead pool, the facility balance, the VAT positions.
All of them are **computed** from the sub-ledger rows plus the GL, every time they are asked for.

There is no `balance` column to drift, because there is no `balance` column.

## The failure class

This is the whole reason the finance layer is built the way it is, so it is worth stating precisely.

A spreadsheet holds a derived value in a cell with a formula.
Somebody, at some point, pastes a value over that formula.
Perhaps to fix a display glitch, perhaps to hardcode a number that was right at the time, perhaps by accident with a paste-as-values.

From that moment:

* the cell shows a number,
* the number no longer follows its inputs,
* **nothing about the cell looks different**,
* and every downstream figure that reads it is quietly wrong.

That is the **paste-over-value failure class**, and it is the single most common way a spreadsheet-run book of record goes wrong.
It is not a mistake in the arithmetic.
It is a mistake in the *architecture*: it stores something that should have been derived.

A stored `bill.due` column is the database version of that pasted cell.
The moment one code path forgets to update it, or two paths update it differently, or a migration backfills it from stale data, it holds a number that no longer follows its inputs and looks exactly the same as one that does.

**A derived value cannot drift.**
Not "does not drift if everyone is careful".
Cannot.

## What derivation looks like

Every balance is one query over rows that already exist.

```
due(bill)            = total - Σ allocations - Σ advances applied
                       + Σ DEBIT notes - Σ CREDIT notes

unapplied(payment)   = amount - Σ allocations

AP control           = Σ due over open bills

rail balance         = Σ settlements on the rail, per currency

gl_balance_base(acct)= Σ (debit_base - credit_base)
                       over posted lines on that account
```

`derive.py` is a thousand lines of these, and it is deliberately dull.
Each function is a `SELECT` with a `coalesce(..., 0)` and a `money.to_money` on the way out.

The GL balance function is the one everything else reconciles against: signed, in base currency, positive meaning net debit, with callers negating for credit-normal accounts.
One implementation, so no two reports can disagree about what an account balance is.

## The honest decision at the heart of the Close list

Here is where this principle produced a decision that is worth publishing.

The v12 workbook has a family of checks of the form "does the stored balance equal the derived balance?" In a relational model where the balance *is* the derivation, that check is a **tautology**: it compares a value to itself and passes unconditionally.

Reproducing it would have been easy, would have produced a green row on a dashboard, and would have tested nothing.

It was not reproduced.
Instead, where the workbook's check was true-by-construction, the version **with real teeth** was implemented:

| Instead of the tautology                | The check that was built                                                                           |
| --------------------------------------- | -------------------------------------------------------------------------------------------------- |
| stored balance equals derived balance   | the sub-ledger-to-GL **control tie** - catches a rogue posting straight to the control account     |
| a pool reconciles to itself             | `Σ abs(advance pool)` - catches an unapplied deposit                                               |
| a document reconciles to its own fields | **cross-foot** - catches an allocation with no settlement behind it                                |
| book equals book                        | reconciliation against **external bank evidence** - catches a booked payment the bank never showed |
| a type is valid because it was written  | the enumerated **rail catalog** and the other catalog checks                                       |

That table is the most credible thing in the finance layer, because it is a record of somebody noticing that a check would pass for the wrong reason and choosing the harder replacement over the green row.

<Note>
  The same reasoning appears in [inventory and costing](/greatbook/capabilities/subledgers/inventory-costing).
  The workbook's WIP check nets to zero because a live unit-cost formula moves both legs together.
  GreatBook stamps the cost immutably on the movement, so the two legs cannot move together, and `WIP-154` becomes a check that can actually fail.
</Note>

## The cost, stated

Derivation is not free.
A control-account total is an aggregate over the sub-ledger every time it is asked for, and at ten million rows that is a real query.

The answer is indexes and, if it ever comes to it, materialised views that are **rebuilt from the derivation** rather than written to by application code.
The distinction that matters is not "cached versus computed"; it is **who may write the number**.
A cache the derivation owns is fine.
A column the application writes is the pasted cell.

Today the book is well inside the size where the straightforward query is the right answer, and the reconciliation surface runs in seconds.

## Where it is enforced

| Concern                                                  | Code                                                           |
| -------------------------------------------------------- | -------------------------------------------------------------- |
| every derivation, roughly a thousand lines of them       | `backend/app/logics/finance/derive.py`                         |
| the decision not to reproduce tautological checks        | `backend/app/logics/finance/close_checks.py`, module docstring |
| the immutably stamped costs that make the WIP check real | `backend/app/logics/finance/costing.py`                        |

## The test that would fail if it broke

There is no single test, because this is a structural property rather than a behaviour.
The evidence is the absence: no balance column in any migration, and `close_checks` comparing two independently derived paths rather than a value against itself.

The closest thing to a direct test is the sub-ledger-to-GL control ties, which fail the moment a balance is written anywhere other than as a journal entry.

## Related

* [Why a ledger, not a spreadsheet](/greatbook/why-a-ledger) - the same argument for a general audience
* [The Close checksums](/greatbook/capabilities/close-list) - the checks that replaced the tautologies
* [The seven sub-ledgers](/greatbook/capabilities/subledgers/index) - where the derived balances live
* [Inventory and costing](/greatbook/capabilities/subledgers/inventory-costing) - the stamped-cost version of the same idea