Skip to content

Architecture

One number.
One definition.

Every figure this system states has exactly one implementation in the codebase, and a check that fails the build when a second one appears. So when a screen, a report and an agent all show you the same number, it is the same number — not three that happen to agree today.


01/The failure mode

It is never one wrong number

A single bad figure gets found and fixed. What does the damage is five screens disagreeing.

Ask four systems what your AR aging is and you can get four answers. Each one is defensible: they disagree about what counts as a credit, when a dispute pauses the clock, whether an unapplied payment is netted. Nobody is wrong, exactly. Nobody can reconcile it either.

The cost is not the hour spent working out which figure to use. It is that the next figure from any of those systems now has to be checked too. Trust does not degrade one number at a time — it goes all at once, and the work moves into a spreadsheet, where the definition lives in one person’s head and leaves when they do.


02/Why one system

A stack cannot make this promise

Not because the vendors are careless — because the definition is split across companies, and no check spans them.

In a typical stack, “on hand” is defined inside one vendor’s product and “available to promise” inside another’s. Both are correct in their own terms. When one changes its definition, nothing in the other notices, and nothing in your build fails — there is no build that contains both. The integration layer moves numbers between them; it has no opinion about whether they mean the same thing.

Being one system is not a convenience argument here. It is what makes the guarantee possible to offer at all: a check can only fail a build it is part of.


03/The mechanism

One implementation, and a check that there is only one

A worked example: forward demand, the figure behind cash coverage, margin ranking, which suppliers get paid this week, and what production buys.

Forward demand is read through one path by every consumer of it — treasury coverage, margin ranking, the payment run, MRP and the constrained optimiser alike — so the org-grain predicate, the forward-source filter and the period window each exist exactly onceone loader, five consumers — the grain predicate, the source filter and the window are written once and read by all of them
Every read of the demand table must declare which grain it means, or the build fails — the check that stops a customer-level row and an org total being summed into one doubled figurea read that does not say which grain it means does not compile past the guard
Human-facing sequence numbers are minted in one place, and a new generator that counts rows instead of taking the maximum fails the buildthe same shape, applied to invoice and contract numbering

The pattern generalises past demand. Where a quantity matters enough that two implementations would diverge, it gets one implementation — and, where the ratchet has been written, a check that keeps it that way. There are 34 such checks running today. That list is deliberately shorter than the list of quantities we have converged: the convergence is the work, and the check is what makes it last.


04/Where it stops

A ratchet, not a proof

The honest version of this argument is narrower than the marketing version, and more useful.

Known exceptions are held in a baseline whose count can only fall: a new one fails the build, and a fixed one keeps failing until it is removed from the baselinenew finding fails; healed finding fails until the baseline entry is removed
A second implementation of the forecast figure fails the build, against a baseline whose count can only fallthe demand figure above, held by exactly this mechanism

It is a regression pin on the shapes that have occurred in this codebase, not a proof that no other shape can exist.

What it guarantees is narrower than prevention, and worth more. A duplicate cannot be introduced accidentally, because the canonical helper is the path of least resistance and the one already imported. It cannot be reverted silently, because the existing consumers are pinned by tests. And it cannot become the new normal without someone editing a baseline file inside a pull request, where a human sees it.

A genuinely novel shape is caught in review rather than by the scan. That is a weaker guarantee than a check, which is why it is not described as one.

The same precision applies one level up. The check that every guard runs in CI proves that a guard runs. It cannot prove the job is a required status check, because that lives in branch protection rather than in the repository — so it does not claim to.


05/This page

Including this page

The argument would not be worth much if the page making it were exempt.

Every capability this site claims resolves to an inventory entry with evidence a reviewer can open, and the build fails when that evidence no longer existsevery sentence on this site that states a capability
Every structural check in the guard chain runs on every pull request — a guard wired into the chain but not into CI fails the build rather than reporting green from a job nobody invokesa guard that gates nothing is itself a build failure

Every claim above is an entry in an inventory, and each entry names the file or route that proves it. Delete the code and this page stops building. That is the same mechanism the page describes, turned on the page itself.

The count in the previous section is not maintained either. It is computed from the same definition the build runs, so it cannot be a stale number on a page about stale numbers.

One further claim was drafted for this page and does not render. It holds figures from a live customer, which are theirs to release and not ours to publish while waiting. You are reading the page with it withheld — which is the only demonstration of this that means anything.

A second was withheld until this week. It described a check that had been written but not yet merged, so it was marked as not built and the component refused it; it renders in the previous section now that the check is on the main branch. That is the intended lifecycle, not an exception to it.


In practice

Bring the number you cannot reconcile.

The useful test is not a demo. Pick the figure your team argues about most — aging, coverage, on-hand, margin — and ask where it is defined, how many places compute it, and what would happen if someone wrote a second one. We will walk your engineers through the answer here, and hand them the files.