Section 2: The Contract Behind One Run - Requirements (Functional & Non-Functional)

Executive Summary: This section turns Section 1's answers into a contract you can test. We number eight functional requirements so later sections can point back at them, walk Kai's run through every one, and draw the out-of-scope line with a reason for each exclusion, including why a matchmaking rating is a different problem from a leaderboard. Then we set the non-functional dials per path, not for "the leaderboard": one write path and three read paths, each with its own latency target. We spell out the consistency model as promises about who sees what and when, and we defend the two numbers interviewers push on: only 99.9% for reads, and a tighter 99.95% for accepting runs.

The clarifications are done, and the interviewer caps the marker: "Good. So what exactly are we committing to?" The weak answer is one sentence: "players see their rank, it updates in real time, it scales." Nobody can test that sentence, and it hides everything Section 1 uncovered. A best score is a max, ties need a rule, and a board with weekly prizes invites cheating. So every requirement below is something a test could check, and every number is one an on-call engineer could be paged on.

The Functional Contract

Strip the prompt to its verbs and you get eight requirements. Numbering them isn't bureaucracy. It lets Section 4's endpoints and Section 5's keys trace back to a promise.

Now walk Kai through it, because the table earns its keep only if a real run exercises it. On Wednesday 2026-10-28 at 21:14 UTC, Kai finishes run r-7f3a91 in Manila with 1,284,500 (FR1). Kai's previous best this week was 1,201,000, so the weekly board moves them from rank 412,907 to 88,416 and says improved: true. On the all-time board, nothing changes. Kai's best stays 1,350,200 at rank 1,042,311, and the response says so rather than staying silent (FR6). The post-run screen shows NovaBlitz on top with 9,812,000 (FR2), the ten players bracketing rank 88,416 (FR3), and Kai in 3rd place of 41 among their friends (FR4).

FR6's tie rule is a requirement, not an implementation detail. ember_fox and quietstorm both reach 2,500,000 this week, ember_fox on Tuesday at 18:02 UTC and quietstorm on Wednesday at 09:40 UTC, so ember_fox ranks higher. Without a written rule, the order of those two would fall out of whatever the storage engine happens to do, and at rank 10,000 that can be the difference between a reward and no reward.

Key Insight: FR1 returns ranks in the submit response, and that single choice is the read-your-writes guarantee. The one person who'll notice a stale rank is the player who just finished a run. Hand them their rank from the write itself and every other read can come from a replica a second or two behind, which is what makes Section 3's read numbers affordable.

FR8 is in the functional table on purpose. zzz_speed's 9,999,999 from a 41-second run blows far past the plausibility bound (Section 1 does the arithmetic), so the run is rejected outright. A subtler cheater who passes the bound but lands in the top 1,000 gets a provisional status on that board. They see their entry; nobody else does until replay validation clears it within 15 minutes. A leaderboard with prizes is an incentive. If integrity isn't a requirement, it never gets designed in.

Quick check before moving on: