Hi👋SpeedSystem: the engineering mystery curriculum
A checkout accepted two buyers for one seat. Fixing that race reveals another: an acknowledged write disappears after a crash. Protecting it makes writes slow; batching them fills the disk with compaction work. Each improvement creates the next engineering question.
These are explicitly hypothetical incidents, not reports about named companies. Start with the problem at the top of each lesson. Write a prediction before opening its Answer callout. Implement or trace the mechanism, then defend a choice under the final changed constraint.
Entry knowledge and navigation
You should be able to read a short SQL transaction, a loop, a hash map, and an HTTP exchange. No prior knowledge of consensus, storage engines, streaming watermarks, or distributed locks is assumed. A prerequisite means the lesson uses that mechanism; the numbered sequence is a valid topological ordering. Follow the links to skip material you can already explain through a failure trace.
The main path is lessons 01–26. Lessons 27–37 apply it to identity, networking, discovery, and abuse resistance. All are part of the collection; the application paths can be taken independently once their listed prerequisites are met. A lesson is complete when you can explain its invariant, demonstrate a counterexample to the first attempt, and solve the transfer challenge.
The learning sequence
| Lesson | Mystery | Prerequisites |
|---|---|---|
| 01 · Two successful transactions, one impossible result | Two buyers both reserve the last seat. | Entry knowledge |
| 02 · The write that survived the process but not the machine | A successful write disappears after power loss. | 01 |
| 03 · The file exists, but recovery must ignore it | A crash leaves an SSTable outside the durable manifest. | 02 |
| 04 · Fast writes, then a completely frozen database | Background merging cannot keep up with foreground writes. | 03 |
| 05 · Can we prove the key is absent without reading it? | Negative lookups spend most of the disk budget. | 04 |
| 06 · The client gave up; the server kept working | Retries multiply work whose outcomes remain unknown. | 01 |
| 07 · An optional widget exhausts the checkout pool | A slow dependency consumes resources needed by healthy routes. | 06 |
| 08 · The limiter that allows twice its advertised limit | A window boundary permits an unexpected burst. | 01 |
| 09 · Twenty correct limiters enforce the wrong limit | Local enforcement multiplies a tenant budget by fleet size. | 08, 07 |
| 10 · Deleting the cache resurrected the old price | A slow refill races a committed update. | 01, 06 |
| 11 · The database cannot survive a successful cache | A cold cache turns nearly every request into origin work. | 10, 07, 05 |
| 12 · Adding a server moved almost everything | Modulo routing remaps data during expansion. | 01 |
| 13 · The cluster is idle and one customer is throttled | One logical key exceeds the capacity of its owner. | 12, 07, 11 |
| 14 · The database acknowledged a write the replica cannot read | Durable, committed, and applied positions differ. | 02 |
| 15 · Two machines both say they are the leader | An isolated former leader continues to receive requests. | 14 |
| 16 · The lease expired; the old worker did not | A paused worker resumes after a replacement takes ownership. | 15, 01 |
| 17 · The copy finished, then the old owner accepted a write | A live migration races stale routers and ongoing writes. | 12, 13, 14, 16 |
| 18 · The payment succeeded twice after one timeout | An ambiguous external effect is retried as a new operation. | 01, 06 |
| 19 · The queue is healthy; the customer is still waiting | Redelivery, poison records, and early acknowledgement break progress. | 18, 07, 16 |
| 20 · The order committed, but nobody heard about it | A database commit and a publish cannot be made atomic by ordering calls. | 18, 19, 03 |
| 21 · Yesterday changed after the stream restarted | Late events and replay make a plausible counter incorrect. | 19, 20, 16, 04 |
| 22 · The dashboard recovered by hiding the incident | A roll-up discards the information needed to answer the question. | 21, 04 |
| 23 · All participants voted yes; no participant can finish | Prepared transactions wait for a durable global decision. | 01, 15 |
| 24 · The refund failed after the booking failed | Independent commits require recoverable semantic compensation. | 18, 20, 23, 16 |
| 25 · Traffic failed over before authority did | Routing users to a standby does not make it a safe writer. | 14, 15, 16, 18, 07 |
| 26 · The current balance cannot explain its own history | A new query needs a replayable model without duplicating effects. | 18, 20 |
| 27 · The unique ID generator repeated itself after restart | Clock rollback and worker reuse violate assumed uniqueness. | 16 |
| 28 · The failure detector removed a healthy machine | A missing heartbeat cannot distinguish failure from delay. | 15 |
| 29 · More connections did not fix the slow page | Transport, proxy, and dependency queues create different bottlenecks. | 06, 07 |
| 30 · The socket reconnected; the messages did not | A live transport supplies neither history nor replay correctness. | 19, 29 |
| 31 · The token is genuine and the request is forbidden | Authentication, authorization, and revocation have different boundaries. | 05, 06, 20, 29 |
| 32 · Autocomplete found the prefix and still timed out | Finding a prefix does not find its best completions. | 04, 20 |
| 33 · The closest driver is invisible to the index | Spatial cells omit nearby points unless coverage is complete. | 12 |
| 34 · The vector index returns ten excellent unauthorized matches | Approximate retrieval and access filters interact. | 31, 32 |
| 35 · Every account obeyed the limit; the attack still worked | Many cheap identities evade per-identity controls. | 09, 31 |
| 36 · The browser passed the challenge twice | A challenge token is accepted without a correct server-side lifecycle. | 35, 18, 07 |
| 37 · The puzzle was hard once and free thereafter | A reusable proof makes client work irrelevant to repeated abuse. | 35, 18 |
Dependency map
This is a view of the major concept chains; the table above and catalog carry every lesson-level dependency.
Synthesizing vector architecture diagram...
Read from the atomic decision down to its larger failure domain. In particular, queues rely on idempotent effects, and live migrations rely on fencing; neither is introduced as a substitute for those prerequisites.
Three prototypes and the editorial decision
01 establishes the foundational standard: a concrete interleaving, an atomic implementation, then a multi-row counterexample. 08 establishes implementation depth: a runnable model, boundary cases, and a mathematical admission bound. 16 establishes distributed reasoning: a pause trace, a resource-side fence, and an explicit limit on what a lease proves.
The rest use this problem-first method, with different evidence: corrupted records, queue timelines, workload calculations, protocol traces, index candidates, and adversarial retries. Prototype QA and collection checks are recorded in QA_REPORT. Editorial validation here means a review against the rubric, not a claim of classroom testing.
Using the source references
Each lesson links to its contributing sources. The source map distinguishes concepts transformed into the lesson from detailed reference material intentionally left in the unchanged originals. The inventory records every source, heading, fenced asset, and link, with checksums so preservation can be verified. Vendor configurations and large worked traces remain references, not required detours in the narrative.
Reading in the website
The files use the existing first-line H1 convention, fenced code, GFM tables, Mermaid, KaTeX, and [!THINK] / [!ANSWER] blockquotes. There is no invented frontmatter or raw HTML disclosure widget. The current renderer implements AnswerReveal for answer callouts. Plain Markdown viewers show both callouts, so pause before reading the answer.
The Narrative Curriculum sidebar entry opens /narrative-curriculum, with an overview and all 37 lessons. It is available in the desktop sidebar, collapsed rail, and mobile drawer. Lesson pages follow /narrative-curriculum/<lesson-slug> and include prerequisites, a table of contents, answer reveals, and previous/next navigation. They use the same open reading model as Loop Primitives.
catalog.json is the lesson route allowlist and dependency metadata. The server reads only catalogued lesson files. The renderer resolves links relative to each lesson's sourcePath, then maps the curriculum path to its web route; source references retain their existing component and loop routes. Editorial documents have separate allowlisted reference pages, and Python labs/provenance JSON have allowlisted downloads. Audit/style/inventory/lab files are excluded from lesson navigation. The fixed-stage component mastery tracker is not attached to these lessons.
For local reading, start the application in apps/hispeeddesign with npm run dev, then visit http://localhost:3001/narrative-curriculum (or the configured port). The production build prerenders every lesson. See QA_REPORT for automated results and the remaining live-browser verification boundary.