From 70f5d39123794e451273b1d0596be61a6811297e Mon Sep 17 00:00:00 2001 From: zzstoatzz Date: Thu, 30 Jul 2026 07:40:18 -0500 Subject: [PATCH] docs: the homepage's headline numbers reset every 45 minutes Used product-copy-context.md as intended -- checked the live public page against its own rules while the experiment is mid-fill -- rather than only annotating it. The page honours the rules that matter: it says "Backfilling network history / Live subscriptions open when the archive catches up", reports "0 listening" honestly while serving is gated, and gives build provenance without promoting the implementation language. But "up" and "live events this run" are process-local, and the process restarts at every backfill batch boundary. At 55.6 h elapsed with 16,728,092,842 events archived, the homepage read: up 12m . 289,369 live events this run . 0 listening Both correct, both useless -- understating a two-and-a-half-day archive by ~275x because the last restart was 12 minutes earlier. A visitor cannot distinguish a permanently-young instance from a brand new one. Added the rule: durable values (archived event count, elapsed since the run began, complete repository count) belong on /, process-local figures on /status where the reader is looking at this process. Noted this is the HttpConnectionClosing batch-boundary defect surfacing publicly, but that the copy is worth fixing either way, since a durable counter is the right thing to show even once the process stops dying. Co-Authored-By: Claude Opus 5 (1M context) --- docs/product-copy-context.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/product-copy-context.md b/docs/product-copy-context.md index dbebe86..b183e50 100644 --- a/docs/product-copy-context.md +++ b/docs/product-copy-context.md @@ -48,6 +48,29 @@ make ephemeral consumers cheap without making the network absorb the rebuild. statements about the currently running build. - Runtime facts belong on /status; the / page should remain legible, welcoming, and honest about whether it is filling or serving. +- **Do not put process-local counters on a page that describes the run.** + "up N" and "N live events this run" are measured from process start, and the + process currently restarts at every backfill batch boundary. Checked on + experiment 6 at 55.6 h elapsed, with 16,728,092,842 events archived, the + homepage read: + + ``` + up 12m · 289,369 live events this run · 0 listening + ``` + + Both numbers were correct and both were useless: they understated a + two-and-a-half-day archive by roughly 275x, because the last restart was 12 + minutes earlier. A visitor cannot tell a permanently-young instance from a new + one. Prefer durable values — archived event count, elapsed since the run + began, `complete` repository count — and reserve process-local figures for + `/status`, where a reader is looking at *this process* rather than the + archive. `0 listening` is fine and honest: serving is gated until steady + state. + + This is the batch-boundary restart defect surfacing publicly rather than a + copy mistake (`gotchas.md`, `HttpConnectionClosing`). Worth fixing in the copy + regardless, since a durable counter is the right thing to show even once the + process stops dying. ## Presentation guardrails -- 2.51.2