# cld-toys Small (~100-200 LOC) Python implementations of one core mechanism from a piece of infrastructure or systems software. The goal of each toy is a working mental model of *how the thing works under the hood*, not a usable reimplementation of the real system. ## Ground rules - Each toy lives in its own top-level directory, is self-contained, and does not depend on any other toy in this repo. - Target 100-200 lines for the core implementation (a `demo.py` / tests can go over that budget — they're not part of the "understand this" budget). - Every toy has exactly one document: its **commentary**. No per-toy `README.md` — one mechanism, one explanation, one place to keep current. See "The commentary" below for the template. - No shared framework or utils package across toys — duplication across toys is fine and preferred to coupling them together. (This rule is about the Python. The commentary pages do share `assets/`, which is presentation, not implementation.) See [BACKLOG.md](BACKLOG.md) for the list of toys to build, one mechanism each. ## The commentary Each toy carries a `commentary.md` (source of truth) and a rendered `commentary.html` companion, both living **beside the toy's source** so the page can link straight at the code it discusses. It is the toy's only documentation, so it opens with how to run the thing. The model is Lion's *Commentary on UNIX* — but concept-level, not line-by-line. Ten sections, in order: 1. **Orientation** — the commands that run the toy and its demo, what the toy is, and a short list of what you'll be able to do by the end. 2. **The problem this mechanism exists to solve** — why real systems have this at all. Name the competing goals that make more than one design defensible. 3. **Background you need** — a table of concepts: one line each saying *where in the toy* it's used, plus one link. Flag the one or two that carry the result. 4. **The mental model** — an ASCII `.diagram` of the idea, before any code. 5. **Reading the source** — annotated excerpts in reading order. Each is captioned with its `file:line` provenance and followed by commentary on *why* it's written that way, not what it says. 6. **The demo, and what it proves** — the real captured transcript, then the result derived arithmetically. Finish with the boundary condition: where the effect *vanishes*, so a reader can place their own system. 7. **Design decisions and roads not taken** — the alternatives, and why they lost. 8. **What's simplified vs. the real thing** — the corners cut to hit the LOC budget, and what the real system does instead. Each one is a map of a production concern: concurrency, sharding per client, shared state across processes. 9. **Check yourself** — questions with answers behind `
`. Each answer must be derivable from the source. 10. **Further reading** — annotated. Every URL fetched and confirmed live before it ships. **The rules that make it worth reading:** - **Never state a claim you haven't run.** Every transcript, number, and counterfactual ("change this character and the result flips") comes from a real execution against the real toy. Declare the environment at the top of the page. A plausible invented output is the worst possible outcome, because it destroys the reader's ability to check themselves. - **Never leave a headline number underived.** If the page says "it denies the fifth," show the arithmetic that produces four. - **Commentary, not narration.** Restating the code in prose adds nothing. Explain the decision behind the line. ### Rendering the HTML - Assets are one level up: `../assets/style.css`, and `` at the end of ``. - **Syntax highlighting is hand-written.** `copy.js` only injects copy buttons. Mark up Python by hand with the existing `.kw` `.fn` `.str` `.cmt` `.num` `.op` spans, and escape `<` `>` `&`. - Source excerpts use `
…
…
` so an excerpt can't drift from its provenance. - Transcripts you *read* go in `
` and are left un-highlighted on purpose; commands you *type* go in plain `
`, which is what gets the copy button.
- Page chrome is `.page-title` / `.page-subtitle` / `.page-meta` /
  `.page-footer`, with a `.toc` after the intro callout.
- Finally, **add an `.index-card` for the toy to [`index.html`](index.html)**
  and move its backlog entry into the "Available now" section.

## Built so far

- [`wal-kv/`](wal-kv/) — a key-value store with a write-ahead log; `kill -9`
  turns out to be unable to fail as a durability test.
  ([commentary](wal-kv/commentary.md) ·
  [rendered](wal-kv/commentary.html))
- [`rate-limiter/`](rate-limiter/) — token bucket vs. sliding window log,
  side by side; the same request trace makes the two diverge twice.
  ([commentary](rate-limiter/commentary.md) ·
  [rendered](rate-limiter/commentary.html))
Browse them at [`index.html`](index.html). [BACKLOG.md](BACKLOG.md) carries
the full checklist of what's built and what's left.

## What used to live here

This repo also held a second track: **guided exercises** — hands-on labs run
against real, full-strength systems (Postgres, Docker) rather than
reimplementations of them. Those moved to their own repo, `~/study`, in July
2026, where they sit alongside book-driven exercises and share one format
spec. This repo is toys only.