Builds on the PR #1957 merge (Zeljko's Vol1 layout), otherwise byte-for-byte his version:
- Remove the end-of-chapter research-questions callouts from all chapters.
- ml_ops correction-cascade figure: keep Zeljko's Model A-D chain TikZ drawing,
and rewrite the caption, alt-text, and lead-in to describe the chain (they
carried a stale 'timeline' description that no longer matched the figure),
plus an operations-impact line.
- Standardize the matplotlib figure font on a bundled TeX Gyre Heros (a free,
redistributable Helvetica-metric clone) registered at runtime in
book/tools/figures/style.py, so figures render with a real bold identically
on macOS, Linux, and CI instead of falling back to DejaVu Sans or an
unreachable macOS .ttc bold face.
New book/tools/audit/check_purpose_overflow.py: for each teaching chapter,
locates in the built PDF the page holding the Purpose hook and the page
holding the paragraph's last words; flags any chapter whose Purpose ends on
a later page than it starts. Uses plain pdftotext (the -layout mode
interleaves margin-stack/running-header labels into the paragraph and breaks
matching), normalizes curly quotes/em-dashes, falls back to shorter anchors.
Wired into preflight.sh as step 5. Run per volume:
python3 book/tools/audit/check_purpose_overflow.py <pdf> --vol vol1
resolve_precision('fp32') yields key 'fp32', which was absent from the H100/H200 precision_flops map (stored as 'fp32_cuda' = 67 TFLOP/s), so Engine.solve fell through to peak_flops (989, the FP16 dense rate) -- a ~15x FP32 overestimate reachable by no precision string.
- Rename precision_flops key fp32_cuda -> fp32 on H100 and H200 (value 67 TFLOP/s unchanged)
- Propagate the rename to every consumer, value-preserving: 2 LEGO cells
(compute_infrastructure, appendix_assumptions), 2 mlsysim_constants audit
manifests, and the migrate-constants map
- Add test_hardware guards: precision-vocabulary check (no canonical precision
aliased away) + H100/H200 fp32 -> 67 regression
Add native Binder checks for LEGO formatting/unit/prose contracts, extend mlsysim formatter helpers, and normalize Vol1/Vol2 LEGO output strings through typed formatters.
Validate precision-sensitive prose rendering across both volumes and promote direct math/string assembly to fmt_math, fmt_display_math, fmt_text, and domain-specific helpers.
Hardware specs already get sanity-bounds protection in
test_physics_bounds.py (catching an 80 TB/s typo for 80 GB/s), but
registered model specs had no equivalent guard: a transposed parameter
count (124M typed as 421M) or a decimal slip (124 typed as 12.4) in a
registry YAML would bind silently.
Two layers now protect every TransformerWorkload:
- test_transformer_attention_geometry: universal invariant that
hidden_dim splits evenly into heads with a 32-256 head dim and is a
multiple of 64 (catches transposed hidden_dim/heads across all 13
registered transformers).
- test_transformer_curated_specs: a curated, web-verified spec table
(seeded with GPT-2 Small, Radford 2019) that fails CI when a registry
value diverges >1% from its verified figure. Extend the table whenever
a new model spec is registered.
Wire GPT2_Small into the two chapter-side checks so its specs cannot be
hardcoded into a LEGO cell: CANONICAL in audit_mlsysim_drift.py and
HARDCODED_REGISTRY in book_check_registry_sources.py.
Verified the guard fires: transposing 124M to 421M fails the curated
test, and swapping hidden_dim/heads fails the geometry invariant.
Three-phase standalone audit tooling under book/tools/audit/:
- emphasis_extract.py: emit body-prose bold/italic spans, skipping code,
math, callouts, footnotes, headings, tables, captions (READ-ONLY).
- emphasis_ap2map.py: volume-wide bold occurrence map; flags terms bolded
in >=2 chapters (AP2 duplicate first-definition candidates), canonical
chapter order from the PDF config.
- emphasis_rollup.py: roll per-chapter agent ledgers under
.claude/_reviews/emphasis/ into a volume summary + actionable fix-list.
Ad-hoc audit tooling for now; candidate to fold into Binder as a
'check emphasis' group once it becomes a commit gate.
The L016 runner computed its line number as base_line + match.start() // 80,
a magic 'cols per line' guess that pointed authors at the wrong line. Count
actual newlines like the sibling L014 runner does.
NVIDIA quotes NVLink (and Google quotes TPU ICI) as bidirectional totals,
while PCIe and fabric entries store per-direction rates — two conventions
under one field name, undeclared. IOInterconnect now carries an explicit
direction field ('per_direction' default; 'bidirectional_total' tagged on
all NVLink/ICI YAML entries) and a bandwidth_per_direction accessor.
Systems.Nodes intra_node_bw now feeds the per-direction rate (H100 450,
A100 300, B200 900 GB/s) into the collective beta terms — previously the
bidirectional total made every intra-node-bound allreduce/TP latency ~2x
optimistic. Stored datasheet figures are unchanged, so spec displays keep
the familiar marketing numbers.
Distributed golden re-pinned to the corrected physics (tp comm 267->535 ms,
scaling efficiency 0.809->0.761 on the Llama3-8B/Research_256 case); new
convention test pins the tagging and accessor; drift auditor gains
per-direction entries.
Audit 2026-06-09, findings_provenance.md M1/M2. Ruling: VJ 2026-06-10.
Adds the literal classes the overnight audit found contradicting or
shadowing the registry — NVMe Gen4 latency/bandwidth, pluggable-optics
power, GPU MTTF, GDDR6X bandwidth, TPU v5p bandwidth, DS-CNN parameters,
GPT-4 parameter count, LeNet-1 parameters, H100 purchase price — so the
patterns cannot quietly return. Per the 'catch a mistake, add a check'
rule; each entry carries a note naming the incident.
Per-chapter worklists and rollups were one-run output: findings were
already applied or refuted, and regenerate from scan_floats.py. Keep
only the reusable tool and the grading rubric.
Prose: add the missing interpret move to eight figure, table, listing, and
equation references so body prose carries each float's takeaway without leaning
on the caption, per the float-exposition standard. Includes one mismatched-claim
fix: robust_ai cited the adversarial-googlenet figure against its own content.
Tooling: book/tools/audit/float_explanation/ -- the float-exposition scanner,
grading standard, per-chapter worklists, rollups, and the campaign record.
Vijay Janapa Reddi
