Freshness is a state, not a timestamp
Most systems that touch external facts record one thing: when they last looked.
last_updated: 2026-09-01. That field answers a narrow question — when was this
captured — and gets silently asked to answer a much bigger one: is this still true. Those
are different questions. Conflating them is a specific, recurring source of bugs in systems
that act on external state, agents included.
What a timestamp actually tells you
A capture timestamp is a fact about the past. It says a process ran on a given date and recorded a value. It says nothing about the process that produced the underlying fact — how often the source changes, whether anyone has checked since, or what the source says right now. Treating "last updated: 3 days ago" as "probably still accurate" is a guess wearing a timestamp's clothing. Sometimes that guess is fine. For a fact a decision or an audit later depends on, "probably" is not a basis — it's an assumption nobody wrote down.
Two questions, kept separate
AIality's exact-state model splits this deliberately into two calls that return two different kinds of answer, because the server's own contract makes the same split (see Exact States and Freshness):
- The exact state — an immutable
FactStateVersion. Once written, it never changes. Fetching it twice for the same id returns byte-identical results, forever. This answers "what did we determine, and when." - Freshness — a live verdict, evaluated at read time:
FRESH,STALE, orUNKNOWN. Calling it again later can return something different for the exact same state id, because "is this still current" is a question about now, not about the record. This answers "should you still rely on this without rechecking."
A single "last updated" field tries to answer both at once and ends up answering neither precisely. Splitting them means an agent — or a person — can ask the second question without disturbing the first, and can reconstruct exactly what was known at decision time without it silently drifting as the world moves on.
Why the horizon is frozen, not recomputed
The freshness horizon (fresh_until) is set once, at the moment a state is
created, from whatever revalidation policy is in force at that time — and then frozen.
It is not retroactively recomputed when the policy later changes. This is a deliberate
invariant, not an oversight: if an old state's staleness were reinterpreted under a policy
that didn't exist when it was written, "what did we know, and how confident were we"
would stop being an answerable question about the past. A policy change only ever affects
states created after it — old provenance keeps resolving exactly as it always did.
What this means in practice
For an agent, the practical consequence is small and concrete: don't collapse "I have a record" and "the record still holds" into one check. Resolve the exact state, check its freshness separately, and if a decision or an action needs to be defensible later, bind both together explicitly — that's what a Reality Lock is for: a durable record of exactly which exact states a decision used, assessable afterward for whether that basis has since drifted. Not a claim that the world stood still. A record of what was actually relied on, and a way to check later whether it still is.