Six provenance classes, and why your calculation tool needs them

Evgenii Buchinskii — Fri, 02 Oct 2026 05:25:59 +0000

Here is a bug report you will never receive, because nobody can see it:

The cable schedule says 120 mm². It was 95 mm² last quarter. Nothing in the project changed. Nobody knows which input moved.

Engineering calculation software is usually built to answer what is the result. Design review asks a different question: what would have to be wrong for this result to be wrong. A tool that stores only outputs cannot answer it, and no amount of UI polish compensates.

The fix is smaller than it sounds. It is one field on every input.

The field

Every decision-relevant input carries a provenance class — where the value came from, not what it is. Six classes cover an engineering calculation completely:

Class	Where the value came from	What goes wrong without it
Normative	A clause in a named standard edition	The edition changes and saved results silently become results under a superseded method
Manufacturer	A data sheet, catalogue or type-test report	Nobody can tell a measured value from a typical one, or find which revision it came from
Project	A decision recorded for this project	Site-specific limits look like physics and get copied to the next project
Assumption	Chosen because the real value was not available	The weakest number in the chain is indistinguishable from the strongest
User override	A library value a user replaced by hand	A default silently edited once propagates forever and is invisible on review
Derived	Computed from other inputs	A value that should have moved when its parent changed quietly did not

That is the whole model. Six strings, one per input. Not an ontology, not a graph database, not a semantic layer — the simplest thing that makes the right question answerable.

Why "normative" is not enough without the edition

The class that most often gets implemented wrong is the first one, because teams store the standard number and not the edition.

IEC 60909-0:2016 was replaced by IEC 60909-0:2026 in July 2026. A short-circuit result saved as "per IEC 60909" is now ambiguous in a way it was not the week before: there is no way to tell, from the saved record, which method produced it. A result saved as "per IEC 60909-0:2016, clause 6.2" is still perfectly reviewable — and, more usefully, a tool can flag it when the edition it cites stops being current.

That flag is the single highest-value feature in this whole idea, and it costs a string comparison.

Why "assumption" earns its place

Of the six, the one engineers push back on is assumption. The objection is that it looks bad — it marks your own work as uncertain.

That is exactly what it is for. In a thermal cable calculation, soil thermal resistivity is almost never measured; it is assumed. It is also, routinely, the parameter that moves the answer most. A result where the dominant input is class assumption is a different object from one where it is class manufacturer, and a reviewer who cannot see the difference is reviewing the arithmetic rather than the engineering.

Marking it does not weaken the result. It tells the reader where to push.

What this is not

It is not validation. Traceability tells you where every number came from; validation tells you whether the method is right. A fully traceable wrong equation is still wrong, and a validated black box is still unreviewable. You need both, and they are different work.

It is not an audit log. An audit log records who changed what when. Provenance records what kind of thing this value is, which is what a reviewer needs and what survives being exported to a PDF.

It is not a reason to build a data model. If adding provenance to your inputs requires a schema migration and a new service, you have over-designed it. It is a column.

The part that changes the output

Once inputs carry a class, the calculation report can say something a bare PASS never says:

Governing criterion: short-circuit thermal withstand.
Margin: 185 mm² installed against 154 mm² required.
Weakest input: k = 115 — class assumption, no source recorded.

A reviewer reads three lines and knows where to spend their hour. Compare that with a green tick.

And the reporting rule that follows is the one I would push hardest: never emit a bare PASS or FAIL. Always name the criterion that governed and the numerical margin to it. A PASS at 3 % reserve and a PASS at 40 % reserve are the same pixel and completely different engineering situations, and the tool is the only thing in the loop that knows which one it just produced.

If you implement one thing

Add the edition to every normative reference you store, and make the tool warn when a cited edition is superseded. Everything else on this list can wait; that one stops saved results from quietly decaying.

The full method — the six classes in detail, how dependencies and substitutions are recorded, how the governing constraint and margin are reported, and a worked multi-segment cable route — is in the technical report:

E. Buchinskii, "Clause-Traceable Engineering Calculations: a Method for Design Tools That Show Their Working," IECCalc.com Technical Report IECCalc-TR-2026-001, v1.0, Sep. 2026. doi: 10.5281/zenodo.23061123

Verification code: github.com/buchinskiievg/ieccalc-tr-validation (doi:10.5281/zenodo.23080081).

Disclosure: I wrote the report and I develop IECCalc.com, the free IEC calculator set where this method is implemented.