fix(ci): unblock pre-commit after cascade of latent regressions

Every hook now passes on `pre-commit run --all-files` (exit 0 after one
auto-fix pass + one verification pass — the standard pre-commit contract).
Unblocks book-validate-dev, which has been red on various hooks since the
mlsysim.core import failure finally cleared.

Fixes applied (source-traced, not suppressed):

1. codespell: 'OT' in mlperf-edu/reference/cloud/micro_lstm.py is the
   column name for Oil Temperature in the ETTh1 dataset (Zhou et al.,
   AAAI 2021), not a typo for 'to/of/or/not/it'. Added 'ot' to
   .codespell-ignore-words.txt (case-insensitive, covers OT).

2. bib-lint §5 bibliography hygiene: 12 entries in
   mlperf-edu/paper/refs.bib missing required publisher/journal per the
   canonical mapping in book-prose-merged.md §5. Added canonical
   publishers (MLSys → mlsys.org, ICLR → OpenReview.net, CVPR → IEEE,
   NAACL → ACL, etc.); promoted krizhevsky2009cifar from @Article to
   @TechReport with institution = University of Toronto. banbury2021mlperf
   uses Curran Associates Inc. (pre-2022 NeurIPS rule); flagged
   banbury2024wakevision for author review since the booktitle says CVPR
   but web verification suggests it is still an arXiv preprint.

