StaffML: add draft topic→chapter map + recommended-reading design

First-pass topic_chapter_map.yaml (87 topics → book chapters, primary + also_see + rationale) plus the design analysis for connecting each StaffML question back to recommended textbook reading. Seeds the future work tracked in harvard-edge/cs249r_book#1822. Not yet wired into the build.
2026-07-16 23:24:55 -05:00 · 2026-05-29 10:05:53 -04:00
parent 0db2522de1
commit ed68fda58c
2 changed files with 612 additions and 0 deletions
--- a/interviews/staffml/docs/proposals/book-refs-analysis.md
+++ b/interviews/staffml/docs/proposals/book-refs-analysis.md
@@ -0,0 +1,212 @@
+# Recommended Reading: connecting StaffML questions back to the textbook
+
+**Status:** analysis / proposal — no code changes yet.
+**Worktree:** `MLSysBook-staffml-book-refs` (branch `feat/staffml-book-refs`, off local `dev`).
+
+---
+
+## Framing (settled with VJ)
+
+This is a **"go deeper" pointer, not an answer key.** The reference does *not* claim the
+question's answer lives in a given section — it says *"if you want to read about or learn
+this topic, here's where the book develops it."* It is tied to the question's **topic**,
+not to its solution. Consequences: the label is curiosity/consolidation framing
+("Learn more about this" / "Go deeper"), it renders **after** the attempt, and the
+topic→chapter mapping is a subject-matter judgment rather than an answer-location hunt.
+
+**Scope (settled):** book-only (no papers/docs/video for v1), covering **both Volume 1
+and Volume 2**, at **chapter** granularity.
+
+---
+
+## TL;DR
+
+The plumbing for this already exists and is **dormant** — a `Resource` type and a
+`details.resources` field are defined in the schema, the Pydantic-derived TS types,
+and the corpus bundle, but **zero of the 10,711 questions populate it** and nothing
+renders it. The right move is *not* to hand-author a reference for every question.
+Map the **87 topics → book chapters once** and derive each question's reference
+automatically from the `topic` it already carries. The book-URL stability concern
+that caused the team to defer this (see `Footer.tsx`) is now resolvable: the live
+chapter URLs are stable and verified.
+
+---
+
+## 1. What already exists (don't rebuild it)
+
+| Layer | Artifact | State |
+|---|---|---|
+| Schema | `Resource` class + `details.resources` on `Question` (`interviews/vault/schema/question_schema.yaml`) | ✅ defined |
+| TS types | `interface Resource { name; url }`, `details.resources?: Resource[]` (`corpus.ts`) | ✅ defined |
+| Bundle | summary corpus carries `details` | ✅ wired |
+| Authored data | questions with a populated `resources` | 🔴 **0 of 10,711** |
+| UI render | practice page rendering of `resources` | 🔴 none |
+| Funnel today | site-level footer link to book homepage only (`Footer.tsx`) | 🟡 coarse |
+
+`Footer.tsx` states the intent and the blocker verbatim:
+
+> *"Per-question book links are deferred until mlsysbook.ai URLs stabilize. In the
+> meantime the site-level cross-link to the book homepage — which cannot 404 — gives
+> every StaffML page a closing funnel back to the textbook."*
+
+So this proposal is really **"un-defer the per-question link"** — the schema slot was
+left open on purpose.
+
+## 2. The mapping problem — and why it's small
+
+There are 10,711 questions but the corpus is already classified along axes that are
+*far* smaller and already curated:
+
+```
+10,711 questions
+     └── 87 topics            ← map THIS to chapters (one-time, ~87 rows)
+            └── 13 competency areas
+                   └── 5 tracks
+```
+
+Every question carries a `topic` (one of 87 curated IDs in `taxonomy_data.yaml`) and a
+`competency_area` (one of 13). **Map topic → chapter once** and every question inherits
+a textbook reference for free. ~87 curated rows vs. 10,711 hand edits. The taxonomy is
+already a knowledge graph with prerequisite/related edges, which we can exploit later
+(§6).
+
+The book has 24 content chapters across two volumes (from the Quarto configs):
+
+- **Vol 1 (Foundations → Build → Optimize → Deploy):** introduction, ml_systems,
+  ml_workflow, data_engineering, nn_computation, nn_architectures, frameworks, training,
+  data_selection, model_compression, hw_acceleration, benchmarking, model_serving,
+  ml_ops, responsible_engr, conclusion.
+- **Vol 2 (Fleet → Distributed → Deployment → Responsible Fleet):** compute_infrastructure,
+  network_fabrics, data_storage, distributed_training, collective_communication,
+  fault_tolerance, fleet_orchestration, performance_engineering, inference,
+  edge_intelligence, ops_scale, security_privacy, robust_ai, sustainable_ai,
+  responsible_ai, conclusion.
+
+The competency areas line up suggestively with the volume split (e.g. `power`,
+`reliability`, `networking`, `parallelism` are Vol-2-heavy), which is almost certainly
+the "between Vol 1 and Vol 2 / recommended reading" idea that was suggested.
+
+## 3. URL stability — the blocker, now resolved
+
+The deferral reason was "until mlsysbook.ai URLs stabilize." Verified live (HTTP 200):
+
+```
+https://mlsysbook.ai/vol1/contents/vol1/training/training.html      → 200
+https://mlsysbook.ai/vol2/contents/vol2/inference/inference.html    → 200
+```
+
+Pattern: `https://mlsysbook.ai/vol{N}/contents/vol{N}/{chapter}/{chapter}.html`
+
+This maps **1:1** from the `.qmd` source path (`contents/vol1/training/training.qmd`),
+so the map can be generated from the Quarto config rather than typed by hand.
+
+**Granularity recommendation — chapter, not section.** Chapter anchors are
+human-authored and stable (`# Model Training {#sec-model-training}`). Section anchors
+carry auto-generated hash suffixes that regenerate on rebuild and *will* rot:
+
+```
+## Iron Law of Training Performance {#sec-model-training-iron-law-training-performance-a53f}
+                                                                                      ^^^^ regenerates
+```
+
+Link at chapter granularity for v1 (optionally `…training.html#sec-model-training` for
+the chapter top). Defer section deep-links until anchors are stabilized or a checker
+guarantees them.
+
+**Guardrail instead of indefinite deferral:** add a build-time link-checker that fails
+the vault build if a mapped chapter file doesn't exist (source-side check — no network).
+That converts "wait until URLs stabilize" into "URLs are enforced to be valid," which is
+why this can ship now.
+
+## 4. Field / schema design
+
+Three options considered:
+
+| Option | Mechanism | Pro | Con |
+|---|---|---|---|
+| A. Reuse `details.resources` per question | hand-author name+url on each YAML | uses existing field | 10,711 edits; semantics lost (book vs. arbitrary link); diff noise |
+| **B. Derive `book_refs` from a topic→chapter map** ✅ | one `topic_chapter_map.yaml`; vault build joins → emits `book_refs` into corpus | ~87 rows; auto-coverage; clean YAML diffs; matches how SVG visuals are kept out of YAML | needs a small build step + a new summary field |
+| C. Per-question column in every YAML | store resolved chapter on each YAML | explicit | reintroduces the 10k-edit + diff-noise problem |
+
+**Recommend B, with A as an optional override.** Source of truth is a single
+`interviews/vault/schema/topic_chapter_map.yaml`:
+
+```yaml
+# topic_chapter_map.yaml  (one row per topic; 87 total)
+roofline-analysis:
+  primary:   { volume: 1, chapter: hw_acceleration }
+  also_see:  [ { volume: 1, chapter: benchmarking } ]
+gpu-compute-architecture:
+  primary:   { volume: 1, chapter: hw_acceleration }
+```
+
+A `BookRef` shape (volume + chapter + derived title/url) gets emitted into the summary
+bundle so the card renders synchronously (no extra worker fetch). The dormant
+`details.resources` field stays — now meaningfully used for **per-question overrides**:
+a specific paper, a particular section, or a hand-picked extra beyond the topic default.
+Give `Resource` an optional `kind: book | paper | docs | video` so the structure is
+ready for the "broader set of sources" the user mentioned, without a future migration.
+
+## 5. Where & when to render (the pedagogy)
+
+The single most important design decision is **when** the link appears.
+
+> **Recommendation: reveal recommended reading *after* the attempt, not before.**
+> A student who can jump to the chapter before thinking will read instead of reason —
+> which defeats the napkin-math, "reason under uncertainty" purpose of StaffML. The
+> textbook is the *consolidation / go-deeper* step after the productive struggle, not a
+> shortcut around it. The card answers "want to learn more about this?" — not "here's
+> where the answer was."
+
+Concretely:
+
+- A **"Learn more in the textbook"** card rendered below the revealed solution on the
+  practice page (the details render around `practice/page.tsx:1146`), showing the
+  primary chapter with a Volume badge, plus 0–2 "also see" chapters.
+- One **"why this chapter" line** per ref — connect the question's concept to the
+  chapter, not a bare link. ("This question is about PUE as a multiplier — *Sustainable
+  AI* develops the full datacenter energy model.")
+- **Struggle-gated depth:** show only the primary chapter by default; expand to
+  prerequisites + related chapters when the student got it wrong or asked for a hint
+  (the wrong-answer path already exists in the scoring flow).
+
+This upgrades the footer funnel (coarse, site-level, intent-stage) to a per-question,
+concept-level funnel — which is exactly the gap the footer comment describes.
+
+## 6. Other ideas worth folding in
+
+1. **Prerequisite-aware remediation.** The taxonomy already encodes `prerequisite`
+   edges between topics. On a wrong answer, recommend the *prerequisite* topic's chapter
+   ("Shaky on this? Review X first"), not just the current one. This is the highest-value
+   pedagogical add and it's almost free given the existing graph.
+2. **Bidirectional links.** Chapters could link *out* to a filtered StaffML practice set
+   (`/practice?topic=…`). Reader finishes a chapter → practices; student finishes a
+   question → reads. Closes the loop both ways and reinforces the "one ecosystem" framing.
+3. **Source tiers / multi-source (the user's "future" ask).** The `kind` enum (§4) lets a
+   question point at book (primary) → canonical paper → vendor docs → talk, rendered as a
+   tiered list with the textbook always first. No schema migration needed later.
+4. **Track-sensitive mapping.** The same topic can be taught differently across volumes
+   (e.g. inference at the edge vs. in the fleet). Allow the map to vary the chapter by
+   `track` where it matters; default to a single primary otherwise.
+5. **Coverage report.** A build artifact listing topics with no chapter mapped — keeps the
+   87-row map honest as the taxonomy grows, and surfaces genuinely book-orphaned topics.
+
+## 7. Phasing & effort
+
+| Phase | Scope | Effort | Value |
+|---|---|---|---|
+| **1 — MVP** | `topic_chapter_map.yaml` (87 rows) + build join → `book_refs` in bundle + chapter-level card after reveal + link-checker | M | High — un-defers the feature for *all* questions at once |
+| **2 — Pedagogy** | prerequisite-on-wrong-answer; "why this chapter" lines; per-question `resources` overrides + `kind` enum | M | High |
+| **3 — Ecosystem** | bidirectional chapter→practice links; multi-source tiers; section deep-links once anchors checked | L | Medium |
+
+## 8. Open questions for VJ
+
+1. **Granularity:** chapter-level for v1 (recommended), or do you want section-level deep
+   links from the start (needs anchor-stability work first)?
+2. **Authoring the 87-row map:** want me to draft a first-pass `topic_chapter_map.yaml`
+   (topic → chapter) for you to correct, or do you want to drive the mapping since you
+   know where each concept is *sourced* in the book?
+3. **Reveal timing:** confirm "after the attempt" is the right pedagogy (vs. always
+   visible).
+4. **Scope of "broader sources":** book-only for v1 with the `kind` enum reserved for
+   later, or seed a few paper/doc references now?
--- a/interviews/vault/schema/topic_chapter_map.yaml
+++ b/interviews/vault/schema/topic_chapter_map.yaml
@@ -0,0 +1,400 @@
+# =============================================================================
+# topic_chapter_map.yaml  —  StaffML topic → MLSysBook chapter map
+# =============================================================================
+#
+# PURPOSE
+#   Maps each of the 87 curated topics (taxonomy_data.yaml) to the book
+#   chapter(s) where that subject is developed. This is a "go deeper" pointer,
+#   NOT an answer key: it says "if you want to learn about this topic, here's
+#   where the book covers it" — tied to the question's `topic`, decoupled from
+#   its solution. Every question inherits its reference from its topic, so this
+#   ~87-row file replaces per-question authoring across all 10,711 questions.
+#
+# STATUS
+#   FIRST-PASS DRAFT for review. Primary/also_see were assigned from each
+#   topic's taxonomy description + competency area + tracks. The author is the
+#   source of truth on where each concept is actually *sourced* in the book —
+#   fix any row whose `primary` points at the wrong chapter.
+#
+# SCHEMA (per topic)
+#   <topic-id>:
+#     primary:  { vol: <1|2>, chapter: <slug> }   # the one chapter to send a learner to
+#     also_see: [ { vol, chapter }, ... ]          # optional, 0–2 secondary chapters
+#     why:      "<one line: what this chapter develops for the topic>"
+#
+# URL DERIVED AT BUILD TIME (verified live, HTTP 200):
+#   https://mlsysbook.ai/vol{N}/contents/vol{N}/{chapter}/{chapter}.html
+#   (chapter-level only; section anchors carry regen-on-build hash suffixes)
+#
+# CHAPTER SLUGS (from the Quarto configs)
+#   Vol 1: introduction, ml_systems, ml_workflow, data_engineering,
+#          nn_computation, nn_architectures, frameworks, training,
+#          data_selection, model_compression, hw_acceleration, benchmarking,
+#          model_serving, ml_ops, responsible_engr, conclusion
+#   Vol 2: compute_infrastructure, network_fabrics, data_storage,
+#          distributed_training, collective_communication, fault_tolerance,
+#          fleet_orchestration, performance_engineering, inference,
+#          edge_intelligence, ops_scale, security_privacy, robust_ai,
+#          sustainable_ai, responsible_ai, conclusion
+# =============================================================================
+
+# ---------------------------------------------------------------- architecture
+transformer-systems-cost:
+  primary:  { vol: 1, chapter: nn_architectures }
+  also_see: [ { vol: 2, chapter: inference } ]
+  why: "Transformers and scaling laws are introduced here; KV-cache/attention cost recurs in inference."
+cnn-efficient-design:
+  primary:  { vol: 1, chapter: nn_architectures }
+  also_see: [ { vol: 1, chapter: model_compression } ]
+  why: "Depthwise-separable / MobileNet design lives in the architectures chapter."
+attention-scaling:
+  primary:  { vol: 1, chapter: nn_architectures }
+  also_see: [ { vol: 2, chapter: inference } ]
+  why: "MHA/GQA/MQA variants are an architecture topic; context-length cost shows up at inference."
+mixture-of-experts:
+  primary:  { vol: 1, chapter: nn_architectures }
+  also_see: [ { vol: 2, chapter: distributed_training } ]
+  why: "MoE as an architecture; expert parallelism is a distributed-training concern."
+model-size-estimation:
+  primary:  { vol: 1, chapter: nn_architectures }
+  also_see: [ { vol: 1, chapter: model_compression } ]
+  why: "Parameter counting and footprint feasibility follow from the architecture."
+neural-architecture-search:
+  primary:  { vol: 1, chapter: nn_architectures }
+  also_see: [ { vol: 2, chapter: edge_intelligence } ]
+  why: "NAS is architectural; hardware-aware/MCUNet-style search is an edge topic."
+encoder-decoder-tradeoffs:
+  primary:  { vol: 1, chapter: nn_architectures }
+  why: "Encoder-only vs decoder-only vs enc-dec is a core architectures discussion."
+recommendation-systems-engineering:
+  primary:  { vol: 1, chapter: nn_architectures }
+  also_see: [ { vol: 1, chapter: model_serving }, { vol: 2, chapter: data_storage } ]
+  why: "RecSys architecture; embedding-table scale touches serving and storage."
+
+# --------------------------------------------------------------------- compute
+roofline-analysis:
+  primary:  { vol: 1, chapter: hw_acceleration }
+  also_see: [ { vol: 2, chapter: performance_engineering } ]
+  why: "The roofline model is introduced with accelerators; reused for perf tuning at scale."
+gpu-compute-architecture:
+  primary:  { vol: 1, chapter: hw_acceleration }
+  also_see: [ { vol: 2, chapter: compute_infrastructure } ]
+  why: "Warps/occupancy/Tensor Cores are taught in the hardware-acceleration chapter."
+accelerator-comparison:
+  primary:  { vol: 1, chapter: hw_acceleration }
+  also_see: [ { vol: 2, chapter: compute_infrastructure } ]
+  why: "CPU/GPU/TPU/NPU/ASIC spectrum is the heart of hardware acceleration."
+mcu-compute-constraints:
+  primary:  { vol: 2, chapter: edge_intelligence }
+  also_see: [ { vol: 1, chapter: hw_acceleration } ]
+  why: "MCU/no-FPU/CMSIS-NN constraints are a TinyML (edge) deployment topic."
+systolic-dataflow:
+  primary:  { vol: 1, chapter: hw_acceleration }
+  also_see: [ { vol: 2, chapter: compute_infrastructure } ]
+  why: "Systolic arrays and weight/output-stationary dataflows are accelerator internals."
+compute-cost-estimation:
+  primary:  { vol: 1, chapter: hw_acceleration }
+  also_see: [ { vol: 2, chapter: compute_infrastructure } ]
+  why: "FLOPs/GPU-hours/$ estimation builds on the accelerator cost model."
+chiplet-architecture:
+  primary:  { vol: 2, chapter: compute_infrastructure }
+  also_see: [ { vol: 1, chapter: hw_acceleration } ]
+  why: "Multi-die scaling and yield-cost tradeoffs are a fleet-scale compute topic."
+
+# ---------------------------------------------------------------- cross-cutting
+federated-learning:
+  primary:  { vol: 2, chapter: edge_intelligence }
+  also_see: [ { vol: 2, chapter: security_privacy } ]
+  why: "Cross-device FL is an edge topic; privacy/communication tradeoffs link to security."
+autograd-computational-graphs:
+  primary:  { vol: 1, chapter: frameworks }
+  also_see: [ { vol: 1, chapter: nn_computation } ]
+  why: "Static/dynamic graphs and reverse-mode autodiff are a frameworks topic."
+software-portability:
+  primary:  { vol: 1, chapter: frameworks }
+  also_see: [ { vol: 2, chapter: edge_intelligence } ]
+  why: "HAL/TVM/MLIR lowering is a frameworks topic; conversion bites hardest on edge."
+sustainability-carbon-accounting:
+  primary:  { vol: 2, chapter: sustainable_ai }
+  also_see: [ { vol: 1, chapter: responsible_engr } ]
+  why: "Operational vs embodied carbon is the sustainable-AI chapter's core."
+differential-privacy:
+  primary:  { vol: 2, chapter: security_privacy }
+  also_see: [ { vol: 1, chapter: responsible_engr } ]
+  why: "DP-SGD / epsilon budgets / privacy-utility live in security & privacy."
+fairness-evaluation:
+  primary:  { vol: 2, chapter: responsible_ai }
+  also_see: [ { vol: 1, chapter: responsible_engr } ]
+  why: "Demographic parity / equalized odds / subgroup eval is responsible-AI material."
+responsible-ai:
+  primary:  { vol: 2, chapter: responsible_ai }
+  also_see: [ { vol: 1, chapter: responsible_engr } ]
+  why: "Model cards, red-teaming, governance frameworks are the responsible-AI chapter."
+tco-cost-modeling:
+  primary:  { vol: 2, chapter: compute_infrastructure }
+  also_see: [ { vol: 2, chapter: ops_scale } ]
+  why: "Buy-vs-rent / spot-vs-reserved / cost-perf Pareto is fleet-infrastructure economics."
+
+# ------------------------------------------------------------------------- data
+data-pipeline-engineering:
+  primary:  { vol: 1, chapter: data_engineering }
+  also_see: [ { vol: 2, chapter: data_storage } ]
+  why: "ETL/ELT, loaders, the data-pipeline equation are the data-engineering chapter."
+feature-store-management:
+  primary:  { vol: 1, chapter: data_engineering }
+  also_see: [ { vol: 2, chapter: data_storage } ]
+  why: "Online/offline stores and point-in-time correctness are introduced in data engineering."
+data-quality-validation:
+  primary:  { vol: 1, chapter: data_engineering }
+  why: "Schema validation, data contracts, quality gates are data-engineering fundamentals."
+dataset-curation:
+  primary:  { vol: 1, chapter: data_engineering }
+  also_see: [ { vol: 1, chapter: data_selection } ]
+  why: "Annotation workflows / IAA / dataset bias sit in data engineering; selection extends it."
+streaming-ingestion:
+  primary:  { vol: 1, chapter: data_engineering }
+  also_see: [ { vol: 2, chapter: data_storage } ]
+  why: "Stream processing and sensor ingestion are part of the data-engineering pipeline."
+storage-format-selection:
+  primary:  { vol: 2, chapter: data_storage }
+  also_see: [ { vol: 1, chapter: data_engineering } ]
+  why: "Parquet/TFRecord/columnar-vs-row and storage tiers are the data-storage chapter."
+data-efficiency-selection:
+  primary:  { vol: 1, chapter: data_selection }
+  also_see: [ { vol: 1, chapter: data_engineering } ]
+  why: "Coresets, curriculum, the data wall, ICR are exactly the data-selection chapter."
+
+# ------------------------------------------------------------------- deployment
+model-serving-infrastructure:
+  primary:  { vol: 1, chapter: model_serving }
+  also_see: [ { vol: 2, chapter: inference } ]
+  why: "Inference servers, autoscaling, cold start are the model-serving chapter."
+mlops-lifecycle:
+  primary:  { vol: 1, chapter: ml_ops }
+  also_see: [ { vol: 2, chapter: ops_scale } ]
+  why: "Registries, CI/CD for ML, training-serving consistency are MLOps fundamentals."
+ota-firmware-updates:
+  primary:  { vol: 2, chapter: edge_intelligence }
+  also_see: [ { vol: 1, chapter: ml_ops } ]
+  why: "A/B partitions, FOTA, flash constraints are an edge/TinyML deployment topic."
+container-orchestration:
+  primary:  { vol: 2, chapter: fleet_orchestration }
+  also_see: [ { vol: 1, chapter: ml_ops } ]
+  why: "Kubernetes, GPU device plugins, job scheduling are fleet-orchestration material."
+model-format-conversion:
+  primary:  { vol: 2, chapter: edge_intelligence }
+  also_see: [ { vol: 1, chapter: frameworks } ]
+  why: "ONNX/TFLite/CoreML/TensorRT conversion and op-coverage gaps are edge concerns."
+ab-rollout-strategies:
+  primary:  { vol: 1, chapter: ml_ops }
+  also_see: [ { vol: 2, chapter: ops_scale } ]
+  why: "Blue-green/canary/shadow and progressive rollout are MLOps practices."
+compound-ai-systems:
+  primary:  { vol: 2, chapter: inference }
+  also_see: [ { vol: 1, chapter: model_serving } ]
+  why: "RAG, agent orchestration, chained-inference latency are an inference-systems topic."
+disaggregated-serving:
+  primary:  { vol: 2, chapter: inference }
+  also_see: [ { vol: 1, chapter: model_serving } ]
+  why: "Prefill/decode split and cross-node KV transfer are an advanced inference topic."
+model-adaptation-systems:
+  primary:  { vol: 2, chapter: inference }
+  also_see: [ { vol: 2, chapter: edge_intelligence } ]
+  why: "LoRA serving / personalized inference; on-device adaptation links to edge."
+
+# ---------------------------------------------------------------------- latency
+latency-decomposition:
+  primary:  { vol: 1, chapter: model_serving }
+  also_see: [ { vol: 2, chapter: inference } ]
+  why: "End-to-end latency breakdown is taught with serving; TTFT/TPOT detailed at inference."
+batching-strategies:
+  primary:  { vol: 1, chapter: model_serving }
+  also_see: [ { vol: 2, chapter: inference } ]
+  why: "Static/dynamic/continuous batching is core to serving throughput."
+tail-latency:
+  primary:  { vol: 1, chapter: model_serving }
+  also_see: [ { vol: 2, chapter: ops_scale } ]
+  why: "P99/P999, hedged requests, SLA design are a serving topic; reinforced at fleet scale."
+real-time-deadlines:
+  primary:  { vol: 2, chapter: edge_intelligence }
+  also_see: [ { vol: 1, chapter: model_serving } ]
+  why: "Frame budgets, WCET, jank/ANR are edge/mobile real-time concerns."
+profiling-bottleneck-analysis:
+  primary:  { vol: 1, chapter: benchmarking }
+  also_see: [ { vol: 2, chapter: performance_engineering } ]
+  why: "Profilers, flame graphs, trace tools are introduced with benchmarking."
+queueing-theory:
+  primary:  { vol: 1, chapter: model_serving }
+  also_see: [ { vol: 2, chapter: performance_engineering } ]
+  why: "Little's Law and capacity sizing underpin serving; applied in perf engineering."
+
+# ----------------------------------------------------------------------- memory
+vram-budgeting:
+  primary:  { vol: 1, chapter: training }
+  also_see: [ { vol: 2, chapter: inference } ]
+  why: "Weights+optimizer+activations accounting is a training-memory topic; KV-cache at inference."
+kv-cache-management:
+  primary:  { vol: 2, chapter: inference }
+  also_see: [ { vol: 1, chapter: model_serving } ]
+  why: "Paged attention, eviction, long-context pressure are inference-systems topics."
+memory-hierarchy-design:
+  primary:  { vol: 1, chapter: hw_acceleration }
+  also_see: [ { vol: 2, chapter: compute_infrastructure } ]
+  why: "Registers/SRAM/HBM/DRAM capacity-bandwidth-latency is a hardware topic."
+activation-memory:
+  primary:  { vol: 1, chapter: training }
+  also_see: [ { vol: 2, chapter: distributed_training } ]
+  why: "Gradient checkpointing and the compute-memory tradeoff are training-time concerns."
+memory-mapped-inference:
+  primary:  { vol: 2, chapter: edge_intelligence }
+  also_see: [ { vol: 1, chapter: model_serving } ]
+  why: "mmap weight loading and cold-start avoidance are mobile/edge serving techniques."
+tensor-arena-planning:
+  primary:  { vol: 2, chapter: edge_intelligence }
+  also_see: [ { vol: 1, chapter: model_compression } ]
+  why: "Flat tensor arenas and peak-SRAM scheduling are a TinyML topic."
+dma-data-movement:
+  primary:  { vol: 1, chapter: hw_acceleration }
+  also_see: [ { vol: 2, chapter: compute_infrastructure } ]
+  why: "DMA, zero-copy, pinned memory, host-device movement are hardware-level."
+memory-pressure-management:
+  primary:  { vol: 1, chapter: training }
+  also_see: [ { vol: 2, chapter: inference } ]
+  why: "OOM/fragmentation/gradient-accumulation are training-memory tactics; eviction at serving."
+
+# ------------------------------------------------------------------- networking
+collective-communication:
+  primary:  { vol: 2, chapter: collective_communication }
+  why: "AllReduce/AllGather/ReduceScatter and ring-vs-tree are this chapter exactly."
+interconnect-topology:
+  primary:  { vol: 2, chapter: network_fabrics }
+  also_see: [ { vol: 2, chapter: compute_infrastructure } ]
+  why: "Fat-tree/torus/dragonfly and NVLink/IB are the network-fabrics chapter."
+network-bandwidth-bottlenecks:
+  primary:  { vol: 2, chapter: network_fabrics }
+  also_see: [ { vol: 2, chapter: distributed_training } ]
+  why: "Bisection bandwidth and comm-compute ratio are network-fabrics topics."
+rdma-transport:
+  primary:  { vol: 2, chapter: network_fabrics }
+  why: "RDMA/RoCE/IB verbs and kernel bypass are high-performance-transport material."
+load-balancing:
+  primary:  { vol: 1, chapter: model_serving }
+  also_see: [ { vol: 2, chapter: fleet_orchestration } ]
+  why: "Request routing / consistent hashing for inference traffic is a serving topic."
+congestion-control:
+  primary:  { vol: 2, chapter: network_fabrics }
+  why: "ECN/PFC/DCQCN and incast are GPU-cluster network-fabrics topics."
+
+# ------------------------------------------------------------------ optimization
+pruning-sparsity:
+  primary:  { vol: 1, chapter: model_compression }
+  also_see: [ { vol: 2, chapter: performance_engineering } ]
+  why: "Structured/unstructured pruning and accelerator-aligned sparsity are compression."
+knowledge-distillation:
+  primary:  { vol: 1, chapter: model_compression }
+  why: "Teacher-student, logit/feature distillation are the model-compression chapter."
+kernel-fusion:
+  primary:  { vol: 2, chapter: performance_engineering }
+  also_see: [ { vol: 1, chapter: frameworks } ]
+  why: "Fusing memory-bound ops and launch-overhead reduction is a perf-engineering topic."
+graph-compilation:
+  primary:  { vol: 1, chapter: frameworks }
+  also_see: [ { vol: 2, chapter: performance_engineering } ]
+  why: "AOT compilation, operator lowering, constant folding are framework-compiler topics."
+operator-scheduling:
+  primary:  { vol: 2, chapter: performance_engineering }
+  also_see: [ { vol: 1, chapter: frameworks } ]
+  why: "Execution-order optimization for memory reuse is a perf-engineering topic."
+flash-attention:
+  primary:  { vol: 2, chapter: inference }
+  also_see: [ { vol: 2, chapter: performance_engineering } ]
+  why: "IO-aware tiling / online softmax is taught alongside attention inference."
+speculative-decoding:
+  primary:  { vol: 2, chapter: inference }
+  why: "Draft-verify decoding and acceptance rates are an autoregressive-inference topic."
+
+# ------------------------------------------------------------------- parallelism
+communication-computation-overlap:
+  primary:  { vol: 2, chapter: distributed_training }
+  also_see: [ { vol: 2, chapter: collective_communication } ]
+  why: "Hiding collectives/DMA behind compute is a distributed-training scheduling topic."
+data-parallelism:
+  primary:  { vol: 2, chapter: distributed_training }
+  why: "Replicated training, gradient averaging, FSDP/ZeRO are distributed-training core."
+model-tensor-parallelism:
+  primary:  { vol: 2, chapter: distributed_training }
+  why: "Column/row partitioning across devices is distributed-training material."
+pipeline-parallelism:
+  primary:  { vol: 2, chapter: distributed_training }
+  why: "Stage splitting, micro-batching, bubble overhead are distributed-training topics."
+3d-parallelism:
+  primary:  { vol: 2, chapter: distributed_training }
+  why: "Combining DP+TP+PP for frontier training is the distributed-training chapter."
+gradient-synchronization:
+  primary:  { vol: 2, chapter: collective_communication }
+  also_see: [ { vol: 2, chapter: distributed_training } ]
+  why: "AllReduce variants, gradient compression, async SGD are collective-comm topics."
+scheduling-resource-management:
+  primary:  { vol: 2, chapter: fleet_orchestration }
+  also_see: [ { vol: 2, chapter: compute_infrastructure } ]
+  why: "MIG/MPS, gang scheduling, preemption, multi-tenancy are fleet-orchestration topics."
+
+# ------------------------------------------------------------------------ power
+power-budgeting:
+  primary:  { vol: 2, chapter: sustainable_ai }
+  also_see: [ { vol: 1, chapter: hw_acceleration } ]
+  why: "TDP/DVFS/CMOS energy equation and energy-per-inference anchor the sustainability chapter."
+thermal-management:
+  primary:  { vol: 2, chapter: compute_infrastructure }
+  also_see: [ { vol: 2, chapter: sustainable_ai } ]
+  why: "Cooling and sustained-vs-burst throttling are datacenter-infrastructure topics."
+energy-per-operation:
+  primary:  { vol: 2, chapter: sustainable_ai }
+  also_see: [ { vol: 1, chapter: hw_acceleration } ]
+  why: "The Horowitz energy table and memory-vs-compute energy are sustainability core."
+duty-cycling:
+  primary:  { vol: 2, chapter: edge_intelligence }
+  also_see: [ { vol: 2, chapter: sustainable_ai } ]
+  why: "Sleep/wake, coin-cell budgets, harvesting are TinyML always-on topics."
+datacenter-efficiency:
+  primary:  { vol: 2, chapter: sustainable_ai }
+  also_see: [ { vol: 2, chapter: compute_infrastructure } ]
+  why: "PUE, rack power, carbon-aware scheduling are the sustainability chapter."
+
+# -------------------------------------------------------------------- precision
+quantization-fundamentals:
+  primary:  { vol: 1, chapter: model_compression }
+  why: "INT8/INT4, zero-point, PTQ-vs-QAT, per-tensor-vs-per-channel are compression core."
+mixed-precision-training:
+  primary:  { vol: 1, chapter: training }
+  also_see: [ { vol: 1, chapter: model_compression } ]
+  why: "FP16/BF16/FP8, loss scaling, mixed-precision recipes are training-time topics."
+extreme-quantization:
+  primary:  { vol: 1, chapter: model_compression }
+  why: "Sub-4-bit, binary/ternary, GPTQ/AWQ are advanced model-compression topics."
+
+# ------------------------------------------------------------------- reliability
+fault-tolerance-checkpointing:
+  primary:  { vol: 2, chapter: fault_tolerance }
+  also_see: [ { vol: 1, chapter: training } ]
+  why: "Checkpoint strategy, Young-Daly, preemption recovery are the fault-tolerance chapter."
+distribution-drift-detection:
+  primary:  { vol: 1, chapter: ml_ops }
+  also_see: [ { vol: 2, chapter: ops_scale } ]
+  why: "Data/concept drift and training-serving skew are MLOps monitoring topics."
+graceful-degradation:
+  primary:  { vol: 2, chapter: robust_ai }
+  also_see: [ { vol: 2, chapter: fault_tolerance } ]
+  why: "Degradation ladders, fallbacks, QoS shedding are a robust-AI topic."
+safety-certification:
+  primary:  { vol: 2, chapter: robust_ai }
+  also_see: [ { vol: 2, chapter: edge_intelligence } ]
+  why: "ISO 26262, watchdogs, deterministic execution are robustness/safety topics."
+adversarial-robustness:
+  primary:  { vol: 2, chapter: security_privacy }
+  also_see: [ { vol: 2, chapter: robust_ai } ]
+  why: "Adversarial attacks, prompt injection, model extraction are security topics."
+monitoring-observability:
+  primary:  { vol: 1, chapter: ml_ops }
+  also_see: [ { vol: 2, chapter: ops_scale } ]
+  why: "Telemetry, alerting, MTBF/MTTR are MLOps; scaled out in ops-at-scale."