How to use this book

Three kinds of chapters

Book chapters (orientation, part introductions, Part VI, appendices) are written for this book. They frame questions, connect parts and compare designs.

Imported chapters are the projects' own lessons, walkthroughs, labs and reference documents, shown in full. Each starts with a line like:

From cognokratos/<project> · docs/… · pinned revision abcdef123456

and ends with a short source note. Both link to the file at that exact revision on GitHub. Links inside an imported chapter behave as follows:

• a link to another chapter that is in the book stays inside the book, across parts too;
• a link to a source file, a directory or a document that is not in the book opens GitHub at the pinned revision, so code references always match the text you are reading;
• links to other websites are unchanged.

Book edition notes appear inside a few imported chapters, set apart like this:

Note

Book edition note. Where a sentence in an imported lesson is broader than the pinned code supports, the editors add a short note with the evidence. The lesson's own text is never altered.

Pinned revisions

The book is built from fixed commits of each project, listed in Source revisions and provenance. The projects keep evolving. If you clone a project to run its labs, check out the same revision the book shows (see Setting up each track) or expect differences.

How a lesson works

Most project lessons follow the same rhythm, with small variations:

1. The question and why it matters in production.
2. The concept, and the code that implements it.
3. A lab: run it, predict the result, observe it.
4. Break it: attack the guarantee on purpose.
5. Why it fails: find the guard that stopped you.
6. What to take away, and links to go deeper.

Challenges at the end of each part have no published solutions. They are design exercises: you are done when you can defend your design against the part's failure modes.

Navigating

• The sidebar mirrors the structure of the book. Parts fold, so you can collapse the ones you are not reading.
• Search (the magnifier, or press S or /) covers every chapter of every part, including code identifiers such as expected_choice or recoverInterruptedRuns.
• Use the arrows at the page edges, or the ← and → keys, to move to the previous or next chapter. Press ? for all keyboard shortcuts.
• The paintbrush switches between light and dark themes. Diagrams follow the theme.
• Glossary entries are deliberately short and point to the chapter that develops each term.