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.
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.
Fix naming mismatches, migrate ridge/intensity exports to fmt_arithmetic_intensity, adopt fmt_length and fmt_rate for distance and speed, and register fmt_length in binder checks.
Resolved 36 conflicts by taking dev's side (mlsysim-deferred-polish
import migrations) and deterministically re-applying this branch's
mechanical transformations: LEGO cell reformat, dead #| label removal,
and the two #| output: false hoists.
No-backward-compat sweep, part 2. The module had been reduced to a
units-only re-export ('retired, do not add values'); per policy it is
now gone and every consumer reads the real home:
- 32 internal modules, the package __init__, and core/__init__ import
core.units (physics modules keep their own physics/constants)
- 43 book chapters' LEGO cells migrated (star imports, named imports,
and the appendix attribute style 'constants.VIDEO_*' -> units.*);
lego_focal_verify confirms identical pass/flag state to pre-sweep
(8 pre-existing structural flags, A/B-verified unchanged)
- tutorial/tools/test imports migrated (incl. binder test_units.py);
book tests' legacy-symbol scanner treats a missing constants.py as
'nothing defined'
- test_constants_allowlist.py rewritten as a deletion pin: the module
(and any shim for it) must never return; core.units must keep the
measurement surface (ureg, Q_, GB, BYTES_FP16, PRECISION_MAP, ...)
- test_mlsysim_registry_parity.py deleted: it compared registry values
against legacy constants 'before deletion' — that migration is
complete (registry gate list updated)
- Docs prose (DATA_MODEL, architecture, contributing) states the
deletion instead of describing a retired shim
749 passed; binder registry gate green; star import intact.
The book-format-python hook's fence regex matched display blocks
(```python, ```{.python}) but skipped executable ```{python} cells,
so hand-aligned assignment columns accumulated unchecked in LEGO code
(931 aligned lines across 22 files).
Add a second formatting profile for executable cells:
- Black at 150 chars (keeps one-line fmt_* exports; the display-block
70-char profile would explode them into multiline calls)
- --skip-string-normalization (preserves the corpus quote-style mix)
- #| option lines shielded with a sentinel (Black rewrites '#|' to
'# |', which breaks Quarto cell options)
- no comment wrapping (LEGO box-drawing headers must not rewrap)
- blank-line runs collapsed to one inside cells, keeping cells compact
and making output a fixed point for book-format-blanks, whose fence
toggle can desync on commented-out partial code blocks
Apply the one-time mechanical reformat across both volumes. Black
verifies AST equivalence, so all cells are semantically unchanged;
binder math/code checks and the LEGO test suites pass.
The linter silently missed *_unit_str = fmt(...) assignments; replace the broken
space-strip check with L014_CLOSED_FMT and allowlist 81 known cases until 8½-B.
Pre-commit lego-units now lints only staged QMDs with per-file baseline so
parallel WIP does not block atomic migration commits; full-repo baseline remains for CI.
Visual QA of all 207 margin figures surfaced figures that contradicted
their own captions/labels. Fixes:
- 6 ladder inversions where bar length taught the opposite of the data
(P99 vs mean, Image vs Text bandwidth, FHE vs AES latency, HBM vs
register energy, training vs inference memory, radio vs arithmetic).
Regenerated via margin_devices with consistent-unit / mlsysim SSOT
values.
- 5 trend/threshold figures whose shape did not match the relationship
(cloud-edge crossover, FPS collapse, burst-vs-sustained levels) plus
two caption reframes (retraining knee, training power).
- 7 segmented-bar figures whose labels were truncated to 4 chars and two
whose highlight contradicted the caption (egress, optimizer state);
regenerated readable with full labels.
- 10 passive/meta captions rewritten as declarative takeaways.
Root cause hardened in generate_margin_figures.py: _parse_number now
unit-aware (ms vs s, MB/s vs GB/s, pJ vs nJ) instead of mis-reading the
first letter of a unit as a k/M/B/T multiplier; ironbar label cap raised
from 5 chars so words are no longer chopped.
Replace pointers to the private project rules/docs tree (relative .claude/rules
and .claude/docs paths) in code comments and docstrings with neutral phrasing
("the project prose style guide", etc.). Load-bearing runtime paths that the
tooling reads or writes are left intact.
Drop absolute references to the author's private config repo (home-dir paths
into an external AIConfigs tree) from audit/newsletter tooling, and resolve the
prose-rule file in scan.py via the repo root instead of a hardcoded $HOME path
(also makes it portable across machines). No behavior change: the SHA lookup
keeps its graceful 'unknown' fallback when the file is absent.
With crossref prefixes set to lowercase, sentence-start refs need
the Quarto capitalized syntax (@Fig-, @Tbl-, @Sec-, @Eq-, @Lst-)
to render uppercase at sentence starts while staying lowercase
mid-sentence.
Applied 515 changes in vol1 (22 files) and 506 in vol2 (24 files).
Verified by rendering vol1/conclusion, vol1/introduction, and
vol2/introduction: capitalization correct in all contexts.
Also updated book/cli/commands/validate.py to recognize the
capitalized crossref prefixes in label/ref/citation checkers
(LABEL_REF_PATTERN, EXCLUDED_CITATION_PREFIXES, narrative_cite,
no_space_before_bracket).
Classification script added at book/tools/scripts/maintenance/
for future use and verification.
Codex chapter-by-chapter audit findings applied across vol1 and vol2:
prose rewrites where the cited source supported only a narrower or
adjacent claim, plus new audit tooling
(book/tools/scripts/build_citation_reference_packets.py and the
companion workflow doc).
Author-form cleanup pass on top of the audit:
- 19 narrative @key conversions where prose already named the author
(e.g., "Sambasivan et al. describe ... [@sambasivan2021]" -> narrative
"@sambasivan2021 describe ...", rendering "Sambasivan et al. (2021)
describe ...") - removes the citeproc duplication that the
manual-bracket regex did not catch.
- 4 [-@key] suppressed-author conversions for possessive eponyms
(Han et al., Vaswani et al., Patarasuk and Yuan, Linnainmaa).
- 2 [-@key] conversions where the prose names an author/entity that
matches the cited author (Patterson and Hennessy's iron law,
Google's data centers + Google whitepaper).
- 1 Horowitz footnote rewritten to narrative so the inline year
replaces a duplicated "(ISSCC 2014, ...) (Horowitz 2014)" pair.
- 1 narrative @russell2021 anchoring "As Russell argues" that was
previously a bare attribution.
- 1 pre-existing narrative fix for "Graham et al. report ..." in
collective_communication that had no cite on the line.
Pre-commit cleanups landing with this commit:
- subramanya2019diskann: add publisher = Curran Associates (NeurIPS
proceedings, per bib-check rule 3).
- Remove orphaned @misc{Wu2016} GNMT bib entry in vol2; it had no
citations and collided case-insensitively with @inproceedings{wu2016}
(the cited Quantized CNNs paper) under bibtex-tidy's normalization.
- vol1/training/training.qmd: drop the dead UtilizationGap LEGO cell
(gpu_real_tflops_*, cluster_*_tflops_*) and the dead
TrainingModels.{gpt3_gpu_years,gpt3_compute_cost}_str exports plus
their unused upstream values.
- vol2/distributed_training/distributed_training.qmd: anchor the
orphaned [^fn-parameter-server] footnote on the body-prose mention
of "parameter-server systems" rather than deleting the definition.
manual-bracket hook (book-check-refs) green at this tip.
