Section 10: The Number That Tells the Truth - Approximate Counts & Honest Display

Executive Summary: This section delivers on the promise Section 2 wrote into the requirements: counts are exact at rest, approximate in motion. We turn display rounding into an engineering spec rather than a UI whim, replace the consistency guarantee nobody can afford with a convergence SLO someone can actually measure, and meet the quiet hero of the whole design — the nightly reconciliation job that recomputes every touched counter from the ledger and makes "the ledger is the source of truth" an operational fact instead of a slogan. We close by dismantling the most seductive pushback in the room: "why not just make the pipeline exactly-once?"

Priya's phone has said "42.3K" for the entire subway ride. Underneath that calm little string, @astra's post has absorbed hundreds of thousands of likes, a buffered aggregator has flushed ~5,000-like batches ten times a second, and Priya's own like, retry, unlike, and re-like have all landed in the ledger. The display never flinched. A weak candidate treats that as a cop-out — "we round because we can't keep up." A Staff candidate argues the opposite: "42.3K" is the honest answer, and 42,318 would be a lie.

Here's why. The hot-post pipeline Section 7 built has a flush window of 100ms, a cache in front of it, and increments landing from thousands of clients at once. At any instant, the live counter is within roughly 0.1% of the ledger truth — close, converging, but in motion. Rendering 42,318 advertises per-unit precision the pipeline does not possess at that instant; rendering "42.3K" states exactly the precision it does. The rounded number isn't hiding error. It's disclosing the error bar.

Key Insight: Precision is a claim, and your display makes it whether you meant to or not. Showing more digits than your pipeline can defend is the numeric equivalent of a progress bar that jumps backward — users read it as breakage. Round to what you can guarantee, and the system looks as correct as it is.

Display Rules as a Spec

"Round big numbers" is a vibe. A spec is testable, and this one took a product conversation plus one accuracy-tolerance requirement (Section 2) to write:

Two supporting rules complete the spec:

• Jitter suppression: never animate a downward correction smaller than 1%. Corrections happen — a flush lands out of order, reconciliation trims bot likes (Section 9) — but a number that visibly ticks down by a hair reads as a glitch, while "8.2M" quietly absorbing a 40K correction reads as nothing at all. Large corrections (the 400K bot purge from Section 9) are allowed to show; small ones are noise and get smoothed.
• The viewer's own edge is exempt: the count+1 display merge from Section 8 still applies. Priya's like is reflected in her rendering instantly, whatever the rounding bucket.

Quick check before moving on: