Staleness Is Something You Display

"Stale data is shown as stale, never hidden and never extrapolated."

Four things you can do with an old number

A source has not updated. The gauge on the dashboard has a value from three days ago. There are exactly four options, and three of them are worse than the boring one.

Hide the card. Feels tidy, destroys information. "Three days old" and "we have nothing" are wildly different states, and collapsing them means the reader cannot tell a quiet weekend from a broken integration. It also inverts the failure: the more broken things get, the emptier and calmer the dashboard looks.

Extrapolate. Fills the gap with a plausible number. This is the worst option available, because the result is indistinguishable from a measurement and there is no honest source string to attach to it. In an app whose core promise is provenance on every stored value, a made-up number is not a small compromise — it is a contradiction of the product.

Silently swap providers. Now the value is real, but the source string is a lie, and the two providers almost certainly disagree slightly in method. A series that quietly changes its source mid-history is worse than a gap, because the resulting discontinuity looks like a market event.

Show the last-good value with its date and a staleness indicator. Boring, honest, and the only option that leaves the reader in possession of what is actually known.

An honest gap beats a plausible number. When a system cannot know something, the highest-value thing it can do is say so precisely — what it has, when it was from, and why there is nothing newer. Every alternative trades a small amount of visual tidiness for the reader's ability to tell measurement from guess, and that trade is never worth it in a system whose whole claim is measurement.

Staleness is not always failure

Here is what makes this design more than error handling: in this product, most staleness is correct.

The Buffett gauge's US numerator comes from a quarterly statistical release, so it is legitimately months old and the architecture says to show the release lag as staleness rather than hide it. Two of the three long-term yield series are monthly. The Korean and Japanese Buffett readings are annual — one row a year, and the live surface labels them annual so that a yearly number never dresses up as a daily tick.

If the interface treated age as an error state, it would be permanently alarmed about data that is arriving exactly on schedule. The chip does not say broken. It says this is from then, and lets a reader who knows the release calendar draw the right conclusion.

The one that bites: mixed as-of. The real trap is not one stale value, it is several values of different ages rendered as one coherent picture. A composite built from a daily reading and a quarterly one is only as current as its oldest leg — and if the surface prints a single as-of date, it is asserting a simultaneity that does not exist. That is why the composite in this product names its oldest input explicitly, and it is the subject of a later track.

Code

Every stored value carries its own provenance·text

ROW SHAPE:  (gauge, market, series, data_date, value,
             source, fetched_at)

  data_date   the date the MARKET says this reading belongs to
  fetched_at  when this process asked
  source      exactly which provider and series produced it

# data_date and fetched_at are different questions, and keeping both
# is what makes staleness computable rather than guessed:
#
#   data_date 2026-08-05, fetched_at 2026-08-08
#     -> 3 days stale, and we know we asked today
#
#   data_date 2026-08-05, fetched_at 2026-08-05
#     -> we have not asked since; a very different problem
#
# One timestamp cannot tell those apart. Most systems store one.

Exercise

Find a value in a system you maintain that comes from an external source, and check whether you store both when the data is from and when you last asked. If you store only one, work out which failures you currently cannot distinguish. The usual answer is that a dead integration and a quiet source look identical, which means nobody notices the dead one until someone asks a question about a number.

Hint

Two timestamps, always: the subject's time and your time. Almost every 'why is this number old?' investigation is really the question 'did we stop asking, or did they stop publishing?' — and one timestamp cannot answer it.

Four things you can do with an old number

Staleness is not always failure

Code

External links

Exercise

Progress

Comments 0