@brandon_m_behring/book-scaffold-astro 5.0.0 → 5.1.0

package/scripts/validate-core.mjs

@@ -0,0 +1,1675 @@
+/**
+ * validate-core.mjs — callable pre-flight validation for book content.
+ *
+ * Catches authoring errors that astro build either misses or surfaces
+ * with insufficient context. Designed to run in <2 s on a medium-sized
+ * book so it's pre-commit-hook friendly.
+ *
+ * Checks performed (per Q14 in the v2.0 plan):
+ *   1. <Cite key="..." /> — key exists in src/data/references.json.
+ *   2. <XRef id="..." /> — id exists in src/data/labels.json.
+ *   3. <Figure src="/path/..." /> — file exists under public/.
+ *   4. Internal markdown links [text](/foo) — target resolves.
+ *   5. <CodeRef path="..." line={N} /> — when BOOK_REPO_ROOT set,
+ *      path exists + line in bounds.
+ *   6. <Theorem> — has a resolvable kind= (or legacy type=); else it would
+ *      render an empty label and throw at build (#121). An id'd theorem must
+ *      resolve in labels.json, and a literal n= must agree with that index.
+ *   7. <BookLink book="…" to="…"> (#96/#147) — both props present, book= is
+ *      registered, and literal fragment targets resolve in the sibling's
+ *      declared vendored labels index. Dynamic and URL-only entries warn/skip.
+ *   8. Questions collection (#112) — each question's frontmatter `domain` is a
+ *      member of the consumer's examDomains registry (best-effort), and question
+ *      `id`s are unique (the cross-ref key for the appendix / flashcards).
+ *   9. Learning-objective anchors (#130) — when a chapter declares frontmatter
+ *      `los:` entries with `anchor:` slugs, the declared set and the prose's
+ *      MDX anchor-comment marker set must agree in both directions.
+ *  10. Authored root-absolute href/src targets (#190) — under a non-root Astro
+ *      base, literal Markdown, HTML, and JSX targets must stay inside that base.
+ *
+ * Run from the consumer's project root. Closes #8 (was resolving paths
+ * from the package's own directory inside node_modules — false negatives
+ * across all reference consumers).
+ *
+ * Usage:
+ *   book-scaffold validate
+ *   book-scaffold validate --preset academic
+ *   BOOK_REPO_ROOT=/abs/path npx book-scaffold validate
+ *
+ * Exit code = total failure count capped at 255 (0 = pass, >=1 = errors).
+ */
+import { readFile, access } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, dirname, extname, join } from 'node:path';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkMath from 'remark-math';
+import remarkMdx from 'remark-mdx';
+import { walkMdx, readChaptersBase, readBookSchemaConfig } from './walk-mdx.mjs';
+import { readEnvFile } from './read-env.mjs';
+import { loadResolvedBookConfig } from './resolve-book-config.mjs';
+import {
+  assertCorpusEnvelope,
+  frontmatterSlug,
+  legacyFrontmatterBook,
+  parseFrontmatter,
+  resolveBookSelection,
+} from './corpus-tooling.mjs';
+import {
+  findAuthoredTargets,
+  normalizeAstroBase,
+  rootTargetEscapesBase,
+  rootTargetPathname,
+  suggestBaseContainedTarget,
+} from './authored-links.mjs';
+
+// --help / -h: non-mutating (closes #14).
+export const VALIDATE_USAGE = `Usage: book-scaffold validate [--preset <name>]
+
+Pre-flight content validator. Checks Cite keys, XRef ids, Figure srcs,
+internal authored links, and (when BOOK_REPO_ROOT is set) CodeRef paths.
+
+Options:
+  --preset <name>    academic | tools | minimal | course-notes | research-portfolio
+                     Explicit override when no scaffold integration is resolved.
+  --book <id>        In corpus mode, validate only one registered book.
+  --help, -h         Print this message and exit (non-mutating).
+
+Env:
+  BOOK_PRESET        Preset name (preferred over BOOK_PROFILE).
+  BOOK_PROFILE       Backward-compat alias for BOOK_PRESET.
+  BOOK_REPO_ROOT     Absolute path to a sibling code repo for CodeRef checks.
+
+Exit code = total failure count, capped at 255 so failures never wrap to success.
+No preset is inferred: configure a Style/corpus, content schema preset, flag, or env.
+`;
+
+class ValidationFatal extends Error {
+  constructor(kind, message, exitCode) {
+    super(message);
+    this.name = 'ValidationFatal';
+    this.kind = kind;
+    this.exitCode = exitCode;
+  }
+}
+
+/**
+ * Run the content-contract validator without mutating process globals.
+ *
+ * `regenerateArtifact` is deliberately injected: the core never spawns a
+ * command. The legacy CLI supplies a spawn-backed callback, while other
+ * callers may provide an in-process implementation or leave it absent and
+ * receive a structured artifact fatal.
+ */
+export async function runValidation(options = {}) {
+  const argv = [...(options.argv ?? [])];
+  const ROOT = resolve(options.root ?? process.cwd());
+  const ENV = options.env ?? process.env;
+  const stdout = [];
+  const stderr = [];
+  const context = {
+    root: ROOT,
+    toolingConfig: null,
+    selection: null,
+    preset: null,
+    errors: [],
+    warnings: [],
+    notices: [],
+    chapterFiles: [],
+    chapterCountsByBook: new Map(),
+    questionsChecked: 0,
+    questionsCheckedByBook: new Map(),
+    regenerationRequests: [],
+  };
+
+  const writeOutput = (stream, value) => {
+    const text = String(value);
+    (stream === 'stdout' ? stdout : stderr).push(text);
+    options.onOutput?.({ stream, text });
+  };
+  const writeStdout = (value) => writeOutput('stdout', value);
+  const writeStderr = (value) => writeOutput('stderr', value);
+  const abort = (kind, message, exitCode, rendered) => {
+    if (rendered) writeStderr(rendered);
+    throw new ValidationFatal(kind, message, exitCode);
+  };
+  const finish = (exitCode, fatal = null) => {
+    const selection = context.selection;
+    const selected = selection?.corpus
+      ? selection.books.map((book) => book.id)
+      : [];
+    const diagnostic = (severity, item, code) => ({
+      severity,
+      code,
+      message: item.msg,
+      book: item.book,
+      ...(item.file ? { file: item.file } : {}),
+      ...(Number.isInteger(item.line) ? { line: item.line } : {}),
+    });
+    const diagnostics = [
+      ...context.errors.map((item) => diagnostic('error', item, 'validation_error')),
+      ...context.warnings.map((item) => diagnostic('warning', item, 'validation_warning')),
+      ...context.notices,
+    ];
+    const bookResults = selection
+      ? selection.corpus
+        ? selection.books.map((book) => ({
+            book: book.id,
+            chapters: context.chapterCountsByBook.get(book.id) ?? 0,
+            questions: context.questionsCheckedByBook.get(book.id) ?? 0,
+            errors: context.errors.filter((item) => item.book === book.id),
+            warnings: context.warnings.filter((item) => item.book === book.id),
+          }))
+        : [{
+            book: null,
+            chapters: context.chapterFiles.length,
+            questions: context.questionsChecked,
+            errors: [...context.errors],
+            warnings: [...context.warnings],
+          }]
+      : [];
+    return {
+      status: fatal ? 'fatal' : context.errors.length > 0 ? 'invalid' : 'valid',
+      exitCode,
+      fatal,
+      preset: context.preset,
+      numberStyle: context.toolingConfig?.numberStyle ?? null,
+      toolingConfig: context.toolingConfig,
+      scope: selection
+        ? {
+            kind: selection.corpus ? 'corpus' : 'single',
+            requestedBook: selection.requestedBook,
+            selected,
+          }
+        : null,
+      errors: [...context.errors],
+      warnings: [...context.warnings],
+      notices: [...context.notices],
+      diagnostics,
+      bookResults,
+      counts: {
+        chapters: context.chapterFiles.length,
+        questions: context.questionsChecked,
+      },
+      regenerationRequests: [...context.regenerationRequests],
+      output: {
+        stdout: stdout.join(''),
+        stderr: stderr.join(''),
+      },
+    };
+  };
+
+  try {
+
+// --preset <name> CLI flag (closes #9 — single source of truth across
+// defineBookConfig + validate).
+const presetFlagIdx = argv.findIndex((a) => a === '--preset');
+const presetFromFlag = presetFlagIdx >= 0 ? argv[presetFlagIdx + 1] : undefined;
+
+// v3.4.0: ROOT is the consumer's CWD, not the package's own dir.
+// Resolves issue #8 — three reference consumers reported "0 chapter(s) checked"
+// because ROOT was the package directory inside node_modules.
+const PUBLIC_DIR = resolve(ROOT, 'public');
+const DATA_DIR = resolve(ROOT, 'src/data');
+
+let TOOLING_CONFIG;
+try {
+  TOOLING_CONFIG = await loadResolvedBookConfig(ROOT);
+} catch (error) {
+  const message = String(error?.message ?? error);
+  abort('config', message, 1, `validate: fatal: ${message}\n`);
+}
+context.toolingConfig = TOOLING_CONFIG;
+let BOOK_SELECTION;
+try {
+  BOOK_SELECTION = resolveBookSelection(TOOLING_CONFIG, argv, 'validate');
+} catch (error) {
+  const prefix = TOOLING_CONFIG.corpus ? '[book:corpus] ' : '';
+  const message = String(error?.message ?? error);
+  abort('invocation', message, 1, `${prefix}validate: fatal: ${message}\n`);
+}
+context.selection = BOOK_SELECTION;
+const CORPUS_DIAGNOSTIC_PREFIX = BOOK_SELECTION.corpus ? '[book:corpus] ' : '';
+// Corpus content uses one root with a registered first segment per book;
+// single-book consumers retain the historical chapters directory.
+let CHAPTERS_DIR;
+try {
+  CHAPTERS_DIR = await readChaptersBase(ROOT, { corpus: BOOK_SELECTION.corpus });
+} catch (error) {
+  const message = String(error?.message ?? error);
+  abort(
+    'config',
+    message,
+    1,
+    `${CORPUS_DIAGNOSTIC_PREFIX}validate: fatal: ${message}\n`,
+  );
+}
+
+// Preset resolution:
+//   composed Astro-config preset > --preset flag > BOOK_PRESET env > BOOK_PROFILE env >
+//   .env BOOK_PRESET > .env BOOK_PROFILE >
+//   defineBookSchemas({ preset }) in content.config.ts >
+//   defineBookSchemas({ profile }) in content.config.ts (alias).
+// .env fallback closes #20 — without it, consumers who set BOOK_PROFILE in
+// .env (the documented convenience in SKILL.md + create-book defaults) saw
+// the CLI silently default to minimal, hiding academic-profile errors.
+// content.config.ts fallback closes #75 — without it, consumers using the
+// canonical v4.5+ defineBookSchemas({ preset, chaptersBase }) form had the
+// CLI silently default to minimal, hiding research-portfolio (and any
+// non-env-set) profile errors while astro build applied the correct settings.
+const dotenv = readEnvFile(ROOT);
+const schemaConfig = await readBookSchemaConfig(ROOT);
+const PRESET_CANDIDATE =
+  TOOLING_CONFIG.preset ??
+  presetFromFlag ??
+  ENV.BOOK_PRESET ??
+  ENV.BOOK_PROFILE ??
+  dotenv.BOOK_PRESET ??
+  dotenv.BOOK_PROFILE ??
+  schemaConfig.preset;
+const PRESETS = ['academic', 'tools', 'minimal', 'course-notes', 'research-portfolio'];
+if (presetFlagIdx >= 0 && !presetFromFlag) {
+  abort(
+    'invocation',
+    '--preset requires a value.',
+    2,
+    `${CORPUS_DIAGNOSTIC_PREFIX}validate: --preset requires a value.\n`,
+  );
+}
+if (PRESET_CANDIDATE && !PRESETS.includes(PRESET_CANDIDATE)) {
+  const message =
+    `preset must be one of ${PRESETS.join(' | ')} ` +
+    `(got ${JSON.stringify(PRESET_CANDIDATE)}).`;
+  abort(
+    presetFlagIdx >= 0 ? 'invocation' : 'config',
+    message,
+    1,
+    `${CORPUS_DIAGNOSTIC_PREFIX}validate: ${message}\n`,
+  );
+}
+if (!PRESET_CANDIDATE) {
+  const message =
+    'no book preset was resolved. Add a built-in Style to ' +
+      '`defineBookConfig({ styles: [...] })` and pass the same preset to ' +
+      '`defineBookSchemas({ preset: "..." })`, pass one `defineBookCorpus` manifest ' +
+      'to both entrypoints, use --preset, or set BOOK_PRESET in the environment or .env. ' +
+      `Valid presets: ${PRESETS.join(' | ')}. See ` +
+      'https://github.com/brandon-behring/book-scaffold-astro/blob/main/' +
+      'package/MIGRATION-v4-to-v5.md.';
+  abort(
+    'config',
+    message,
+    1,
+    `${CORPUS_DIAGNOSTIC_PREFIX}validate: ${message}\n`,
+  );
+}
+const PRESET = PRESET_CANDIDATE;
+context.preset = PRESET;
+// Alias kept for downstream message text only; the resolution above is canonical.
+const PROFILE = PRESET;
+const MATH_ENABLED = PROFILE === 'academic' || PROFILE === 'research-portfolio';
+const REPO_ROOT = ENV.BOOK_REPO_ROOT ?? null;
+const corpusDependencyParser = unified().use(remarkParse).use(remarkMdx);
+if (MATH_ENABLED) corpusDependencyParser.use(remarkMath);
+
+let selectedCorpusDependencies = null;
+async function resolveSelectedCorpusDependencies() {
+  if (selectedCorpusDependencies) return selectedCorpusDependencies;
+
+  const routeBooks = new Set(BOOK_SELECTION.books.map((book) => book.id));
+  const labelBooks = new Set(BOOK_SELECTION.books.map((book) => book.id));
+  if (!BOOK_SELECTION.corpus || BOOK_SELECTION.requestedBook === null) {
+    selectedCorpusDependencies = { routeBooks, labelBooks };
+    return selectedCorpusDependencies;
+  }
+
+  const selectedBook = BOOK_SELECTION.books[0];
+  const selectedDir = join(CHAPTERS_DIR, selectedBook.id);
+  const corpusIds = new Set(BOOK_SELECTION.corpus.books.map((book) => book.id));
+  const configuredBase = normalizeAstroBase(TOOLING_CONFIG.base);
+  for await (const file of walkMdx(selectedDir)) {
+    const content = await readFile(join(selectedDir, file), 'utf8');
+
+    // Root-absolute Markdown chapter links need only the referenced book's
+    // slug index. Structural collection avoids examples in code/comments.
+    try {
+      const targets = findAuthoredTargets(content, {
+        format: authoredFormat(file),
+        math: MATH_ENABLED,
+      });
+      for (const target of targets) {
+        if (target.kind !== 'Markdown link destination') continue;
+        const pathname = rootTargetPathname(target.target);
+        if (pathname === null) continue;
+        const localPath =
+          configuredBase !== '/' &&
+          (pathname === configuredBase || pathname.startsWith(`${configuredBase}/`))
+            ? pathname.slice(configuredBase.length) || '/'
+            : pathname;
+        const match = localPath.match(/^\/chapters\/([^/]+)(?:\/|$)/);
+        if (match && corpusIds.has(match[1])) routeBooks.add(match[1]);
+      }
+    } catch {
+      // The main validation pass reports the parse failure with source context.
+    }
+
+    if (!content.includes('<BookLink')) continue;
+    try {
+      for (const element of mdxElements(corpusDependencyParser.parse(content), 'BookLink')) {
+        const bookAttr = mdxStringProp(element, 'book');
+        const toAttr = mdxStringProp(element, 'to');
+        if (!bookAttr.literal || !toAttr.literal || !corpusIds.has(bookAttr.value)) continue;
+        const target = normalizeCorpusTarget(
+          BOOK_SELECTION.corpus.books.find((book) => book.id === bookAttr.value),
+          toAttr.value,
+        );
+        if (target.error || !target.chapterSlug) continue;
+        routeBooks.add(bookAttr.value);
+        if (target.fragment !== null) labelBooks.add(bookAttr.value);
+      }
+    } catch {
+      // The main validation pass reports the parse failure with source context.
+    }
+  }
+
+  selectedCorpusDependencies = { routeBooks, labelBooks };
+  return selectedCorpusDependencies;
+}
+
+// v4.6.0 (issue #76 Layer 3b): chapter-route shadow warning. Detect a
+// consumer-owned `src/pages/chapters/[...slug].astro` that shadows the
+// scaffold v4.3.0+ auto-injected route. Non-blocking — emits to stderr,
+// validate continues normally. Suppressed when the consumer explicitly
+// disabled the scaffold's chapter route (intentional override).
+//
+// Edge cases per issue #76:
+//   file + routes.chapters undefined/true → WARN
+//   file + routes.chapters: false         → silent (intentional override)
+//   no file (any routes config)           → silent
+//
+// Heuristic for "routes.chapters: false": regex-grep astro.config.mjs for
+// the literal `chapters: false`. Light-touch detection that matches the
+// issue's warning-not-error intent; consumers wanting a stricter detector
+// can run `astro check` separately.
+{
+  const consumerChapterRoute = resolve(ROOT, 'src/pages/chapters/[...slug].astro');
+  if (existsSync(consumerChapterRoute)) {
+    const astroConfigPath = resolve(ROOT, 'astro.config.mjs');
+    let chaptersDisabled = false;
+    if (existsSync(astroConfigPath)) {
+      const astroConfig = readFileSync(astroConfigPath, 'utf8');
+      // Match `chapters: false` (with optional whitespace) inside a routes
+      // object. Slight false-positive risk on commented-out code; acceptable
+      // for a non-blocking warning.
+      chaptersDisabled = /\bchapters\s*:\s*false\b/.test(astroConfig);
+    }
+    if (!chaptersDisabled) {
+      const message =
+        (BOOK_SELECTION.corpus
+          ? '[book:corpus] validate: WARN consumer-owned chapter route at '
+          : '\n⚠ Consumer-owned chapter route at ') +
+        `src/pages/chapters/[...slug].astro\n` +
+        `  shadows the scaffold v4.3.0+ auto-injected route. Either:\n` +
+        `  • Delete the consumer file to defer to the scaffold (recommended), OR\n` +
+        `  • Set 'routes: { chapters: false }' in defineBookConfig to keep\n` +
+        `    your override (intentional).\n` +
+        `  See: package/recipes/18-chapter-route-ownership.md\n`;
+      writeStderr(`${message}\n`);
+      context.notices.push({
+        severity: 'warning',
+        code: 'consumer_chapter_route_shadow',
+        message: 'Consumer-owned chapter route shadows the scaffold route.',
+        book: BOOK_SELECTION.corpus ? 'corpus' : null,
+        file: 'src/pages/chapters/[...slug].astro',
+        line: 1,
+      });
+    }
+  }
+}
+
+// v4.20.0 (issue #129): the same shadow warning for the landing route. A
+// consumer-owned `src/pages/index.astro` collides with the scaffold's
+// auto-injected `/` (Astro warns today and has announced a hard error in a
+// future major). The escape hatch already exists — `routes: { landing: false }`
+// — this check makes it discoverable before Astro's break lands. Same edge
+// cases + heuristic as the chapters check above.
+{
+  const consumerLanding = resolve(ROOT, 'src/pages/index.astro');
+  if (existsSync(consumerLanding)) {
+    const astroConfigPath = resolve(ROOT, 'astro.config.mjs');
+    let landingDisabled = false;
+    if (existsSync(astroConfigPath)) {
+      const astroConfig = readFileSync(astroConfigPath, 'utf8');
+      landingDisabled = /\blanding\s*:\s*false\b/.test(astroConfig);
+    }
+    if (!landingDisabled) {
+      const message =
+        (BOOK_SELECTION.corpus
+          ? '[book:corpus] validate: WARN consumer-owned landing page at '
+          : '\n⚠ Consumer-owned landing page at ') +
+        `src/pages/index.astro shadows the\n` +
+        `  scaffold's auto-injected "/" route. Your page wins today, but Astro\n` +
+        `  has announced route collisions become a HARD ERROR in a future\n` +
+        `  version. Set 'routes: { landing: false }' in defineBookConfig to\n` +
+        `  declare the override and silence the collision.\n` +
+        `  See: package/recipes/18-chapter-route-ownership.md\n`;
+      writeStderr(`${message}\n`);
+      context.notices.push({
+        severity: 'warning',
+        code: 'consumer_landing_route_shadow',
+        message: 'Consumer-owned landing page shadows the scaffold route.',
+        book: BOOK_SELECTION.corpus ? 'corpus' : null,
+        file: 'src/pages/index.astro',
+        line: 1,
+      });
+    }
+  }
+}
+
+const errors = context.errors;
+const warnings = context.warnings;
+let ACTIVE_BOOK_ID = BOOK_SELECTION.corpus ? 'corpus' : null;
+const fail = (file, line, msg, book = ACTIVE_BOOK_ID) => errors.push({ file, line, msg, book });
+const warn = (file, line, msg, book = ACTIVE_BOOK_ID) => warnings.push({ file, line, msg, book });
+const invalidFrontmatterFiles = new Set();
+function recordFrontmatterFailure(error, file, book) {
+  invalidFrontmatterFiles.add(file);
+  fail(
+    file,
+    error?.frontmatterLine ?? 1,
+    error?.frontmatterDetail ?? `Invalid YAML frontmatter: ${error?.message ?? error}`,
+    book,
+  );
+}
+
+// ===== Self-heal missing generated artifacts (#186) =====
+// These files are intentionally gitignored. Direct `book-scaffold validate`
+// bypasses npm's prevalidate lifecycle, so rebuild each missing artifact before
+// loading it. In selected corpus runs, placeholder-empty requested/dependency
+// namespaces are also materialized to keep results independent of run order.
+// Child diagnostics and failures are propagated verbatim instead of becoming
+// downstream unknown-id noise.
+async function regenerate(scriptName, artifact, book = null, reason = null) {
+  const prefix = BOOK_SELECTION.corpus ? '[book:corpus] ' : '';
+  const progress =
+    `${prefix}validate: ${reason ?? `${artifact} is missing — regenerating via ${scriptName} (#186)`}\n`;
+  writeStdout(progress);
+  const request = { scriptName, artifact, book, reason, root: ROOT, env: ENV };
+  context.regenerationRequests.push({ scriptName, artifact, book, reason });
+  await options.onProgress?.({ type: 'artifact-regeneration', ...request });
+  if (typeof options.regenerateArtifact !== 'function') {
+    const message = `${artifact} requires regeneration via ${scriptName}.`;
+    abort(
+      'artifact',
+      message,
+      1,
+      `${prefix}validate: fatal: ${message} Supply regenerateArtifact or run the producer first.\n`,
+    );
+  }
+  let result;
+  try {
+    result = (await options.regenerateArtifact(request)) ?? { status: 0 };
+  } catch (error) {
+    result = { status: 1, error };
+  }
+  if (result?.stdout) writeStdout(result.stdout);
+  if (result?.stderr) writeStderr(result.stderr);
+  const status = result.status === undefined ? 0 : result.status;
+  if (result.error || status !== 0) {
+    const detail = result.error ? `: ${result.error.message}` : '';
+    const exitCode = status ?? 1;
+    const message = `${scriptName} failed (exit ${exitCode})${detail} — cannot self-heal.`;
+    abort(
+      'artifact',
+      message,
+      exitCode,
+      `${prefix}validate: ${message}\n`,
+    );
+  }
+}
+
+async function readableCorpusArtifactBooks(path, artifact) {
+  try {
+    const value = JSON.parse(await readFile(path, 'utf8'));
+    return assertCorpusEnvelope(
+      value,
+      BOOK_SELECTION.corpus,
+      artifact,
+      isRecord,
+    ).books;
+  } catch {
+    return null;
+  }
+}
+
+function isEmptyRecord(value) {
+  return isRecord(value) && Object.keys(value).length === 0;
+}
+
+const labelsPath = join(DATA_DIR, 'labels.json');
+const materializedLabels = new Set();
+let materializedAllLabels = false;
+if (!existsSync(labelsPath)) {
+  await regenerate(
+    'build-labels.mjs',
+    'src/data/labels.json',
+    BOOK_SELECTION.requestedBook,
+  );
+  if (BOOK_SELECTION.requestedBook) materializedLabels.add(BOOK_SELECTION.requestedBook);
+  else if (BOOK_SELECTION.corpus) materializedAllLabels = true;
+}
+if (BOOK_SELECTION.requestedBook) {
+  const dependencies = await resolveSelectedCorpusDependencies();
+  const books = await readableCorpusArtifactBooks(labelsPath, 'src/data/labels.json');
+  if (books) {
+    for (const book of dependencies.labelBooks) {
+      if (materializedLabels.has(book) || !isEmptyRecord(books[book])) continue;
+      await regenerate(
+        'build-labels.mjs',
+        'src/data/labels.json',
+        book,
+        `${book === BOOK_SELECTION.requestedBook
+          ? `selected book ${book}`
+          : `local BookLink from ${BOOK_SELECTION.requestedBook} requires ${book}`} ` +
+          'has an empty labels namespace — materializing it (#186)',
+      );
+    }
+  }
+} else if (BOOK_SELECTION.corpus && !materializedAllLabels) {
+  const books = await readableCorpusArtifactBooks(labelsPath, 'src/data/labels.json');
+  if (books && BOOK_SELECTION.corpus.books.some((book) => isEmptyRecord(books[book.id]))) {
+    await regenerate(
+      'build-labels.mjs',
+      'src/data/labels.json',
+      null,
+      'corpus labels contain placeholder-empty namespaces — rebuilding all books (#186)',
+    );
+  }
+}
+
+const referencesPath = join(DATA_DIR, 'references.json');
+let materializedReferences = false;
+let materializedAllReferences = false;
+if (!existsSync(referencesPath)) {
+  await regenerate(
+    'build-bib.mjs',
+    'src/data/references.json',
+    BOOK_SELECTION.requestedBook,
+  );
+  materializedReferences = BOOK_SELECTION.requestedBook !== null;
+  materializedAllReferences = Boolean(BOOK_SELECTION.corpus && !BOOK_SELECTION.requestedBook);
+}
+if (BOOK_SELECTION.requestedBook) {
+  if (!materializedReferences) {
+    const books = await readableCorpusArtifactBooks(
+      referencesPath,
+      'src/data/references.json',
+    );
+    if (books && isEmptyRecord(books[BOOK_SELECTION.requestedBook])) {
+      await regenerate(
+        'build-bib.mjs',
+        'src/data/references.json',
+        BOOK_SELECTION.requestedBook,
+        `selected book ${BOOK_SELECTION.requestedBook} has an empty references namespace — ` +
+          'materializing it (#186)',
+      );
+    }
+  }
+} else if (BOOK_SELECTION.corpus && !materializedAllReferences) {
+  const books = await readableCorpusArtifactBooks(
+    referencesPath,
+    'src/data/references.json',
+  );
+  if (books && BOOK_SELECTION.corpus.books.some((book) => isEmptyRecord(books[book.id]))) {
+    await regenerate(
+      'build-bib.mjs',
+      'src/data/references.json',
+      null,
+      'corpus references contain placeholder-empty namespaces — rebuilding all books (#186)',
+    );
+  }
+}
+
+// ===== Load reference data (graceful when missing) =====
+async function loadJson(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+async function loadGeneratedArtifact(name) {
+  const path = join(DATA_DIR, name);
+  if (!BOOK_SELECTION.corpus) return loadJson(path);
+  try {
+    const parsed = JSON.parse(await readFile(path, 'utf8'));
+    return assertCorpusEnvelope(parsed, BOOK_SELECTION.corpus, `src/data/${name}`, isRecord);
+  } catch (error) {
+    const message =
+      `${error?.message ?? error}. ` +
+      `Run book-scaffold ${name === 'labels.json' ? 'build-labels' : 'build-bib'} ` +
+      'to regenerate the corpus envelope.';
+    abort(
+      'artifact',
+      message,
+      1,
+      `[book:corpus] validate: fatal: ${message}\n`,
+    );
+  }
+}
+
+const refsArtifact = await loadGeneratedArtifact('references.json');
+const labelsArtifact = await loadGeneratedArtifact('labels.json');
+
+// #147: eagerly load every labels index explicitly declared by the evaluated
+// siblingBooks registry. Unlike this book's generated labels.json, sibling
+// indexes are vendored inputs: never self-heal or silently replace them. A
+// missing, unreadable, malformed, or non-object index is a configuration error
+// even when no current chapter happens to reference that sibling.
+const siblingLabelIndexes = new Map();
+for (const [book, entry] of Object.entries(TOOLING_CONFIG.siblingBooks)) {
+  if (typeof entry === 'string' || entry.labels === undefined) continue;
+  const indexPath = resolve(ROOT, entry.labels);
+  try {
+    const index = JSON.parse(await readFile(indexPath, 'utf8'));
+    if (index === null || typeof index !== 'object' || Array.isArray(index)) {
+      throw new Error('top-level JSON value must be an object');
+    }
+    siblingLabelIndexes.set(book, { index, configuredPath: entry.labels });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    fail(
+      'astro.config',
+      1,
+      `siblingBooks.${book}.labels (${JSON.stringify(entry.labels)}) is missing, unreadable, or invalid: ${detail}. ` +
+        'Vendor a readable sibling labels.json at that path or remove labels to opt out with a warning.',
+    );
+  }
+}
+
+// ===== Collect chapter files =====
+// v3.7.1 (closes #52): walkMdx (in ./walk-mdx.mjs) is a recursive readdir
+// walker that replaces the previous `glob` import from `node:fs/promises`.
+// The `glob` API was added in Node 22 but consumer CI templates ship
+// Node 20 — `npm run validate` crashed on every consumer's prebuild hook.
+// Walker uses readdir + path only; works on Node 18+.
+const chapterFiles = context.chapterFiles;
+const chapterBookByFile = new Map();
+const chapterCountsByBook = context.chapterCountsByBook;
+if (BOOK_SELECTION.corpus) {
+  for (const book of BOOK_SELECTION.books) {
+    let count = 0;
+    for await (const file of walkMdx(join(CHAPTERS_DIR, book.id))) {
+      if (file.split('/').pop().startsWith('_')) continue;
+      const scoped = `${book.id}/${file}`;
+      chapterFiles.push(scoped);
+      chapterBookByFile.set(scoped, book.id);
+      count += 1;
+    }
+    chapterCountsByBook.set(book.id, count);
+  }
+} else {
+  for await (const file of walkMdx(CHAPTERS_DIR)) {
+    if (!file.split('/').pop().startsWith('_')) chapterFiles.push(file);
+  }
+}
+
+function bookArtifacts(rel) {
+  const book = chapterBookByFile.get(rel) ?? null;
+  if (!book) return { book: null, refs: refsArtifact, labels: labelsArtifact };
+  return {
+    book,
+    refs: refsArtifact.books[book],
+    labels: labelsArtifact.books[book],
+  };
+}
+
+// ===== Build slug set from chapter filenames (for internal-link check) =====
+const validSlugs = new Set(
+  BOOK_SELECTION.corpus
+    ? []
+    : chapterFiles.map((file) => file.replace(/\.(md|mdx)$/, '')),
+);
+if (BOOK_SELECTION.corpus) {
+  // Full validation indexes every book. A selected run indexes its own book
+  // plus literal chapter-link dependencies only, so unrelated malformed
+  // content cannot make `validate --book <id>` cache-dependent.
+  const dependencies = await resolveSelectedCorpusDependencies();
+  for (const book of BOOK_SELECTION.corpus.books.filter((candidate) =>
+    dependencies.routeBooks.has(candidate.id))) {
+    for await (const file of walkMdx(join(CHAPTERS_DIR, book.id))) {
+      if (!file.split('/').pop().startsWith('_')) {
+        const fileLabel = `[book:${book.id}] ${book.id}/${file}`;
+        const source = await readFile(join(CHAPTERS_DIR, book.id, file), 'utf8');
+        try {
+          const localId = frontmatterSlug(source, fileLabel) ?? file.replace(/\.(md|mdx)$/, '');
+          validSlugs.add(`${book.id}/${localId}`);
+        } catch (error) {
+          recordFrontmatterFailure(error, `${book.id}/${file}`, book.id);
+        }
+      }
+    }
+  }
+}
+const validTopLevelRoutes = new Set(
+  BOOK_SELECTION.corpus
+    ? ['/', '/chapters/', '/search/']
+    : ['/', '/chapters/', '/references/', '/search/', '/print/', '/convergence/'],
+);
+const KNOWN_CORPUS_APPARATUS_ROUTES = new Set([
+  'references',
+  'print',
+  'convergence',
+  'tips',
+  'exercises',
+  'glossary',
+  'practice-exam',
+  'flashcards',
+  'answers',
+]);
+if (BOOK_SELECTION.corpus) {
+  for (const book of BOOK_SELECTION.corpus.books) {
+    validTopLevelRoutes.add(`/${book.id}/`);
+    validTopLevelRoutes.add(`/chapters/${book.id}/`);
+    for (const route of book.apparatus ?? TOOLING_CONFIG.apparatusRoutes) {
+      validTopLevelRoutes.add(`/${book.id}/${route}/`);
+    }
+  }
+}
+
+// ===== Pattern helpers for component-specific checks =====
+const RE_CITE = /<Cite[^>]+key=["']([^"']+)["']/g;
+const RE_XREF = /<XRef[^>]+id=["']([^"']+)["']/g;
+const RE_FIGURE = /<Figure[^>]+src=["']([^"']+)["']/g;
+const RE_CODEREF = /<CodeRef[^>]+path=["']([^"']+)["'](?:[^>]*line=\{(\d+)\})?(?:[^>]*lineEnd=\{(\d+)\})?/g;
+// #121: a <Theorem> opening tag — capture its attributes to assert a
+// resolvable kind= (or legacy type=) is present.
+const RE_THEOREM = /<Theorem\b([^>]*)>/g;
+// #96/#147: BookLink attributes must be read structurally. An opening-tag
+// regex stops at `>` inside a quoted value or expression and can mistake text
+// inside another prop for a real book=/to= assignment.
+const mdxParser = unified().use(remarkParse).use(remarkMdx);
+if (MATH_ENABLED) mdxParser.use(remarkMath);
+
+async function fileExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function lineOf(content, idx) {
+  return content.slice(0, idx).split('\n').length;
+}
+
+const ASTRO_BASE = normalizeAstroBase(TOOLING_CONFIG.base);
+
+function authoredFormat(file) {
+  return extname(file).toLowerCase() === '.md' ? 'md' : 'mdx';
+}
+
+function collectAuthoredTargets(file, content) {
+  try {
+    return findAuthoredTargets(content, {
+      format: authoredFormat(file),
+      math: MATH_ENABLED,
+    });
+  } catch (error) {
+    const line = error?.line ?? error?.place?.start?.line ?? error?.position?.start?.line ?? 1;
+    const detail = String(error?.reason ?? error?.message ?? error).split('\n')[0];
+    fail(file, line, `Could not parse authored links as ${authoredFormat(file).toUpperCase()}: ${detail}`);
+    return [];
+  }
+}
+
+function validateAuthoredTargets(file, content, targets) {
+  for (const violation of targets) {
+    if (!rootTargetEscapesBase(violation.target, ASTRO_BASE)) continue;
+    const suggested = suggestBaseContainedTarget(violation.target, ASTRO_BASE);
+    fail(
+      file,
+      lineOf(content, violation.index),
+      `Authored ${violation.kind} ${JSON.stringify(violation.target)} escapes configured Astro base ` +
+        `${JSON.stringify(ASTRO_BASE)}. Use ${JSON.stringify(suggested)}, ` +
+        'import.meta.env.BASE_URL in JSX, or a base-aware component. ' +
+        'Validation does not rewrite authored URLs (#190).',
+    );
+  }
+}
+
+function validateInternalMarkdownLinks(file, content, targets) {
+  for (const authored of targets) {
+    if (authored.kind !== 'Markdown link destination') continue;
+    const pathname = rootTargetPathname(authored.target);
+    if (pathname === null) continue;
+    const baseRelativeTarget =
+      ASTRO_BASE !== '/' && (pathname === ASTRO_BASE || pathname.startsWith(`${ASTRO_BASE}/`))
+        ? pathname.slice(ASTRO_BASE.length) || '/'
+        : pathname;
+    const target = baseRelativeTarget.replace(/\/$/, '') || '/';
+    if (validTopLevelRoutes.has(`${target}/`) || validTopLevelRoutes.has(target)) continue;
+    const chMatch = target.match(/^\/chapters\/(.+)$/);
+    if (chMatch && validSlugs.has(chMatch[1])) continue;
+    warn(
+      file,
+      lineOf(content, authored.index),
+      `Internal link ${JSON.stringify(authored.target)} — target may not resolve (check spelling or route)`,
+    );
+  }
+}
+
+/**
+ * Return a statically knowable n= value. Quoted strings and braced
+ * string/numeric literals are safe to compare; identifiers, calls,
+ * interpolation, and all other expressions are deliberately skipped.
+ */
+function literalTheoremNumber(attrs) {
+  const quoted = attrs.match(/\bn\s*=\s*(["'])(.*?)\1/);
+  if (quoted) return quoted[2];
+
+  const braced = attrs.match(/\bn\s*=\s*\{\s*([^}]*?)\s*\}/);
+  if (!braced) return null;
+  const expression = braced[1].trim();
+  const stringLiteral = expression.match(/^(["'`])([\s\S]*)\1$/);
+  if (stringLiteral) {
+    if (stringLiteral[1] === '`' && stringLiteral[2].includes('${')) return null;
+    return stringLiteral[2];
+  }
+  if (/^[+-]?(?:\d+(?:\.\d+)?|\.\d+)$/.test(expression)) {
+    return String(Number(expression));
+  }
+  return null;
+}
+
+/** Yield MDX JSX elements with an exact component name, excluding examples in
+ * fenced/inline code and strings in expressions by construction. */
+function* mdxElements(node, name) {
+  if (
+    (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') &&
+    node.name === name
+  ) {
+    yield node;
+  }
+  if (!Array.isArray(node.children)) return;
+  for (const child of node.children) yield* mdxElements(child, name);
+}
+
+function expressionString(value) {
+  const program = value?.data?.estree;
+  if (program?.body?.length !== 1 || program.body[0].type !== 'ExpressionStatement') {
+    return null;
+  }
+  const expression = program.body[0].expression;
+  if (expression.type === 'Literal' && typeof expression.value === 'string') {
+    return expression.value;
+  }
+  if (expression.type === 'TemplateLiteral' && expression.expressions.length === 0) {
+    return expression.quasis[0]?.value?.cooked ?? expression.quasis[0]?.value?.raw ?? '';
+  }
+  return null;
+}
+
+/**
+ * Evaluate one JSX prop in source order. Later explicit attributes override an
+ * earlier spread; a later spread makes the value dynamic, exactly as JSX does.
+ * Literal ESTree values are already decoded, so entities and JS escapes cannot
+ * disguise the href that the component receives at runtime.
+ */
+function mdxStringProp(element, name) {
+  let result = { present: false, literal: false, value: null, source: 'absent' };
+  for (const attribute of element.attributes) {
+    if (attribute.type === 'mdxJsxExpressionAttribute') {
+      result = { present: true, literal: false, value: null, source: 'spread' };
+      continue;
+    }
+    if (attribute.type !== 'mdxJsxAttribute' || attribute.name !== name) continue;
+    if (typeof attribute.value === 'string') {
+      result = { present: true, literal: true, value: attribute.value, source: 'attribute' };
+      continue;
+    }
+    const value = expressionString(attribute.value);
+    result = value === null
+      ? { present: true, literal: false, value: null, source: 'expression' }
+      : { present: true, literal: true, value, source: 'attribute' };
+  }
+  return result;
+}
+
+/**
+ * Canonical comparison shape for a sibling labels href. The generated index
+ * intentionally omits the deployment base, so only normalize route seams:
+ * leading slashes and the optional trailing slash immediately before `#`.
+ */
+function normalizeSiblingTarget(value) {
+  const hash = value.indexOf('#');
+  if (hash < 0 || hash === value.length - 1) return null;
+  const fragment = value.slice(hash + 1);
+  const path = value.slice(0, hash).trim().replace(/^\/+/, '').replace(/\/+$/, '');
+  return { fragment, href: `${path}#${fragment}` };
+}
+
+/**
+ * Heading keys in labels.json are deliberately opaque and path-qualified so
+ * `#summary` can exist in every chapter. Resolve sibling targets from href
+ * values, while remaining compatible with historical component-id keys.
+ */
+function siblingTargetCandidates(index, fragment) {
+  const candidates = [];
+  for (const [key, entry] of Object.entries(index)) {
+    if (entry === null || typeof entry !== 'object' || typeof entry.href !== 'string') continue;
+    const normalized = normalizeSiblingTarget(entry.href);
+    if (normalized?.fragment === fragment) {
+      candidates.push({ key, href: entry.href, normalized });
+    }
+  }
+  return candidates;
+}
+
+function normalizeCorpusTarget(book, to) {
+  if (typeof to !== 'string' || to.trim().length === 0) {
+    return { error: 'target must be non-empty' };
+  }
+  if (to !== to.trim()) return { error: 'surrounding whitespace is not allowed' };
+  if (/^[a-z][a-z0-9+.-]*:/i.test(to) || to.startsWith('/') || to.includes('\\')) {
+    return { error: 'absolute URLs and paths are not allowed' };
+  }
+  if (/[\u0000-\u001f\u007f]/.test(to)) return { error: 'control characters are not allowed' };
+
+  const query = to.indexOf('?');
+  const hash = to.indexOf('#');
+  const suffixIndex = [query, hash]
+    .filter((index) => index >= 0)
+    .reduce((minimum, index) => Math.min(minimum, index), to.length);
+  const path = to.slice(0, suffixIndex).replace(/\/+$/, '');
+  if (!path) return { error: 'query-only and fragment-only targets are not allowed' };
+  const segments = path.split('/');
+  if (segments.some((segment) => segment.length === 0)) {
+    return { error: 'empty path segments are not allowed' };
+  }
+  for (const segment of segments) {
+    let decoded;
+    try {
+      decoded = decodeURIComponent(segment);
+    } catch {
+      return { error: 'malformed percent encoding' };
+    }
+    if (decoded === '.' || decoded === '..' || decoded.includes('/') || decoded.includes('\\')) {
+      return { error: 'path traversal is not allowed' };
+    }
+  }
+
+  const localPath = segments.join('/');
+  const canonicalPath = localPath === 'chapters'
+    ? `chapters/${book.id}`
+    : localPath.startsWith('chapters/')
+      ? `chapters/${book.id}/${localPath.slice('chapters/'.length)}`
+      : `${book.id}/${localPath}`;
+  const fragment = hash >= 0 ? to.slice(hash + 1) : null;
+  return {
+    error: null,
+    localPath,
+    canonicalPath,
+    fragment,
+    href: fragment ? `${canonicalPath}#${fragment}` : canonicalPath,
+    chapterSlug: localPath.startsWith('chapters/')
+      ? `${book.id}/${localPath.slice('chapters/'.length)}`
+      : null,
+  };
+}
+
+// ===== Run all checks on each chapter =====
+for (const rel of chapterFiles) {
+  const abs = join(CHAPTERS_DIR, rel);
+  const content = await readFile(abs, 'utf8');
+  const artifacts = bookArtifacts(rel);
+  const { refs, labels } = artifacts;
+  ACTIVE_BOOK_ID = artifacts.book;
+  if (artifacts.book && !invalidFrontmatterFiles.has(rel)) {
+    try {
+      const legacy = legacyFrontmatterBook(content, `[book:${artifacts.book}] ${rel}`);
+      if (legacy && legacy.value !== artifacts.book) {
+        fail(
+          rel,
+          legacy.line,
+          `frontmatter book ${JSON.stringify(legacy.value)} does not match ` +
+            `path-derived corpus book ${JSON.stringify(artifacts.book)}.`,
+        );
+      }
+    } catch (error) {
+      recordFrontmatterFailure(error, rel, artifacts.book);
+    }
+  }
+  const authoredTargets = collectAuthoredTargets(rel, content);
+
+  // 10. Root-absolute authored targets under a non-root Astro base (#190).
+  //     Structural parsing covers Markdown link/image destinations, HTML
+  //     href/src, and decoded static JSX strings while excluding code examples.
+  validateAuthoredTargets(rel, content, authoredTargets);
+
+  let bookLinks = [];
+  if (content.includes('<BookLink')) {
+    try {
+      bookLinks = [...mdxElements(mdxParser.parse(content), 'BookLink')];
+    } catch (error) {
+      const line = error?.position?.start?.line ?? error?.line ?? 1;
+      fail(
+        rel,
+        line,
+        `Cannot structurally validate <BookLink>: ${error?.reason ?? error?.message ?? error}`,
+      );
+    }
+  }
+
+  // 1. Cite keys (academic profile only — tools profile uses YAML manifest)
+  if (PROFILE === 'academic') {
+    for (const m of content.matchAll(RE_CITE)) {
+      if (!refs[m[1]]) fail(rel, lineOf(content, m.index), `Unknown bibkey "${m[1]}" — not in references.json`);
+    }
+  }
+
+  // 2. XRef ids
+  for (const m of content.matchAll(RE_XREF)) {
+    if (!labels[m[1]]) fail(rel, lineOf(content, m.index), `Unknown XRef id "${m[1]}" — not in labels.json`);
+  }
+
+  // 3. Figure src exists in public/
+  for (const m of content.matchAll(RE_FIGURE)) {
+    const src = m[1];
+    if (src.startsWith('http')) continue; // external image
+    const path = src.startsWith('/') ? join(PUBLIC_DIR, src) : join(dirname(abs), src);
+    if (!(await fileExists(path))) {
+      fail(rel, lineOf(content, m.index), `Figure src "${src}" not found at ${path}`);
+    }
+  }
+
+  // 4. Internal Markdown links resolve. Reuse the structural authored-target
+  //    traversal so code examples and comments cannot create false warnings.
+  validateInternalMarkdownLinks(rel, content, authoredTargets);
+
+  // 5. CodeRef path + line bounds (only when BOOK_REPO_ROOT set)
+  if (REPO_ROOT) {
+    for (const m of content.matchAll(RE_CODEREF)) {
+      const [, path, lineStart, lineEnd] = m;
+      const abs2 = resolve(REPO_ROOT, path);
+      if (!(await fileExists(abs2))) {
+        fail(rel, lineOf(content, m.index), `CodeRef path "${path}" not found at ${abs2}`);
+        continue;
+      }
+      if (lineStart) {
+        const fileLineCount = (await readFile(abs2, 'utf8')).split('\n').length;
+        const lo = Number(lineStart);
+        const hi = lineEnd ? Number(lineEnd) : lo;
+        if (lo > fileLineCount || hi > fileLineCount) {
+          fail(rel, lineOf(content, m.index), `CodeRef line ${lo}-${hi} exceeds file length (${fileLineCount}) in "${path}"`);
+        }
+      }
+    }
+  }
+
+  // 6. Theorem requires a resolvable kind (#121) — kind= canonical, type=
+  //    legacy alias. Catches the silent-empty-label / build-throw case at the
+  //    earliest gate. (Value typos are caught at build by theoremLabel's throw.)
+  //    Plus (#126): an id'd <Theorem> without a label= override auto-numbers
+  //    from labels.json — an id absent from the index silently renders the
+  //    heading UNNUMBERED (no [?id] placeholder, unlike <XRef>). Fail loud to
+  //    restore symmetry with check #2. (A label= override opts out → number:null.)
+  for (const m of content.matchAll(RE_THEOREM)) {
+    const attrs = m[1];
+    if (!/\b(?:kind|type)\s*=/.test(attrs)) {
+      fail(
+        rel,
+        lineOf(content, m.index),
+        `<Theorem> has no kind= (or legacy type=) — renders an empty label / throws at build. Add e.g. kind="theorem".`,
+      );
+    }
+    const thmId = attrs.match(/\bid=["']([^"']+)["']/);
+    const hasLabelOverride = /\blabel\s*=/.test(attrs);
+    if (thmId && !hasLabelOverride && !labels[thmId[1]]) {
+      fail(
+        rel,
+        lineOf(content, m.index),
+        `<Theorem id="${thmId[1]}"> — not in labels.json; heading silently renders unnumbered. Run build:labels, or fix the id.`,
+      );
+    }
+    // #176: compare only literal n= values. Dynamic expressions cannot be
+    // evaluated reliably by this intentionally regex-based validator, and a
+    // label= override explicitly opts out of labels.json auto-numbering.
+    const explicitNumber = hasLabelOverride ? null : literalTheoremNumber(attrs);
+    const indexedNumber = thmId ? labels[thmId[1]]?.number : null;
+    if (
+      thmId &&
+      explicitNumber !== null &&
+      indexedNumber != null &&
+      explicitNumber !== String(indexedNumber)
+    ) {
+      fail(
+        rel,
+        lineOf(content, m.index),
+        `<Theorem id="${thmId[1]}" n="${explicitNumber}"> — labels.json numbers it ` +
+          `${indexedNumber}, and the rendered heading + every XRef use the index. ` +
+          'Drop the stale n= (auto-numbering wins) or re-run build:labels.',
+      );
+    }
+  }
+
+  // 7. BookLink (#96/#147): structural props + evaluated registry membership,
+  //    then literal path/fragment validation against a declared vendored index.
+  //    Dynamic values and URL-only compatibility entries are explicit warnings
+  //    rather than guessed validations.
+  for (const element of bookLinks) {
+    const line = element.position?.start?.line ?? 1;
+    const bookAttr = mdxStringProp(element, 'book');
+    const toAttr = mdxStringProp(element, 'to');
+
+    if (bookAttr.source === 'spread' || toAttr.source === 'spread') {
+      warn(
+        rel,
+        line,
+        '<BookLink> validation skipped: a dynamic prop spread may supply or override book=/to=, so the target cannot be proven statically.',
+      );
+      continue;
+    }
+    if (!bookAttr.present || !toAttr.present) {
+      fail(rel, line, `<BookLink> requires both book="…" and to="…".`);
+      continue;
+    }
+
+    if (!bookAttr.literal) {
+      warn(
+        rel,
+        line,
+        '<BookLink> target validation skipped: dynamic book= expression cannot be evaluated statically.',
+      );
+      continue;
+    }
+
+    const book = bookAttr.value;
+    const corpusBook = BOOK_SELECTION.corpus?.books.find((candidate) => candidate.id === book);
+    if (corpusBook) {
+      if (!toAttr.literal) {
+        warn(
+          rel,
+          line,
+          `<BookLink book="${book}"> target validation skipped: dynamic to= expression cannot be evaluated statically.`,
+        );
+        continue;
+      }
+
+      const target = normalizeCorpusTarget(corpusBook, toAttr.value);
+      if (target.error) {
+        fail(
+          rel,
+          line,
+          `<BookLink book="${book}" to="${toAttr.value}"> has invalid local corpus target: ` +
+            `${target.error}.`,
+        );
+        continue;
+      }
+
+      if (target.chapterSlug && !validSlugs.has(target.chapterSlug)) {
+        fail(
+          rel,
+          line,
+          `<BookLink book="${book}" to="${toAttr.value}"> — unknown local corpus target ` +
+            `"${target.canonicalPath}".`,
+        );
+        continue;
+      }
+
+      // Exact apparatus roots are known statically and may be checked against
+      // the target book's route set. Nested/custom non-chapter paths remain a
+      // deliberate runtime escape hatch (for example about/team or a custom
+      // glossary detail route), so validate must not reject them merely
+      // because they are absent from the scaffold apparatus registry.
+      if (
+        !target.chapterSlug &&
+        KNOWN_CORPUS_APPARATUS_ROUTES.has(target.localPath) &&
+        !(corpusBook.apparatus ?? TOOLING_CONFIG.apparatusRoutes).includes(target.localPath)
+      ) {
+        fail(
+          rel,
+          line,
+          `<BookLink book="${book}" to="${toAttr.value}"> — local corpus apparatus route ` +
+            `"${target.localPath}" is not enabled for book "${book}".`,
+        );
+        continue;
+      }
+
+      if (target.fragment !== null && target.chapterSlug) {
+        if (target.fragment.length === 0) {
+          fail(
+            rel,
+            line,
+            `<BookLink book="${book}" to="${toAttr.value}"> — local fragment is empty.`,
+          );
+          continue;
+        }
+        const localIndex = labelsArtifact.books[book];
+        const candidates = siblingTargetCandidates(localIndex, target.fragment);
+        if (!candidates.some((candidate) => candidate.normalized.href === target.href)) {
+          const indexedHrefs = candidates.map((candidate) => `"${candidate.href}"`).join(', ');
+          fail(
+            rel,
+            line,
+            `<BookLink book="${book}" to="${toAttr.value}"> — local fragment ` +
+              `"${target.fragment}" does not resolve in labels.json book namespace "${book}"` +
+              (indexedHrefs ? ` (indexed at ${indexedHrefs})` : '') +
+              '.',
+          );
+        }
+      } else if (target.fragment !== null) {
+        // labels.json indexes chapter prose/components only. Runtime accepts
+        // fragments on arbitrary book-local routes, so a non-chapter fragment
+        // cannot be proven (or disproven) from this artifact.
+        warn(
+          rel,
+          line,
+          `<BookLink book="${book}" to="${toAttr.value}"> non-chapter fragment ` +
+            'validation skipped; the target route owns its anchors.',
+        );
+      }
+      continue;
+    }
+
+    const registered = Object.prototype.hasOwnProperty.call(TOOLING_CONFIG.siblingBooks, book);
+    if (!registered) {
+      const known = [
+        ...(BOOK_SELECTION.corpus?.books.map((candidate) => candidate.id) ?? []),
+        ...Object.keys(TOOLING_CONFIG.siblingBooks),
+      ];
+      fail(
+        rel,
+        line,
+        BOOK_SELECTION.corpus
+          ? `<BookLink book="${book}"> — not a registered local corpus or sibling book ` +
+              `(${known.join(', ') || 'none'}). Register it or fix the key.`
+          : `<BookLink book="${book}"> — not in evaluated defineBookConfig siblingBooks ` +
+              `(${Object.keys(TOOLING_CONFIG.siblingBooks).join(', ') || 'none'}). ` +
+              'Register it or fix the key.',
+      );
+      continue;
+    }
+    const siblingEntry = TOOLING_CONFIG.siblingBooks[book];
+
+    if (!toAttr.literal) {
+      warn(
+        rel,
+        line,
+        `<BookLink book="${book}"> target validation skipped: dynamic to= expression cannot be evaluated statically.`,
+      );
+      continue;
+    }
+
+    const target = normalizeSiblingTarget(toAttr.value);
+    if (!target) {
+      warn(
+        rel,
+        line,
+        `<BookLink book="${book}" to="${toAttr.value}"> has no static #fragment; sibling labels validation skipped.`,
+      );
+      continue;
+    }
+
+    if (typeof siblingEntry === 'string' || siblingEntry.labels === undefined) {
+      warn(
+        rel,
+        line,
+        `<BookLink book="${book}" to="${toAttr.value}"> target validation skipped: ` +
+          'the siblingBooks entry is URL-only. Use { url, labels } to enable vendored-label validation.',
+      );
+      continue;
+    }
+
+    const loaded = siblingLabelIndexes.get(book);
+    if (!loaded) continue; // A config-level error was already recorded above.
+
+    const candidates = siblingTargetCandidates(loaded.index, target.fragment);
+    if (candidates.some((candidate) => candidate.normalized.href === target.href)) {
+      continue;
+    }
+
+    if (candidates.length === 0) {
+      // Preserve the actionable diagnostic for a malformed historical entry
+      // whose key is the literal fragment. Opaque heading keys are found by
+      // valid href values and never need to be decoded here.
+      const legacyEntry = loaded.index[target.fragment];
+      if (
+        Object.prototype.hasOwnProperty.call(loaded.index, target.fragment) &&
+        (legacyEntry === null ||
+          typeof legacyEntry !== 'object' ||
+          typeof legacyEntry.href !== 'string')
+      ) {
+        fail(
+          rel,
+          line,
+          `<BookLink book="${book}" to="${toAttr.value}"> — ${loaded.configuredPath} entry ` +
+            `"${target.fragment}" has no string href; re-vendor a valid sibling labels.json.`,
+        );
+        continue;
+      }
+      fail(
+        rel,
+        line,
+        `<BookLink book="${book}" to="${toAttr.value}"> — fragment "${target.fragment}" is not in ` +
+          `${loaded.configuredPath}. Vendor the current sibling labels.json, or fix the target id.`,
+      );
+      continue;
+    }
+
+    const indexedHrefs = candidates.map((candidate) => `"${candidate.href}"`).join(', ');
+    fail(
+      rel,
+      line,
+      `<BookLink book="${book}" to="${toAttr.value}"> — path/fragment does not match ` +
+        `${loaded.configuredPath}, which indexes "${target.fragment}" at ${indexedHrefs}. ` +
+        'Fix to= or refresh the vendored index.',
+    );
+  }
+
+  // <Rationale appendix> in CHAPTER bodies (v4.21.0, #114): same missing-for=
+  // pre-flight as the questions scan below (the for===id rule is
+  // question-file-scoped and doesn't apply here). The component still throws
+  // at build either way; this just catches it at the earliest gate.
+  for (const m of content.matchAll(/<Rationale\b([^>]*)>/g)) {
+    const attrs = m[1];
+    if (/(^|\s)appendix(\s|=|$)/.test(attrs) && !/\bfor\s*=/.test(attrs)) {
+      fail(
+        rel,
+        lineOf(content, m.index),
+        `<Rationale appendix> without for="<question-id>" — no appendix anchor target; throws at build.`,
+      );
+    }
+  }
+
+  // 9. Learning-objective anchor binding (#130). Convention (consumer-defined
+  //    `los` frontmatter, guides-ai-engineering): each `los[].anchor` slug has
+  //    a matching MDX comment marker in the prose binding the objective to its
+  //    section. Both drift directions built + validated green before this
+  //    check, so both fail loud: a declared anchor with no marker (dangling
+  //    objective) and a marker with no declaration (orphan). Scoped to
+  //    chapters that opt into the convention (a `los:` frontmatter key) —
+  //    `los` is not a scaffold schema field, so this can't false-fire on
+  //    books that don't use it. Heuristic, like #8: any indented `anchor:`
+  //    line inside the frontmatter counts as a declaration.
+  {
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const front = fmMatch ? fmMatch[1] : '';
+    if (/^los\s*:/m.test(front)) {
+      const frontOffset = content.indexOf(front);
+      const bodyOffset = fmMatch ? fmMatch[0].length : 0;
+      const body = content.slice(bodyOffset);
+      // Matches both YAML styles: block items (`- anchor: slug` / `anchor: slug`
+      // on its own indented line) and flow/inline maps (`- { text: …, anchor:
+      // slug }`), where the key follows a `{` or `,`. The prefix alternation —
+      // never a bare `.*` — keeps `my-anchor:` from matching as "anchor:".
+      const declared = [
+        ...front.matchAll(
+          /^\s+(?:-\s+|.*[{,]\s*)?anchor\s*:\s*["']?([^"',}\n]+?)["']?\s*(?:[,}].*)?$/gm,
+        ),
+      ];
+      const markers = [...body.matchAll(/\{\s*\/\*\s*anchor:\s*([^\s*]+)\s*\*\/\s*\}/g)];
+      const markerSlugs = new Set(markers.map((m) => m[1]));
+      const declaredSlugs = new Set(declared.map((m) => m[1].trim()));
+      for (const d of declared) {
+        const slug = d[1].trim();
+        if (!markerSlugs.has(slug)) {
+          fail(
+            rel,
+            lineOf(content, frontOffset + d.index),
+            `los anchor "${slug}" has no matching {/* anchor: ${slug} */} marker in the prose — dangling learning objective.`,
+          );
+        }
+      }
+      for (const m of markers) {
+        if (!declaredSlugs.has(m[1])) {
+          fail(
+            rel,
+            lineOf(content, bodyOffset + m.index),
+            `prose anchor marker "${m[1]}" has no matching los[].anchor in the frontmatter — orphan anchor.`,
+          );
+        }
+      }
+    }
+  }
+}
+ACTIVE_BOOK_ID = BOOK_SELECTION.corpus ? 'corpus' : null;
+
+// ===== 8. Questions collection (#112): domain membership + unique ids =====
+//
+// The study-guide `questions` collection (src/content/questions/**) is scanned
+// separately from chapters: a question's frontmatter `domain` must be in the
+// consumer's examDomains registry — an unregistered domain throws at build via
+// assertKnownDomain (route layer); we flag it here, earlier, the same way #7
+// pre-flights BookLink. Question `id`s must also be unique (they're the stable
+// cross-ref key the appendix/flashcards resolve against). Best-effort: when
+// examDomains can't be read from astro.config.mjs, membership is left to the
+// build-time throw.
+let questionsChecked = 0;
+const questionsCheckedByBook = context.questionsCheckedByBook;
+
+if (BOOK_SELECTION.corpus) {
+  const manifestIds = new Set(BOOK_SELECTION.corpus.books.map((book) => book.id));
+  for (const [collection, label] of [
+    ['questions', 'Question'],
+    ['glossary', 'Glossary term'],
+  ]) {
+    const collectionDir = resolve(ROOT, 'src/content', collection);
+    if (!existsSync(collectionDir)) continue;
+    // Collection ownership is path-derived. Scan the complete non-hidden root
+    // even for `--book` so direct files and unknown first segments cannot
+    // silently disappear from every per-book run.
+    for await (const file of walkMdx(collectionDir)) {
+      const owner = file.split('/')[0] ?? '';
+      if (manifestIds.has(owner)) continue;
+      fail(
+        `${collection}/${file}`,
+        1,
+        `${label} content must be nested under a registered corpus book id ` +
+          `(${[...manifestIds].join(' | ')}); found first segment ${JSON.stringify(owner)}.`,
+        'corpus',
+      );
+    }
+  }
+}
+
+{
+  const QUESTIONS_DIR = resolve(ROOT, 'src/content/questions');
+  if (existsSync(QUESTIONS_DIR)) {
+    // examDomains registry from astro.config.mjs (best-effort, mirrors siblingBooks).
+    let examDomains = null;
+    const astroConfigPath = resolve(ROOT, 'astro.config.mjs');
+    if (existsSync(astroConfigPath)) {
+      const block = readFileSync(astroConfigPath, 'utf8').match(/examDomains\s*:\s*\[([^\]]*)\]/);
+      if (block) {
+        examDomains = new Set([...block[1].matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1]));
+      }
+    }
+
+    const runs = BOOK_SELECTION.corpus
+      ? BOOK_SELECTION.books.map((book) => ({
+          book,
+          dir: join(QUESTIONS_DIR, book.id),
+          prefix: `questions/${book.id}`,
+        }))
+      : [{ book: null, dir: QUESTIONS_DIR, prefix: 'questions' }];
+
+    for (const run of runs) {
+      ACTIVE_BOOK_ID = run.book?.id ?? null;
+      const seenIds = new Map(); // ids are book-local in corpus mode
+      const questionFiles = [];
+      for await (const file of walkMdx(run.dir)) {
+        if (!file.split('/').pop().startsWith('_')) questionFiles.push(file);
+      }
+      for (const rel of questionFiles) {
+        const abs = join(run.dir, rel);
+        const content = await readFile(abs, 'utf8');
+        const qrel = `${run.prefix}/${rel}`;
+        let parsedFrontmatter;
+        try {
+          parsedFrontmatter = parseFrontmatter(
+            content,
+            run.book ? `[book:${run.book.id}] ${qrel}` : qrel,
+          );
+        } catch (error) {
+          recordFrontmatterFailure(error, qrel, run.book?.id ?? null);
+          continue;
+        }
+        const frontmatter = parsedFrontmatter.frontmatter;
+        if (run.book) {
+          if (
+            Object.prototype.hasOwnProperty.call(frontmatter, 'book') &&
+            frontmatter.book !== run.book.id
+          ) {
+            fail(
+              qrel,
+              parsedFrontmatter.lines.book ?? 2,
+              `frontmatter book ${JSON.stringify(frontmatter.book)} does not match ` +
+                `path-derived corpus book ${JSON.stringify(run.book.id)}.`,
+            );
+          }
+        }
+
+        // Questions do not run the legacy link-resolution advisory, so keep the
+        // #190 root-base contract fully inert by parsing only for a non-root base.
+        const authoredTargets = ASTRO_BASE === '/' ? [] : collectAuthoredTargets(qrel, content);
+        validateAuthoredTargets(qrel, content, authoredTargets);
+
+        const normalizedQuestionId = typeof frontmatter.id === 'string'
+          ? frontmatter.id.trim()
+          : '';
+        const questionId = normalizedQuestionId.length > 0 ? normalizedQuestionId : null;
+        if (questionId) {
+          const id = questionId;
+          if (seenIds.has(id)) {
+            fail(
+              qrel,
+              parsedFrontmatter.lines.id ?? 1,
+              `Duplicate question id "${id}" — also declared in ${seenIds.get(id)}. Question ids must be unique (cross-ref key for the appendix / flashcards).`,
+            );
+          } else {
+            seenIds.set(id, qrel);
+          }
+        }
+
+        if (examDomains) {
+          const normalizedDomain = typeof frontmatter.domain === 'string'
+            ? frontmatter.domain.trim()
+            : '';
+          const domain = normalizedDomain.length > 0 ? normalizedDomain : null;
+          if (domain && !examDomains.has(domain)) {
+            fail(
+              qrel,
+              parsedFrontmatter.lines.domain ?? 1,
+              `Question domain "${domain}" not in defineBookConfig examDomains (${[...examDomains].join(', ') || 'none'}). Register it or fix the value.`,
+            );
+          }
+        }
+
+        // v4.21.0 (#114): <Rationale appendix> needs for= (the /answers#answer-<id>
+        // anchor target) — the component throws at build; flag it here, earlier.
+        for (const m of content.matchAll(/<Rationale\b([^>]*)>/g)) {
+          const attrs = m[1];
+          if (!/(^|\s)appendix(\s|=|$)/.test(attrs)) continue;
+          const forMatch = attrs.match(/\bfor\s*=\s*["']([^"']+)["']/);
+          if (!forMatch) {
+            fail(
+              qrel,
+              lineOf(content, m.index),
+              `<Rationale appendix> without for="<question-id>" — no appendix anchor target; throws at build.`,
+            );
+          } else if (questionId && forMatch[1] !== questionId) {
+            fail(
+              qrel,
+              lineOf(content, m.index),
+              `<Rationale appendix for="${forMatch[1]}"> does not match this question's id "${questionId}" — the /answers anchor would land on the wrong (or no) answer.`,
+            );
+          }
+        }
+      }
+      questionsChecked += questionFiles.length;
+      if (run.book) questionsCheckedByBook.set(run.book.id, questionFiles.length);
+    }
+    ACTIVE_BOOK_ID = BOOK_SELECTION.corpus ? 'corpus' : null;
+  }
+}
+
+// ===== Report =====
+context.questionsChecked = questionsChecked;
+const format = ({ file, line, msg, book }) =>
+  `${book ? `[book:${book}] ` : '  '}${file}:${line}  ${msg}`;
+if (warnings.length > 0) {
+  const prefix = BOOK_SELECTION.corpus ? '[book:corpus] ' : '';
+  writeStderr(`${prefix}validate: ${warnings.length} warning(s):\n`);
+  warnings.forEach((warning) => writeStderr(`${format(warning)}\n`));
+}
+
+if (BOOK_SELECTION.corpus) {
+  for (const book of BOOK_SELECTION.books) {
+    const count = chapterCountsByBook.get(book.id) ?? 0;
+    const questionCount = questionsCheckedByBook.get(book.id) ?? 0;
+    const questionNote = questionCount > 0 ? ` + ${questionCount} question(s)` : '';
+    const bookErrors = errors.filter((error) => error.book === book.id).length;
+    const bookWarnings = warnings.filter((warning) => warning.book === book.id).length;
+    const result = bookErrors === 0 ? '✓' : '✗';
+    const detail = bookErrors === 0
+      ? 'no errors'
+      : `${bookErrors} error${bookErrors === 1 ? '' : 's'}`;
+    writeStdout(
+      `[book:${book.id}] validate: ${result} ${count} chapter(s)${questionNote} checked; ${detail}, ` +
+        `${bookWarnings} warning${bookWarnings === 1 ? '' : 's'} ` +
+        `(profile=${PROFILE}, number-style=${TOOLING_CONFIG.numberStyle}).\n`,
+    );
+  }
+
+  const qNote = questionsChecked > 0 ? ` + ${questionsChecked} question(s)` : '';
+  const aggregateResult = errors.length === 0 ? '✓' : '✗';
+  const aggregateDetail = errors.length === 0
+    ? 'no errors'
+    : `${errors.length} error${errors.length === 1 ? '' : 's'}`;
+  const aggregateMessage =
+    `[book:corpus] validate: ${aggregateResult} ${chapterFiles.length} chapter(s)${qNote} ` +
+    `across ${BOOK_SELECTION.books.length} book${BOOK_SELECTION.books.length === 1 ? '' : 's'}; ` +
+    `${aggregateDetail}, ${warnings.length} warning${warnings.length === 1 ? '' : 's'} ` +
+    `(profile=${PROFILE}, number-style=${TOOLING_CONFIG.numberStyle})`;
+  if (errors.length === 0) {
+    writeStdout(`${aggregateMessage}.\n`);
+    return finish(0);
+  }
+  writeStderr(`${aggregateMessage}:\n`);
+  errors.forEach((error) => writeStderr(`${format(error)}\n`));
+  return finish(Math.min(errors.length, 255));
+}
+
+if (errors.length === 0) {
+  const qNote = questionsChecked > 0 ? ` + ${questionsChecked} question(s)` : '';
+  writeStdout(
+    `validate: ✓ ${chapterFiles.length} chapter(s)${qNote} checked ` +
+      `(profile=${PROFILE}, number-style=${TOOLING_CONFIG.numberStyle}); no errors.\n`,
+  );
+  return finish(0);
+}
+writeStderr(
+  `validate: ✗ ${errors.length} error(s) in ${chapterFiles.length} chapter(s) ` +
+    `(profile=${PROFILE}, number-style=${TOOLING_CONFIG.numberStyle}):\n`,
+);
+errors.forEach((error) => writeStderr(`${format(error)}\n`));
+return finish(Math.min(errors.length, 255));
+  } catch (error) {
+    if (error instanceof ValidationFatal) {
+      return finish(error.exitCode, {
+        kind: error.kind,
+        message: error.message,
+      });
+    }
+    const message = String(error?.message ?? error);
+    const prefix = context.selection?.corpus ? '[book:corpus] ' : '';
+    writeStderr(`${prefix}validate: fatal: ${message}\n`);
+    return finish(1, { kind: 'internal', message });
+  }
+}