Hands-On Miniatures

Five designs from this program, built as running code and measured. Each page is a sequence of blocks — a block builds one mechanism, proves it works in isolation, and hands what it made to the next — followed by an assembly that wires them into one working thing.

Every number on every page came from executing the code. The generator runs each script and splices its stdout; nothing is transcribed. Regenerate and any number that drifted changes on the page.

And every claim is checkable. --verify re-derives each headline number from a second, independent implementation and asserts it — 58 claims across the five pages, all run in CI. A page cannot quietly stop being true.

Every block is also triggerable. Each carries a Try it yourself snippet that the generator executes at build time — importable, copy-pasteable, and impossible to leave broken, because a snippet that raises fails the build.

Table of Contents

Why These Exist

The design pages in Track C and Track D are prose: nine sections, a hostile critique, a revision. They are the right shape for rehearsing an interview, and they have one gap — you can read a design doc and retain nothing you could defend under a follow-up.

A hands-on page closes that gap by making the mechanism run. When an interviewer asks "how much does the fixed window actually let through at the boundary" or "what does a lease cost you when the holder pauses", the difference between a remembered claim and a measured one is audible.

These are not substitutes for the design pages. Work the design cold, then build the mechanism, then read the annotation. The gap between what you predicted and what the code printed is the finding.

The Five Pages

PageFromThe mechanism it buildsThe number to leave withClaims
C01 — Job dispatch and delivery semanticsd01at-most-once → at-least-once → dedup → the dual write → lease renewal1.99% lost or duplicated — the same crash window, paid on one side or the other9
C03 — Rate limitingd03fixed window → sliding log → token bucket → sliding counter → distribution → atomicityfixed window allows 2× at the boundary; the sliding counter's worst case is also 2×10
C05 — Load shedding and the utilisation kneed05the knee → bounded queue → the shed signal → FIFO vs LIFO → deadline drop → floorsp99 rises 8.7× from 50% to 95% utilisation; deadline-dropping is a 62× goodput win14
C11 — Distributed locking and fencingd11no-expiry deadlock → lease → the zombie → fencing tokens → TOCTOU → lease sizinga client-side token check leaks 1.2% at 1 ms and 72.5% at 1 s11
M02 — KV cache memory and paged attentionm02per-token cost → contiguous → paged → prefix sharing → fetch-vs-recompute → the preemption cliff320 KiB/token; paging is a 6× batch increase; break-even fetch is 9.3 GB/s14

Suggested order: C03 first (smallest surface, sharpest failure), then C11 (the highest-value single concept), then C05, C01, M02.

Where the Measurement Refuted the Prose

The reason these are worth reading rather than skimming is that several of them contradict something the first draft asserted, and the contradiction stayed on the page with the experiment that produced it.

PageWhat was claimedWhat the code showed
C03 B4the sliding window counter has "bounded error"its worst case tends to 2× — the same bound as the fixed window it exists to fix
C03 B4Cloudflare's "0.003% wrongly allowed" characterises ittrue only under the limit; at 1.0–1.5× offered load it is 15–23%. The published figure is measured in the regime where the limiter is not limiting
C05 B1the simulation validates M/M/1it does — to ρ=0.95. At ρ=0.99 it reads 520 ms against 1000 ms predicted, because relaxation time grows as \(1/(1-\rho)^2\) and 20,000 requests never reaches steady state. The real knee is sharper than the table shows
C11 assemblya client-side token check "removes most" duplicatesit removes 98.8% at a 1 ms check-to-write gap and 27.5% at 1 s. Its effectiveness is a function of a latency nobody measures
C01 B4a dedup window "still leaks" at 2,000it leaks exactly zero once the window reaches the maximum redelivery delay. The rule is sharper than the guess
M02 assemblypaged + sharing has low "waste"the metric was wrong — logical KV exceeds physical, so waste went negative. Sharing needs a ratio (held/logical 0.38×), not a waste percentage

Running Them

cd swe-interview-prep/handson

python3 c03_rate_limiter.py            # every block, then the assembly
python3 c03_rate_limiter.py --block 3  # one block and its prerequisites
python3 c03_rate_limiter.py --quiet    # the assembly only
python3 c03_rate_limiter.py --verify   # re-derive and assert every claim

python3 build_pages.py                 # regenerate every page from real output
python3 build_pages.py c11             # regenerate one
python3 test_handson.py                # 24 tests over all five pages

All five scripts are dependency-free standard-library Python, run in under a second each, and touch neither the network nor the filesystem. Fixed seeds throughout, so the pages are reproducible: if a number changes, the code changed.

Inline examples that cannot rot

Every block carries a Try it yourself snippet that the generator executes at build time, splicing in the real output. They are importable and copy-pasteable:

from c03_rate_limiter import parts
FixedWindow = parts()["FixedWindow"]      # every mechanism a page builds

A snippet that raises fails the build; one that prints nothing fails the tests. Writing them caught three errors in the surrounding prose — an example that claimed to straddle a window boundary and did not, a Little's-law queue cap compared against a p99 when the law gives a mean, and a block-table entry count off by 10×. All three are now stated correctly because the code ran.

What --verify is for

Captured output is reproducible but not necessarily right — a wrong measurement reproduces perfectly. So each script also carries a verify() that recomputes its headline numbers from a second implementation, independent of the blocks, and asserts them:

  [PASS] B4  sliding counter's worst case approaches 2x, like the fixed window  measured 1.99x at a 0.99s gap
  [PASS] B4  counter error is zero under the limit                              0.00% at 0.5x offered load
  [PASS] B4  ...and 15-25% at or above it                                       23.29% at 1.5x offered load

  10/10 claims verified

A block with a bug cannot make its own claim pass, and --verify exits non-zero on any failure — so test_handson.py runs all five in CI and the prose on these pages is checkable rather than merely assertable.

How a Page Is Built

handson/
  _harness.py            @block, run_all, check; --block N, --quiet, --verify
  build_pages.py         the generator; PAGES registry at the top
  test_handson.py        24 tests: scripts, claims, examples, annotations, freshness
  <name>.py              the script: N blocks + an assembly + verify()
  notes/<slug>.md        per-block annotation, split on '### B<n>'
  deep/<slug>.md         page-level deep dive, appended after the assembly
  <slug>.md              GENERATED — never hand-edit

Each page opens with Run it (the commands, the expected runtime) and Predict before you read (six numbers to guess first — the gap between your guess and the measurement is the point), and closes with Verify the claims (the captured --verify table).

Each rendered block is five parts: the claim (from the @block decorator), the problem (from notes/), the code (sliced from the .py), reading the implementation (from notes/), the captured output, and what the numbers say / beyond the toy (from notes/). A note may place <<<CODE>>> and <<<OUTPUT>>> to control the layout; whatever it omits is appended.

The bar for an annotation: a reader who already knows the mechanism should still learn something. If a paragraph could have been written without running the code, it does not belong.

Full build spec, conventions and the verification checklist: HANDOFF.md.

References