petralLEARNDesk ↗
CHAPTER 11OVERVIEW2 MIN READ

Data and provenance

Every number has a source, a lag and a reliability. Most tools show you none of the three.

WHY IT MATTERS

A number is only as useful as its source, age and method. Those details belong next to the value, not hidden in documentation.

A trading desk runs on published numbers, and almost every one of them is weaker than its presentation implies. An inventory figure is a survey. A production figure is an estimate. A physical differential is an assessment. A demand figure is a residual. None of that makes them useless; all of it changes what they can support.

The habit this hub is trying to build is asking three questions of every number before using it. Where did it come from, meaning which organisation produced it by what method. How old is it, meaning both the reference period and the publication lag. And how well observed is it, meaning whether it was settled, officially measured, estimated, or stood in for by something else.

Those three questions are why petral attaches a provenance record to every series it carries rather than presenting numbers bare. Each series arrives with its source, its retrieval mode, its reliability tier, the reference date, the fetch time, and any caveat or proxy note that applies. The badge under a chart is that record, rendered.

how a series resolves, in orderforce fixtures?yes: SAMPLE, nothing else attemptedcache fresh within source TTL?yes: CACHEDkey and network available?yes: LIVE, then write cachecache within default TTL?yes: CACHED, olderotherwiseSAMPLE, badgedEvery mode is badged. The badge covers a value; it cannot cover a claim about the world.
The resolution order, and what each mode admits.

The reason to enforce this in code rather than in documentation is that documentation does not stop anything. A proxy series in petral cannot be constructed without a proxy note, because the constructor raises if one is missing. A derived number cannot claim a reliability better than its worst input, because the combining function computes the floor rather than trusting the caller. Those are seams that hold; a convention in a style guide is a seam that decays.

The specific series a crude desk reads most are covered separately: the weekly inventory print, the positioning report, and the revision behaviour that makes a first print a draft rather than a fact. The mechanics of how a survey is actually built underlie all of them.

REVEIA RevisionsLIVE FROM THE DESKOpen on the desk
What a number said when it was published, against what it says now.
CHAPTER 11

IN THIS SECTION