Serve stale entries, and say that they are stale

[iderex]

A cache that only ever returns fresh entries is a cache that is empty exactly
when it is needed, which is when the server is slow or gone. A cache that returns
stale entries without saying so makes every caller guess.

What this produces

Every read answering with the entry and its age, so a caller can decide.

A way for a caller to demand a fresh answer and to accept the failure that comes
with it, used by the paths where staleness is wrong.

The freshness rules from the contract in #6 applied per kind of entry rather than
globally, since a library list and a playback position go stale at very different
speeds.

What happens when the server says an entry has changed is #116 rather than this
issue, which holds only the age a reader is given and the freshness rules that
age is read against.

Done when

Every read returns the age alongside the value, a test proves a demand for
freshness fails rather than returning a stale entry when the server is
unreachable, and each kind of entry has its freshness rule stated in one table.
Blocked on #6, #40, and #102 for what an entry's age is measured against, so
that an entry cannot become permanently fresh because a clock moved between the
write and the read.

[iderex]

The clock this issue was waiting on is decided in docs/decisions/0102-the-clocks-every-deadline-is-measured-against.md.

An entry's age is on none of the three clocks by itself. It is anchored on the server's own stated time, because an age has to survive a restart of the process and both monotonic clocks reset at one.

An entry stores two moments when it is written, the server's stated time from the response and the device's wall reading at the same instant, and the difference between them is the skew at write, kept with the entry. Age at read is the device's wall reading now, minus the stored device moment, corrected by the difference between the skew now and the skew at write. A device clock that moved between the write and the read moved both readings and did not move the server's, so the correction removes the movement. Offline there is no current skew measurement, the correction is unavailable, and the age is the uncorrected difference.

Two guards fix the direction a wrong reading fails in, and they are what stops an entry becoming permanently fresh. An age that computes as negative is treated as past every threshold rather than as fresh, so a clock that moved backwards makes entries stale early. An age beyond a sanity bound is treated the same way. Both fail towards asking the server, which costs a round trip, rather than towards trusting a number the device produced, which costs somebody seeing content that is not there any more with nothing in the system that will ever correct it.

The thresholds themselves are not in that record and stay here. It fixes what the age is measured against and says so by name, and the freshness rule per kind of entry that the age is read against is this issue's.

[iderex]

The thresholds and what a stale read looks like landed as docs/decisions/0043-a-stale-answer-and-the-freshness-rule-per-kind.md, on cf9705d. The age those thresholds are read against is 0102's, which the comment above already settles, and the record names it rather than restating the mechanism.

The freshness rule is one table, one row per kind, matching the five kinds 0006 lists: library query results at five minutes, item metadata at an hour, capability answers for a server at a day, artwork bytes at thirty days, and decoded dimensions with their bytes. Each row carries the reason for its own number. None of the five is a measurement, and the record says so in the sentence above the table rather than in a footnote, with the harness in #65 named as where measured replacements would come from.

Two rules matter more than the numbers, and both would otherwise be decided by accident and in opposite directions.

A server may shorten a threshold and may never lengthen one. Where a response says it may be kept for less time than the table allows, that shorter time is used, because the server knows its own library is being written to and the core does not. Where it says longer, the table wins, because the server knows nothing about the device and the thresholds are about a person in front of a screen. The freshness statement on a response is the nearest thing to hand when the read path is written, so honouring it in both directions is what happens with nobody deciding that a server can make a device hold a library list for a week.

Age never withholds. There is no upper age at which the core refuses to serve an entry; an entry a month past its threshold is served, marked stale, with its age, and the client decides. What produces absent is eviction under #42 or invalidation, never age alone. The upper bound is the line that gets added the first time somebody sees a very old entry served, and it quietly stops the offline behaviour in #45 working for anybody away longer than that line allows.

Two smaller things the issue leaves implicit and the record fixes. An invalidated entry is absent rather than stale, because what is held is wrong rather than old and handing it back marked stale would let a client show it; age marks and invalidation removes, which is what keeps the three states at three. And a demand for freshness against a server that cannot be reached returns the transport's own kind from 0004 rather than a cache-specific failure, so no sixteenth kind is owed for it.

The queue of positions recorded while the server was gone is named as not being in the table. It is #47, it is a person's action rather than a copy of a server's answer, and nothing about it goes stale with age.

Of the three conditions here, one is met and two are untouched. Each kind of entry has its freshness rule stated in one table, which is this record. Every read returning the age alongside the value, and a test proving a demand for freshness fails rather than returning a stale entry when the server is unreachable, are statements about running code, and there is no language chosen, no build and no test command in this tree to assert them against. This stays open on both.