A demo that runs the engine
Everything below was computed when this page was served, by the same code the product runs. No signup, no recording, no mock data. The figures are acceptance fixtures in the test suite, so the build fails before this page can claim something the engine would not do.
1. What went in
Two populations of product lines for one entity and one period — budget and actual — and one figure from the general ledger saying what gross profit actually moved by.
Budget
Actual
Ledger gross profit movement: −9,400.00 USD. That is the number somebody has to explain in a board pack on Thursday.
2. What the engine explains
Budget gross profit 70000.00 against actual 61600.00. The movement in the product records decomposes into four named drivers:
| Driver | Effect | How it was computed |
|---|---|---|
| Total volume | 4666.67 | change in total units x budget weighted unit margin |
| Product mix | -2666.67 | actual units vs budget mix at actual total volume, at budget unit margin |
| Net selling price | -3200.00 | actual quantity x (actual net price - budget net price) |
| Recognized unit cost | -7200.00 | negative of actual quantity x (actual unit cost - budget unit cost) |
| Explained by the records | -8400.00 |
The drivers sum to the product movement exactly — not nearly, not after a rounding
plug. There is no DECOMPOSITION_ROUNDING line here because the arithmetic is
exact decimal throughout, and a bridge that needed one would say so rather than absorbing it.
3. What it refuses to explain
The ledger moved by 9,400. The records account for 8400.00. The rest is the part most tools quietly assign to a driver called “other”.
| Line | Amount | Cause |
|---|---|---|
| Ledger movement | -9400.00 | |
| Supported by drivers | -8400.00 | Traced to product records |
| Unresolved | -1000.00 | None established |
Ledger movement exceeds what the product population explains. The difference is recorded as unresolved and requires controller review; no cause has been assigned to it.
In the product this becomes an UNEXPLAINED investigation with a null cause, a named owner, a list of the evidence that would settle it and a date it is expected by. A cause is written only by a person, and the schema requires their name and the time alongside it. The engine will not write one.
4. And it refuses invalid comparisons outright
Producing an answer is easy. Declining to produce one is the claim, so here is a real refusal: two periods of the same retail calendar, asked whether they can be compared.
| Period | Runs | Days |
|---|---|---|
| FY2026 P08 (4w) | 2026-08-02 to 2026-08-29 | 28 |
| FY2026 P09 (5w) | 2026-08-30 to 2026-10-03 | 35 |
A 25% swing in volume between those two periods is a calendar artifact, and a report that showed it with a footnote would be quoted without the footnote. So the comparison is refused rather than qualified. The same thing happens when a conversion rate is missing: it blocks, and it is never assumed to be 1.0.
What you are looking at
- Exact decimal arithmetic throughout. No binary floating point touches a financial number anywhere in this page or the engine behind it.
- Every driver carries how its figure is known — observed, calculated, inferred or assumed — and arithmetic never upgrades that.
- The decomposition cites the convention it used (
valcenra.margin.v1), which is versioned, so a run stored today still replays after the convention changes. - Nothing here posts a journal, moves money or approves anything. The engine is read-only against your ledger by design.