3. Over-eager 'vs.' style sweep corrupted anchor IDs: 77 instances of
   -vs.- inside {#sec-...}, {#tbl-...}, {#fig-...} definitions and their
   @-references across 27 QMDs. Anchor IDs must be literal strings without
   periods per the repo's own section-ID naming rule; stripped the period
   from all anchor tokens while preserving 'vs.' in visible prose.

4. 4 broken SVG filename references from the same sweep (pam4-vs.-nrz,
   traditional-vs.-ml-fleet, tco-build-vs.-buy, centralized-vs.-decentralized)
   — filenames on disk use vs- (no period) so refs restored to match.

5. Malformed XML declaration in bathtub-curve.svg:
   '<?xml version="utf-8"?>' → '<?xml version="1.0" encoding="utf-8"?>'.

6. 21 quad-asterisks (****term****) in training.qmd collapsed to **term**.

7. bibtex-tidy auto-reformatted mlperf-edu/paper/refs.bib (alphabetical
   order + consistent indentation + wrapped author lists) and pipe-table
   prettifier realigned columns across ~20 QMDs. These are all cosmetic
   formatter output — no content changes.

Verified: pre-commit run --all-files run #1 modified files (exit 1),
run #2 exit 0 with 61 Passed / 0 Failed.

Author: profvjreddi

.codespell-ignore-words.txt

@@ -72,3 +72,4 @@ shs
 MulFunction
 3Nd
 relevants
+ot

book/quarto/contents/vol1/backmatter/appendix_dam.qmd

@@ -227,7 +227,7 @@ Note that common industry labels map to DAM components as follows: **Memory Boun
 
 Once you identify the bottleneck, @tbl-bottleneck-actions tells you what to do—and what NOT to do:
 
-| **If You are...**  | **Dominant Term**                | **Optimization That Works**                                       | **Optimization That is Wasted**                    |
+| **If You are...** | **Dominant Term**                | **Optimization That Works**                                       | **Optimization That is Wasted**                    |
 |:------------------|:---------------------------------|:------------------------------------------------------------------|:---------------------------------------------------|
 | **Memory-Bound**  | $D_{\text{vol}}/BW$              | Quantization, pruning, batching, kernel fusion                    | Faster accelerator (more FLOP/s will not help)     |
 | **Compute-Bound** | $O/(R_{\text{peak}} \cdot \eta)$ | Better kernels, Tensor Cores, faster accelerator, lower precision | More memory bandwidth (already saturated)          |
@@ -319,7 +319,7 @@ Identifying the root cause of performance bottlenecks requires systematic elimin
 |:--------------------------------|:-------------------------|:-------------------------------------------------------------|:-------------------------------------------------------|
 | **Low Accelerator Utilization** | **Data**                 | Is the data loader keeping up with the accelerator?          | Implement prefetching and use binary formats.          |
 | **High Latency (P99)**          | **Algorithm**            | Is the model depth or width exceeding the latency budget?    | Apply quantization (INT8) or structured pruning.       |
-| **High Training Cost**          | **Machine**              | Is the hardware utilization ($\eta$) below 30 percent?              | Optimize CUDA kernels or use spot instances.           |
+| **High Training Cost**          | **Machine**              | Is the hardware utilization ($\eta$) below 30 percent?       | Optimize CUDA kernels or use spot instances.           |
 | **Silent Accuracy Drift**       | **Data**                 | Has the statistical distribution ($P_t$) shifted from $P_0$? | Trigger retraining and update active learning filters. |
 | **Out-of-Memory (OOM)**         | **Algorithm/Machine**    | Does the model state fit in available VRAM?                  | Use gradient checkpointing or reduce batch size.       |
 
@@ -347,17 +347,17 @@ To surpass qualitative guessing, use the efficiency ratios in @tbl-dam-scorecard
 
 [^fn-mfu-scorecard]: **MFU (Model FLOPs Utilization)**: The ratio of achieved model FLOPs to the hardware's theoretical peak FLOPs, introduced by Chowdhery et al. (2022) in the PaLM paper. Unlike raw accelerator utilization (which counts any work the accelerator performs), MFU measures only *useful* model computation, excluding overhead like gradient synchronization and memory management. @sec-benchmarking covers MFU in depth.
 
-| **Axis**      | **Metric**        | **Definition**                                         | **Failing Grade** | **Passing Grade** |
-|:--------------|:------------------|:-------------------------------------------------------|------------------:|------------------:|
-| **Data**      | **I/O Overhead**  | $\frac{\text{Data Wait Time}}{\text{Total Step Time}}$ |           $>$ 10 percent |            $<$ 1 percent |
-| **Algorithm** | **Active Params** | $\frac{\text{Nonzero Params}}{\text{Total Params}}$    |      100 percent (Dense) |  $<$ 50 percent (Sparse) |
-| **Machine**   | **MFU**           | $\frac{\text{Achieved FLOPs}}{\text{Peak FLOPs}}$      |           $<$ 30 percent |           $>$ 50 percent |
+| **Axis**      | **Metric**        | **Definition**                                         |   **Failing Grade** |       **Passing Grade** |
+|:--------------|:------------------|:-------------------------------------------------------|--------------------:|------------------------:|
+| **Data**      | **I/O Overhead**  | $\frac{\text{Data Wait Time}}{\text{Total Step Time}}$ |      $>$ 10 percent |           $<$ 1 percent |
+| **Algorithm** | **Active Params** | $\frac{\text{Nonzero Params}}{\text{Total Params}}$    | 100 percent (Dense) | $<$ 50 percent (Sparse) |
+| **Machine**   | **MFU**           | $\frac{\text{Achieved FLOPs}}{\text{Peak FLOPs}}$      |      $<$ 30 percent |          $>$ 50 percent |
 
 : **The D·A·M Efficiency Rubric.** Use these three numbers to characterize any ML system's maturity. A system that passes all three thresholds has exhausted its easy optimizations; further gains require architectural changes or hardware upgrades. {#tbl-dam-scorecard}
 
 The Scorecard and the Roofline Model both answer efficiency questions, but at different scales. The Scorecard grades your current system against known thresholds. Scaling laws and the information roofline address a more strategic question: what happens as you scale *beyond* the current system?
 
-## scaling laws vs. Roofline {#sec-dam-taxonomy-scaling-laws-vs.-roofline-b290}
+## scaling laws vs. Roofline {#sec-dam-taxonomy-scaling-laws-vs-roofline-b290}
 
 Systems engineering requires distinguishing between *growth trajectories* and *fundamental limits*.
 

book/quarto/contents/vol1/backmatter/appendix_data.qmd

@@ -29,7 +29,7 @@ This appendix is designed as a *reference*. Use it when you are debugging “slo
 Conventions used here follow the book-wide notation (for example, we reserve \(B\) for batch size and use \(\text{BW}\) for bandwidth).
 
 - **When data won’t move**: Start with @tbl-data-gravity and the transfer-time equation in @sec-data-foundations-data-engineering-foundations-0c20.
-- **When the accelerator is starving**: Use @tbl-serialization-cost and the layout discussion in @sec-data-foundations-row-vs.-columnar-formats-bca2.
+- **When the accelerator is starving**: Use @tbl-serialization-cost and the layout discussion in @sec-data-foundations-row-vs-columnar-formats-bca2.
 - **When pipelines explode in cost**: Use the primitives in @sec-data-foundations-algebra-data-9792, especially join-induced shuffles.
 - **When “average looks fine” but users complain**: Use @sec-data-foundations-distributions-long-tail-901f and session-level tail probability.
 - **When accuracy drifts silently**: Use @sec-data-foundations-measuring-drift-divergence-a6dd to compare full distributions.
@@ -107,7 +107,7 @@ Data gravity[^fn-data-gravity] is not a metaphor; it is a calculation of transfe
 
 [^fn-data-gravity]: **Data Gravity**: Coined by Dave McCrory in 2010 to describe how large datasets attract services and applications toward them, much as massive bodies attract smaller ones in physics. The analogy is apt: the "escape velocity" required to move a petabyte-scale dataset is often measured in weeks.
 
-The transfer time for moving a dataset is simply $T = \text{Data Volume} / \text{Bandwidth}$ (for the large volumes here, latency is negligible; the full equation appears in @sec-machine-foundations-bandwidth-vs.-latency-5320). @tbl-data-gravity illustrates the sobering reality:
+The transfer time for moving a dataset is simply $T = \text{Data Volume} / \text{Bandwidth}$ (for the large volumes here, latency is negligible; the full equation appears in @sec-machine-foundations-bandwidth-vs-latency-5320). @tbl-data-gravity illustrates the sobering reality:
 
 | **Data Volume** |               **1 Gbps (Standard WAN)** |               **10 Gbps (High-End WAN)** |           **100 Gbps (Direct Connect)** | **Snowmobile (Truck)** |
 |:----------------|----------------------------------------:|-----------------------------------------:|----------------------------------------:|:-----------------------|
@@ -163,23 +163,23 @@ Even after data arrives at the machine, we face one final hurdle: the serializat
 
 [^fn-serialization]: **Serialization**: From Latin *serialis* (forming a series). The process of converting in-memory data structures into a byte stream for storage or transmission, and the reverse (*deserialization*). In ML pipelines, the choice of serialization format can dominate end-to-end training time; @sec-data-engineering covers pipeline design strategies that minimize this overhead.
 
-| **Format**          |                               **Decoding Speed (MB/s)** |                                    **CPU Cycles per Byte** | **Suitability**         |
-|:--------------------|--------------------------------------------------------:|-----------------------------------------------------------:|:------------------------|
+| **Format**        |                               **Decoding Speed (MB/s)** |                                    **CPU Cycles per Byte** | **Suitability**         |
+|:------------------|--------------------------------------------------------:|-----------------------------------------------------------:|:------------------------|
 | **CSV/JSON**      |         `{python} SerializationCost.csv_speed_str` MB/s |         `{python} SerializationCost.csv_cycles_str` cycles | Debugging only          |
-| **Protobuf**        |       `{python} SerializationCost.proto_speed_str` MB/s |       `{python} SerializationCost.proto_cycles_str` cycles | RPC/Messages          |
+| **Protobuf**      |       `{python} SerializationCost.proto_speed_str` MB/s |       `{python} SerializationCost.proto_cycles_str` cycles | RPC/Messages            |
 | **Parquet/Arrow** | **`{python} SerializationCost.parquet_speed_str` MB/s** | **`{python} SerializationCost.parquet_cycles_str` cycles** | **High-Scale Training** |
 
 : **Serialization Overhead.** Zero-copy formats like Arrow are 10--100$\times$ faster than row-based text formats because they align directly with internal memory structures. {#tbl-serialization-cost}
 
-### Row vs. columnar formats {#sec-data-foundations-row-vs.-columnar-formats-bca2}
+### Row vs. columnar formats {#sec-data-foundations-row-vs-columnar-formats-bca2}
 
 The choice of file format determines the "physics" of how your data is read.
 
 **Row-Oriented (CSV, JSON)**: Data is stored record-by-record. To read just the `age` column, you must scan every byte of every row. This is efficient for *writing* (appending a log) but inefficient for *analytics* (training on specific features).
 
-**Column-Oriented (Parquet, Arrow)**: Data is stored column-by-column. To read the `age` column, the disk head seeks to that column's block and reads it sequentially. This enables **projection pushdown** (reading only the bytes you need) and **vectorized processing** (single instruction, multiple data (SIMD) operations on columns). Compare the two arrangements side by side in @fig-row-vs.-col to see why columnar access avoids scanning unnecessary bytes.
+**Column-Oriented (Parquet, Arrow)**: Data is stored column-by-column. To read the `age` column, the disk head seeks to that column's block and reads it sequentially. This enables **projection pushdown** (reading only the bytes you need) and **vectorized processing** (single instruction, multiple data (SIMD) operations on columns). Compare the two arrangements side by side in @fig-row-vs-col to see why columnar access avoids scanning unnecessary bytes.
 
-::: {#fig-row-vs.-col fig-env="figure" fig-pos="htb" fig-cap="**Storage Layouts**: Row-oriented formats pack data together by record (good for transactions). Column-oriented formats pack data by feature (good for analytics)." fig-alt="Diagram contrasting row store vs. column store. Row store shows Record 1 [ID, Name, Age] followed by Record 2. Column store shows Column 1 [ID1, ID2...] followed by Column 2 [Name1, Name2...]."}
+::: {#fig-row-vs-col fig-env="figure" fig-pos="htb" fig-cap="**Storage Layouts**: Row-oriented formats pack data together by record (good for transactions). Column-oriented formats pack data by feature (good for analytics)." fig-alt="Diagram contrasting row store vs. column store. Row store shows Record 1 [ID, Name, Age] followed by Record 2. Column store shows Column 1 [ID1, ID2...] followed by Column 2 [Name1, Name2...]."}
 ```{.tikz}
 \begin{tikzpicture}[font=\small\usefont{T1}{phv}{m}{n}]
   \tikzset{

book/quarto/contents/vol1/backmatter/appendix_machine.qmd

@@ -221,9 +221,9 @@ These numbers reflect the current generation. Use them for back-of-envelope calc
 
 | Level                |                                  Latency |                                 Bandwidth |
 |:---------------------|-----------------------------------------:|------------------------------------------:|
-| Register             |                                  ~0.3 ns |—|
-| L1 Cache             |   ~`{python} NumbersToKnow.lat_l1_ns` ns |—|
-| L2 Cache             |   ~`{python} NumbersToKnow.lat_l2_ns` ns |—|
+| Register             |                                  ~0.3 ns |                                         — |
+| L1 Cache             |   ~`{python} NumbersToKnow.lat_l1_ns` ns |                                         — |
+| L2 Cache             |   ~`{python} NumbersToKnow.lat_l2_ns` ns |                                         — |
 | GPU HBM3             |  ~`{python} NumbersToKnow.lat_hbm_ns` ns | `{python} NumbersToKnow.bw_hbm_h100` TB/s |
 | PCIe Gen5 (CPU↔GPU)  | ~`{python} NumbersToKnow.lat_pcie_ns` ns |    `{python} NumbersToKnow.bw_pcie5` GB/s |
 | CPU DRAM             |                                  ~100 ns |     `{python} NumbersToKnow.bw_dram` GB/s |
@@ -240,7 +240,7 @@ These numbers reflect the current generation. Use them for back-of-envelope calc
 |:-----------------------|------------------------------------------------:|------------------------------------------------:|------:|
 | Data center GPU (H100) | `{python} NumbersToKnow.flops_h100_fp16` TFLOPS |    `{python} NumbersToKnow.flops_h100_fp8` TOPS | 700 W |
 | Data center GPU (A100) | `{python} NumbersToKnow.flops_a100_fp16` TFLOPS |                                        624 TOPS | 400 W |
-| Mobile NPU             |—| `{python} NumbersToKnow.flops_mobile_int8` TOPS | 3–5 W |
+| Mobile NPU             |                                               — | `{python} NumbersToKnow.flops_mobile_int8` TOPS | 3–5 W |
 
 : **Compute Reference (c. 2024).** Data center is ~28$\times$ more powerful than mobile—this ratio persists across generations. {#tbl-compute-current-ref}
 
@@ -924,9 +924,9 @@ The memory hierarchy is the fundamental physical constraint of machine learning
 
 | **Layer**            | **Technology** |                                   **Latency** |                                      **Bandwidth** |                       **Energy (per 32b)** |
 |:---------------------|:---------------|----------------------------------------------:|---------------------------------------------------:|-------------------------------------------:|
-| **Registers**        | Flip-Flops     |                                       ~0.3 ns |—|   `{python} AppendixMachineSetup.e_reg` pJ |
-| **L1 Cache**         | SRAM           |     ~`{python} AppendixMachineSetup.l1_ns` ns |—|    `{python} AppendixMachineSetup.e_l1` pJ |
-| **L2 Cache**         | SRAM           |     ~`{python} AppendixMachineSetup.l2_ns` ns |—|    `{python} AppendixMachineSetup.e_l2` pJ |
+| **Registers**        | Flip-Flops     |                                       ~0.3 ns |                                                  — |   `{python} AppendixMachineSetup.e_reg` pJ |
+| **L1 Cache**         | SRAM           |     ~`{python} AppendixMachineSetup.l1_ns` ns |                                                  — |    `{python} AppendixMachineSetup.e_l1` pJ |
+| **L2 Cache**         | SRAM           |     ~`{python} AppendixMachineSetup.l2_ns` ns |                                                  — |    `{python} AppendixMachineSetup.e_l2` pJ |
 | **Memory (Local)**   | HBM3           |    ~`{python} AppendixMachineSetup.hbm_ns` ns |    `{python} AppendixMachineSetup.bw_hbm_str` GB/s |  `{python} AppendixMachineSetup.e_dram` pJ |
 | **Interconnect**     | NVLink 4.0     | ~`{python} AppendixMachineSetup.nvlink_ns` ns | `{python} AppendixMachineSetup.bw_nvlink_str` GB/s | ~`{python} AppendixMachineSetup.e_dram` pJ |
 | **Host Link**        | PCIe Gen5      |   ~`{python} AppendixMachineSetup.pcie_ns` ns |   `{python} AppendixMachineSetup.bw_pcie_str` GB/s | ~`{python} AppendixMachineSetup.e_dram` pJ |
@@ -942,7 +942,7 @@ The hierarchy's energy costs reveal why data movement dominates modern system de
 Fetching a 32-bit value from DRAM costs roughly **`{python} AppendixMachineSetup.energy_ratio_str`$\times$ more energy** than performing a floating-point operation on it (for example, ~`{python} AppendixMachineSetup.dram_pj` pJ vs. ~`{python} AppendixMachineSetup.flop_pj` pJ). This "Energy Wall" means that maximizing **arithmetic intensity** (doing many ops per loaded byte) is the only way to be energy efficient.
 :::
 
-### Bandwidth vs. Latency {#sec-machine-foundations-bandwidth-vs.-latency-5320}
+### Bandwidth vs. Latency {#sec-machine-foundations-bandwidth-vs-latency-5320}
 
 Bandwidth (throughput) and latency (delay) are distinct constraints. Total transfer time follows: