Past 60 s, home still answers from the last KPI answer while one refresh runs off the request path #7952

Once home's KPI, panel or vitals answer is more than 60 s old, home still serves it straight away and refreshes it after the response, so the request no longer pays for the recompute. Only a cold start, where there is no answer yet, still computes during the request.

• src/kernel/stamped.ts: adds peek(key), which returns a stored entry however old and counts nothing, and put(key, stamp, value), which stores a value timed from now. get now stores through the same private store, so its behaviour is unchanged.
• src/web/studio/home_cache.ts: a new servedStale sits behind cachedKpis, cachedPanel and cachedVitals:

- With no entry, or one under 60 s old, it calls get as before. - An older entry is returned as is and counted as a hit, so Server-Timing marks the kpis phase desc="hit". - It schedules one refresh with setTimeout(0); while that refresh is pending, no second one is scheduled for the same key. - The refresh runs in try/catch/finally: if it throws, the old answer stays and the key is freed for the next request to try again. - A refresh adds to neither the hit nor the miss count, so it can't flip an unrelated request's phase to a miss. - The KPI refresh is given no Server-Timing timer, because the request that triggered it has already answered. - The builders figure is still read fresh on every request, stale or not.

• test/home-cache-ttl.test.ts: two existing tests expected the old behaviour, an inline recompute at 61 s. The issue changes that, so they now check that the old value comes back at 61 s and the new one after the tick. New tests cover:

- Past 60 s the old value comes back without calling compute. - After the tick the next call returns the new value. - Two stale calls in a row schedule one refresh. - A refresh that throws keeps the old value and frees the key. - Only a cold start computes inline. - The kpis phase is a hit under 50 ms both warm and stale.

afterEach now waits one tick so a refresh scheduled in one test doesn't run inside the next.

• test/stamped.test.ts: covers peek and put.
• docs/CACHING.md: the 60 s paragraph now describes serving stale and refreshing after.

I left the waiting line alone: it stays on the write stamp so the asks count is exact. There is no upper limit on how old a served answer can get: if every refresh fails, the last good answer keeps being served until the cache evicts it. The KPI key also changes on the hour, so that one starts cold each hour anyway.

To try it: bun test test/home-cache-ttl.test.ts test/stamped.test.ts. I ran bun scripts/gate.ts, bun x tsc --noEmit and bun scripts/design-lint.ts, all clean. scripts/fast.ts could not narrow the change because it touches the kernel, so I ran the 64 test files that reference home_cache, Stamped, explore, map snapshots, alarm lines and the KPI row: 702 passed, 0 failed.

🤖 Generated with Claude Code

Closes #7625

Once home's KPI, panel or vitals answer is more than 60 s old, home still serves it straight away and refreshes it after the response, so the request no longer pays for the recompute. Only a cold start, where there is no answer yet, still computes during the request.

• src/kernel/stamped.ts: adds peek(key), which returns a stored entry however old and counts nothing, and put(key, stamp, value), which stores a value timed from now. get now stores through the same private store, so its behaviour is unchanged.
• src/web/studio/home_cache.ts: a new servedStale sits behind cachedKpis, cachedPanel and cachedVitals:

- With no entry, or one under 60 s old, it calls get as before. - An older entry is returned as is and counted as a hit, so Server-Timing marks the kpis phase desc="hit". - It schedules one refresh with setTimeout(0); while that refresh is pending, no second one is scheduled for the same key. - The refresh runs in try/catch/finally: if it throws, the old answer stays and the key is freed for the next request to try again. - A refresh adds to neither the hit nor the miss count, so it can't flip an unrelated request's phase to a miss. - The KPI refresh is given no Server-Timing timer, because the request that triggered it has already answered. - The builders figure is still read fresh on every request, stale or not.

• test/home-cache-ttl.test.ts: two existing tests expected the old behaviour, an inline recompute at 61 s. The issue changes that, so they now check that the old value comes back at 61 s and the new one after the tick. New tests cover:

- Past 60 s the old value comes back without calling compute. - After the tick the next call returns the new value. - Two stale calls in a row schedule one refresh. - A refresh that throws keeps the old value and frees the key. - Only a cold start computes inline. - The kpis phase is a hit under 50 ms both warm and stale.

afterEach now waits one tick so a refresh scheduled in one test doesn't run inside the next.

• test/stamped.test.ts: covers peek and put.
• docs/CACHING.md: the 60 s paragraph now describes serving stale and refreshing after.

I left the waiting line alone: it stays on the write stamp so the asks count is exact. There is no upper limit on how old a served answer can get: if every refresh fails, the last good answer keeps being served until the cache evicts it. The KPI key also changes on the hour, so that one starts cold each hour anyway.

To try it: bun test test/home-cache-ttl.test.ts test/stamped.test.ts. I ran bun scripts/gate.ts, bun x tsc --noEmit and bun scripts/design-lint.ts, all clean. scripts/fast.ts could not narrow the change because it touches the kernel, so I ran the 64 test files that reference home_cache, Stamped, explore, map snapshots, alarm lines and the KPI row: 702 passed, 0 failed.

🤖 Generated with Claude Code

I found and fixed what was blocking the pull. A type error in test/home-cache-ttl.test.ts stopped bun x tsc --noEmit, which the check runs. One test in that run also failed once and then passed eight times, so the pushed branch has no clean full run behind it.

The preview itself was up: /healthz answers 200, and "no tests declared" is a deploy setting this branch doesn't touch.

The type fix is one line. Under exactOptionalPropertyTypes, the timing test's helper type { hit?: boolean } doesn't accept the possibly-undefined hit it is given. It is now { hit: boolean | undefined }. No behaviour or assertion changed.

To bring the branch up to date I merged main into the pull's existing tip; I didn't rebase, because force pushes are refused. Gate and type check pass.

The one failure. I ran the tests that cover the change: test/home-cache-ttl.test.ts, test/home-cache.test.ts, test/stamped.test.ts, test/observability-budget.test.ts, test/write-clock-quiet.test.ts, test/home-timing.test.ts and test/home-200.test.ts. The first run reported 47 of 48 passing. My command piped the output through tail, which hid the exit code, so the commit and push went ahead anyway. The output was cut off, so I don't know which test failed. The next eight runs of the same files all passed. That points to a timing test failing under load, but I can't rule out a real fault. If the forge's check comes back red, its log will name the test.

bun scripts/fast.ts couldn't name the tests (exit 2: src/kernel/stamped.ts changed, so the diff is too broad). Instead I ran every test file that imports stamped or home_cache, plus the explore, map snapshot, feed items and alarm tests for the other modules that use stamped. Those 56 passed.

The rest of the pull is as described before: past 60 s, home serves its last KPI, panel and vitals answer straight away and runs one refresh per key with setTimeout(0). A refresh that throws keeps the old answer and frees the key. Only a cold start computes inline.

To try it, open / on the preview, wait past 60 s and reload: the kpis phase in Server-Timing reads desc="hit" while the refresh happens after the response.

🤖 Generated with Claude Code

Closes #7625, which is part of #7494. That issue's purpose is home latency, which justifies a change outside the pipeline list. Past 60 s, home serves its last KPI, panel and vitals answer at once and refreshes it after the response, so an admin's home no longer pays for a full KPI recompute once a minute.

What moved where

• src/kernel/stamped.ts: adds peek(key), which returns a stored entry however old and counts nothing, and put(key, stamp, value), which stores a value timed from now. get behaves as before.
• src/web/studio/home_cache.ts: a new servedStale sits behind cachedKpis, cachedPanel and cachedVitals:

- With no entry, an entry under 60 s old, or one past HOME_STALE_CEILING_MS (10 × HOME_TTL_MS, 10 min), it calls get and computes inline. - Otherwise it returns the old answer, counted as a hit, and schedules one refresh per key with setTimeout(0). - A refresh that throws logs home.refresh_failed at warn, keeps the old answer and frees the key. The ceiling means refreshes that keep failing can't pin an answer forever. - A comment says why the KPI refresh reads at the triggering request's now: the key holds that UTC hour, so the refresh lands the answer the key names.

• docs/CACHING.md: describes the stale window, the ceiling and the log line. It also says plainly that the refresh is off the request but not off the event loop: it runs on the same thread, so a request that arrives during a refresh waits for it, just as it would have waited for an inline recompute.

Tests (test/home-cache-ttl.test.ts)

• Two existing tests expected an inline recompute at 61 s. The issue changes that behaviour, so they now check that the old value comes back at 61 s and the new one after the tick.
• New tests cover:

- Past 60 s the old value comes back without calling compute. - After the tick, the next call returns the new value. - Two stale calls in a row schedule one refresh. - A refresh that throws keeps the old value, frees the key and is logged. - Only a cold start computes inline. - The ceiling: at 10 min less 1 ms the old answer comes back; at 10 min it is computed inline.

• The Server-Timing test no longer patches app.db.query by hand. It passes a counting KpiTimer to cachedKpis and checks that a warm or stale kpis phase is a hit that runs exactly ["kpis.builders"]. The refresh gets no timer, so it adds nothing to that count, and nothing else in the process can.

The earlier one-off failure. Its output was cut off, so I can't name the test. It didn't come back in 18 later runs of the same seven files, including 10 with a type check running alongside. The likeliest culprit is test/observability-budget.test.ts: it is the only test in that set that judges wall-clock time (res.ms < 30 * unit), and the failing run shared the machine with tsc. That ratio budget comes from main (#3069) and doesn't touch this change, so I left it alone rather than rewrite a production-size budget in this pull.

Checks. Gate, bun x tsc --noEmit, bun scripts/design-lint.ts, and the seven files above pass (50 tests). I also ran the tests for the other modules that use Stamped (explore, map snapshot, feed items, alarm lines): 56 pass. bun scripts/fast.ts exits 2 because src/kernel/stamped.ts changed, so I chose those files by hand.

To try it: sign in as an admin on the preview, load /, wait past 60 s and reload. Server-Timing marks kpis as desc="hit", and the next reload shows the refreshed figures.

🤖 Generated with Claude Code