petralLEARNDesk ↗
CHAPTER 11LESSON 042 MIN READ

Live, cached, sample

Where a number on screen actually came from, this second.

WHY IT MATTERS

A live observation, a recent cached value and a sample are different kinds of evidence. Their labels should travel with every derived number.

A number rendered on a dashboard came from somewhere, and 'the API' is not a sufficient answer. It may have been fetched from the source just now, served from a cache written some time ago, or generated as sample data because no source was reachable. Those are three different epistemic situations and a tool that presents them identically is misleading by omission.

petral names them explicitly. LIVE means the value was fetched from the upstream source on this request. CACHED means it came from a stored copy, with the age of that copy reported. SAMPLE means it was generated deterministically as fixture data, because no key or no network was available.

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 the conditions under which each mode is reached.

The resolution order is fixed and worth knowing because it explains what you are looking at. If fixtures are forced, fixtures are used and nothing else is attempted. Otherwise a cached value within the source's own freshness window is used. Failing that, a live fetch is attempted and its result is written to the cache. Failing that, a cached value within a longer default window is used. Failing all of it, a fixture is served and badged.

The SAMPLE mode is the one that requires the most care, and the reason is that a fixture is a plausible-looking number. It has to be, or the interface would be untestable. So the honesty burden falls entirely on the badge, and the badge has to be present on every series without exception, including derived ones.