Build a rate limiter that keeps its promise under pressure

A rate limiter looks small until callers arrive at the same instant. In this demo you will build a token bucket with a deterministic clock, then prove that it never grants more tokens than its capacity during a concurrent burst.

Before writing code, use SCOAT:

• Stable role: one atomic allow() decision.
• Change: capacity, refill rate and clock vary while the token invariant remains.
• Ownership: the bucket owns its token state and lock; the caller supplies the clock.
• Abstraction need: keep the boundary as small as the pressure requires.
• Topology: lock, refill, decide and consume as one state transition.

Open the challenge when you are ready. The workspace contains the learner files and real executable checks; the reference implementation stays out of the public workspace. A later hint can reveal the complete solution after you have tried the design.