Progress log

Reviewed locally on 2026-09-07. The correction pass repairs instructional arithmetic, assumptions, source-summary contradictions and selected lab parsers. It does not certify every pinned upstream quotation or mark the GPU labs executed. The older narrative below is retained as an archive.

The historical count of 48 flags below has not been recertified as a current issue count. The categories above explain different closure requirements; they do not assert those 48 items are resolved.

python site/build.py
python site/test_build.py
python site/test_presentation.py
python site/test_inference_references.py
python content/courses/inference/html/labs/cpu_checks.py
python content/courses/inference/html/labs/quant_parallel_checks.py
python site/check_inference_citations.py

Commands run from the repository root. The citation inventory reports missing checkouts and unresolved engine ownership explicitly. Range existence is not quotation or semantic verification.

Followed at the start and end of every session. Deviating from it is how a book ends up describing three different versions of the scheduler.

At the start of a phase

1. Read this page and OUTLINE to reload state. Do not rely on memory of code from a previous session.
2. Confirm both repos are still at the pinned SHAs. tools/verify_citations.py checks this first and refuses to run if either has moved.
3. Pick up at the first chapter whose status is TODO.

Per chapter

1. Read tools/AUTHORING.md — the citation contract, fragment format, allowed CSS, mandatory chapter shape, diagram markup, and forbidden patterns.
2. Re-read the relevant source files in this session. Every citation must come from a file actually opened now, quoted from sed -n output rather than retyped.
3. Write the fragment into src/<part>/<chapter>.html.
4. Set status in tools/manifest.json: TODO → DRAFT → VERIFIED.
5. Add new terms to GLOSSARY and new formulas to FORMULAS in the same session — never defer these to the end.

The seven checks — all must pass before a part is closed

python3 tools/build_book.py         # regenerate every page from src/ + manifest
python3 tools/verify_citations.py   # every cited path exists, every line range is in range
python3 tools/check_links.py        # cross-chapter links and anchors resolve
python3 tools/check_symbols.py      # named flags and env vars still exist in the pinned source
MERMAID_MODULES=<scratch>/node_modules node tools/check_diagrams.mjs   # every diagram renders

check_diagrams.mjs needs a scratch npm i mermaid@11 @mermaid-js/layout-elk puppeteer; it renders every diagram through headless Chrome with the book's own theme and also warns when one exceeds fifteen nodes. A Mermaid parse error is otherwise invisible until a reader opens the page.

At the end of a part

1. Run all seven checks.
2. Run a contradiction pass. The mechanical checks cannot catch two chapters describing the same subsystem differently — read the part's chapters against each other and against their neighbours. This has caught real defects twice.
3. Append a log entry below, and add every raised Unverified flag to the table at the bottom.
4. Stop and summarise. Do not continue silently into the next part.

What the audit changed, in one paragraph

Three defect classes recurred often enough to be worth naming. Liveness was the worst: eight chapters presented vLLM's legacy model runner as the live path when V2 is the default for every dense model, and one listed the V2 branch among the dead ones — the exact inversion. Unit mixing was the most insidious: an “80 GB” H100 is 79.65 GiB, and expressions that mixed GiB with decimal GB produced four different KV-pool figures for the same machine across four chapters, each internally plausible. Assuming the conclusion was the subtlest: §10.3 derived serving capacity by charging a batch of 64 requests one request's prefill, then used Little's Law to recover a throughput that the assumed residence time already implied — 25 req/s where the honest figure is 14.2.

What the citation audit changed

A checker that only proves a cited range exists proves much less than it appears to. check_quotes.py was added to re-read every cited range and diff it against the quoted text, and the first full run over the finished chapters found 156 blocks whose quote did not match its citation. Most were ranges one or two lines short of the passage. The tail was not: a comment invented and inserted into quoted code; a command with <number-of-GPUs> silently replaced by 8; a docstring reworded; and a line asserting a variable (expert_start_loc) that appears nowhere near the lines it was attributed to. Every one of those passed verify_citations.py.

All 156 are resolved — 93 ranges corrected automatically, the rest by hand — and the checker now understands the book's legitimate conventions (descriptive elisions, shorthand second ranges, composite blocks quoting two files, re-wrapped markdown prose, ASCII-folded typography). The rule that prevents the whole class: generate quotes from sed output; never type them.

Original-project commands (not available in this checkout)

cd ~/Documents/knowledge/inference_vllm_sglang
python3 tools/verify_citations.py    # also refuses to run if either repo has moved off its pin
python3 tools/check_quotes.py        # quoted text vs the lines it cites
python3 tools/check_links.py
python3 tools/check_structure.py     # per-chapter diagram/exercise/citation contract
python3 tools/check_symbols.py       # slow: greps both trees

The seven checks

Known cleanup, not yet done

• Fourteen flowcharts exceed the fifteen-node guideline, the largest at 21. All were checked: each is a vertical decision flow with a maximum out-degree of 2, not a dense graph, so they read top-to-bottom without trouble. Left as they are deliberately — the guideline targets undifferentiated blobs, and redrawing working figures to satisfy it in letter would be churn.
• This older TODO predated the source project's later review described above. It is retained as history, not a current assertion that all chapters are drafts. The local correction pass must still distinguish source inspection, CPU tests and GPU execution.
• Several chapters ran long (4,500–6,100 words against a 4,000 guideline). Each author flagged it and named what to cut; none padded. Decide whether to trim or to raise the guideline.
• Unclaimed subtrees noted by chapter authors: SGLang's disaggregation/encoder/ (~8k lines) → 07-04; disaggregation/ascend/ → 05-05 or 13-01; vLLM's RSWASpec / ChunkedLocalAttentionSpec / SlidingWindowMLASpec → a Part 7 chapter.

Cross-chapter contradiction is the real risk

Chapters are written in parallel by separate agents, so the failure mode is not a bad citation — the checks catch those — but two chapters describing the same subsystem differently. It has happened twice and both times a sibling chapter caught it: 03-03 used an environment variable 03-04 had proven was deleted, and 02-06 documented a class 02-04 showed is never constructed. Budget a contradiction pass at the end of every part, not just the mechanical checks.

Findings from Parts 0–1 that invalidate widely-repeated descriptions of these systems. Each was read at the pinned SHA this session. They are recorded here because later parts must not contradict them, and because they are the clearest evidence that this book had to be written from source rather than from papers and blog posts.

Every Unverified callout raised anywhere in the book is mirrored here so it can be resolved in one pass. The table is generated at build time by scanning src/, so a flag cannot be raised in a chapter and quietly forgotten here.

Each is a genuine gap — a fact that could not be established from the pinned checkouts without network access or hardware — rather than a claim that was guessed at. Every one names what was searched. That is the standard: when the source does not answer a question, the book says so and says where it looked, and never fills the hole with something plausible.