How to read this book

Cover-to-cover, with the repo open

This is not a reference manual. The chapters assume each other, and the labs build on each other. Read in order; do the labs.

The repository under /Users/pat/litigation-db is the worked example for every chapter. Every code excerpt in the book is taken from that repository at a pinned commit; every lab runs against it. You will get more from the book if your editor is open to the relevant file as you read. ## Three reading speeds Different chapters reward different paces. Slow (Chapters 4, 5, 6, 7, 25). The cryptographic spine. Read at the speed of understanding, not the speed of words. Reread the worked examples. Run the labs. Medium (Chapters 1–3, 11–12, 17–19, 26). The conceptual chapters. Read at normal speed. Stop to do the warm-up exercises. Fast (Chapters 13–16, 20–24, 28–30). The architectural chapters. Skim, but stop at the working examples and read the source files they reference. Part V (the capstone) is its own pace: 10 weeks of project work. ## Three things to skip on first reading You can defer these to a second pass: 1. The references in research/. They are dossiers, not chapters; they ground the writing but you don't need to read them to follow the book. 2. The "Stretch" exercise tier. The "Warm-up" and "Core" tiers are required; "Stretch" is for the second pass or for the strongest reader. 3. Appendix E (comparative architectures). It's useful when you find yourself comparing Canon to a neighbor system; it's not load-bearing for the spine. ## Three things never to skip 1. The labs. The book is structured so that the labs are the assessment. Reading without the labs produces familiarity, not skill. 2. The "build-your-own" prompts at the end of each chapter. They accumulate into your capstone. 3. The exercises that ask you to construct a deliberately-wrong artifact and detect it. Cryptographic intuition is built by attacking a system, not by trusting it. ## When you're stuck The convention in this book is the same as the Students' Guide to Raft convention from MIT 6.5840: stuck means you have a wrong mental model, not that you are missing information. When stuck: 1. Reread the chapter section that introduces the primitive. Slowly. 2. Run the test harness. The harness is the spec, executable. 3. Consult the dossier in research/ for the chapter's topic. The dossiers carry the live debates and known pitfalls. 4. If still stuck, write down your mental model in a paragraph. Most of the time the act of writing makes the gap visible.

Errata and corrections

This book is being written alongside the implementation. Both will have bugs. If you find one, open an issue or a PR against this directory. The sourcing convention — every code excerpt extracted from a pinned commit — exists so that errata can be tracked precisely and fixed without breaking the rest.

The book and the codebase publish from a single source of truth: when they disagree, the codebase wins, and the book is corrected.