explico 0.1.0

package/src/reference/equations-validate.ts

@@ -0,0 +1,167 @@
+/**
+ * Equation-identity validation (Step D7), run inside `compileManifest()`.
+ *
+ * - `eq-duplicate-key` (Tier 1, error): an `eq:` key is unique per lesson.
+ * - `eq-ref-resolves` (Tier 1, error): every `[[eq-key]]` / `[[slug#eq-key]]`
+ *   points at a display equation that carries `\label{eq:key}`.
+ * - `eq-key-unused` (Tier 3, warning): a labelled equation never referenced.
+ *
+ * The remark pass enforces the same rules on the render path; this gives the
+ * fast `pnpm validate:content` the same coverage and feeds the manifest.
+ */
+
+import { parseEquationRef, scanEquationLabels } from './equations.mjs';
+
+export interface EquationLabelRecord {
+  readonly key: string;
+  readonly number: string;
+  readonly lessonId: string;
+  readonly slug: string;
+  readonly section: number;
+  readonly indexInSection: number;
+}
+
+export interface EquationRefRecord {
+  readonly key: string;
+  readonly lessonId: string;
+  /** Target lesson slug for a cross-page reference; `undefined` = same page. */
+  readonly targetSlug?: string;
+}
+
+export type EquationDiagnosticCode =
+  'eq-duplicate-key' | 'eq-ref-resolves' | 'eq-key-unused';
+
+export interface EquationDiagnostic {
+  readonly code: EquationDiagnosticCode;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+  readonly key?: string;
+}
+
+export interface EquationValidation {
+  /** Every labelled equation, sorted by lesson then appearance. */
+  readonly labels: readonly EquationLabelRecord[];
+  /** `slug -> { eqKey: number }` — the render path's cross-page lookup table. */
+  readonly numbersBySlug: Record<string, Record<string, string>>;
+  readonly diagnostics: readonly EquationDiagnostic[];
+}
+
+export interface EquationLessonInput {
+  readonly lessonId: string;
+  readonly slug: string;
+  readonly file: string;
+  readonly body: string;
+}
+
+const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
+
+function stripCode(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/~~~[\s\S]*?~~~/g, ' ')
+    .replace(/`[^`\n]*`/g, ' ');
+}
+
+function bodyEquationRefs(lesson: EquationLessonInput): EquationRefRecord[] {
+  const refs: EquationRefRecord[] = [];
+  for (const match of stripCode(lesson.body).matchAll(BRACKET_REF)) {
+    const parsed = parseEquationRef((match[1] ?? '').trim());
+    if (!parsed) continue;
+    refs.push({
+      key: parsed.key,
+      lessonId: lesson.lessonId,
+      ...(parsed.lesson ? { targetSlug: parsed.lesson } : {}),
+    });
+  }
+  return refs;
+}
+
+export function validateEquations(
+  lessons: readonly EquationLessonInput[],
+): EquationValidation {
+  const labels: EquationLabelRecord[] = [];
+  const diagnostics: EquationDiagnostic[] = [];
+  const numbersBySlug: Record<string, Record<string, string>> = {};
+
+  for (const lesson of [...lessons].sort((a, b) =>
+    a.lessonId.localeCompare(b.lessonId),
+  )) {
+    const seen = new Set<string>();
+    const table: Record<string, string> = {};
+    for (const raw of scanEquationLabels(lesson.body) as {
+      key: string;
+      number: string;
+      section: number;
+      indexInSection: number;
+    }[]) {
+      if (seen.has(raw.key)) {
+        diagnostics.push({
+          code: 'eq-duplicate-key',
+          severity: 'error',
+          message: `${lesson.lessonId} labels two display equations eq:${raw.key}; an eq: key is unique per lesson`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          key: raw.key,
+        });
+        continue;
+      }
+      seen.add(raw.key);
+      table[raw.key] = raw.number;
+      labels.push({
+        key: raw.key,
+        number: raw.number,
+        lessonId: lesson.lessonId,
+        slug: lesson.slug,
+        section: raw.section,
+        indexInSection: raw.indexInSection,
+      });
+    }
+    numbersBySlug[lesson.slug] = table;
+  }
+
+  const referenced = new Set<string>();
+  for (const lesson of lessons) {
+    const slug = lesson.slug;
+    for (const ref of bodyEquationRefs(lesson)) {
+      const targetSlug = ref.targetSlug ?? slug;
+      const number = numbersBySlug[targetSlug]?.[ref.key];
+      referenced.add(`${targetSlug}#${ref.key}`);
+      if (number === undefined) {
+        diagnostics.push({
+          code: 'eq-ref-resolves',
+          severity: 'error',
+          message: ref.targetSlug
+            ? `${lesson.lessonId} references [[${ref.targetSlug}#eq-${ref.key}]] but that lesson has no display equation labelled eq:${ref.key}`
+            : `${lesson.lessonId} references [[eq-${ref.key}]] but no display equation on the page carries \\label{eq:${ref.key}}`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          key: ref.key,
+        });
+      }
+    }
+  }
+
+  for (const label of labels) {
+    if (referenced.has(`${label.slug}#${label.key}`)) continue;
+    diagnostics.push({
+      code: 'eq-key-unused',
+      severity: 'warning',
+      message: `${label.lessonId} labels eq:${label.key} (${label.number}) but nothing references it with [[eq-${label.key}]]`,
+      file: label.slug,
+      lessonId: label.lessonId,
+      key: label.key,
+    });
+  }
+
+  diagnostics.sort(
+    (a, b) =>
+      a.code.localeCompare(b.code) ||
+      (a.lessonId ?? '').localeCompare(b.lessonId ?? '') ||
+      (a.key ?? '').localeCompare(b.key ?? '') ||
+      a.message.localeCompare(b.message),
+  );
+
+  return { labels, numbersBySlug, diagnostics };
+}

package/src/reference/equations.mjs

@@ -0,0 +1,144 @@
+/**
+ * Equation identity (Step D7) — shared, framework-free helpers.
+ *
+ * An author marks a display equation by putting a trailing `\label{eq:<key>}`
+ * inside its `$$…$$` block (inside math, so the `:` is safe and the form
+ * matches amsmath). The compiler assigns the *visible* number from appearance
+ * order, scoped to the enclosing `##` section (`(2.4)` = fourth keyed equation
+ * under the second section). The number is never authored; unkeyed display
+ * equations render clean and stay un-referenceable. Prose refers to an
+ * equation with the reserved `eq-` prefix (a bare `:` in `[[…]]` prose would
+ * be eaten by `remark-directive`):
+ *
+ *   [[eq-discount-factor-def]]           same page  → "(2.4)" linked to #eq-…
+ *   [[foundations/present-value#eq-pv]]  cross page → number from the manifest
+ *
+ * `scanEquationLabels` (raw Markdown) and `collectEquationLabels` (mdast tree)
+ * MUST agree — `tests/notation/equations.test.ts` checks that on the real
+ * corpus. Both are here so `manifest.ts` and `remark-notation.mjs` share one
+ * numbering algorithm.
+ */
+
+/** `eq:` key grammar — the notation-key shape without the dotted namespaces. */
+export const EQ_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** A `\label{eq:<key>}` anywhere in a math source. Global; `key` in group 1. */
+export const EQ_LABEL_PATTERN =
+  /\\label\{\s*eq:([a-z0-9]+(?:-[a-z0-9]+)*)\s*\}/g;
+
+/**
+ * A `[[ … ]]` payload that targets an equation: `eq-<key>` on the current page,
+ * or `<lesson-slug>#eq-<key>` across pages. `lesson` (group 1) is a `/`-slug.
+ * The `eq-` prefix is reserved — a notation key may not start with it.
+ */
+export const EQ_REF_PATTERN =
+  /^(?:([a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*)#)?eq-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
+/** `{ lesson?, key }` when `raw` is an equation reference, else `undefined`. */
+export function parseEquationRef(raw) {
+  const match = EQ_REF_PATTERN.exec(String(raw).trim());
+  if (!match) return undefined;
+  return match[1] ? { lesson: match[1], key: match[2] } : { key: match[2] };
+}
+
+/** Remove every `\label{eq:…}` (and the whitespace it leaves) from a math source. */
+export function stripEquationLabels(latex) {
+  return String(latex)
+    .replace(EQ_LABEL_PATTERN, '')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/[ \t]{2,}/g, ' ')
+    .trim();
+}
+
+/** The visible number for the `index`-th keyed equation under `section`. */
+function equationNumber(section, index) {
+  return section > 0 ? `${section}.${index}` : String(index);
+}
+
+function stripFencedCode(markdown) {
+  return String(markdown)
+    .replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, ' '))
+    .replace(/~~~[\s\S]*?~~~/g, (block) => block.replace(/[^\n]/g, ' '))
+    .replace(/(^|[^`])`[^`\n]*`/g, (match) => match.replace(/[^\n]/g, ' '));
+}
+
+/**
+ * Every keyed display equation in a Markdown body, in appearance order, with
+ * its assigned number. `$$…$$` blocks only; `##` headings between them advance
+ * the section counter.
+ */
+export function scanEquationLabels(markdown) {
+  const text = stripFencedCode(markdown);
+  const tokens = [];
+  const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
+  const display = /\$\$([\s\S]+?)\$\$/g;
+  for (const match of text.matchAll(heading)) {
+    tokens.push({ kind: 'section', index: match.index });
+  }
+  for (const match of text.matchAll(display)) {
+    EQ_LABEL_PATTERN.lastIndex = 0;
+    const label = EQ_LABEL_PATTERN.exec(match[1]);
+    if (label) {
+      tokens.push({ kind: 'equation', index: match.index, key: label[1] });
+    }
+  }
+  tokens.sort((a, b) => a.index - b.index);
+
+  const labels = [];
+  let section = 0;
+  let indexInSection = 0;
+  for (const token of tokens) {
+    if (token.kind === 'section') {
+      section += 1;
+      indexInSection = 0;
+      continue;
+    }
+    indexInSection += 1;
+    labels.push({
+      key: token.key,
+      number: equationNumber(section, indexInSection),
+      section,
+      indexInSection,
+    });
+  }
+  return labels;
+}
+
+/**
+ * The mdast equivalent of `scanEquationLabels`: walk the tree in document
+ * order, advancing the section counter on every depth-2 heading and emitting a
+ * label for every `math` node whose source carries `\label{eq:…}`.
+ */
+export function collectEquationLabels(tree) {
+  const labels = [];
+  let section = 0;
+  let indexInSection = 0;
+
+  const walk = (node) => {
+    if (!node || typeof node !== 'object') return;
+    if (node.type === 'heading' && node.depth === 2) {
+      section += 1;
+      indexInSection = 0;
+      return;
+    }
+    if (node.type === 'math') {
+      EQ_LABEL_PATTERN.lastIndex = 0;
+      const label = EQ_LABEL_PATTERN.exec(String(node.value ?? ''));
+      if (label) {
+        indexInSection += 1;
+        labels.push({
+          key: label[1],
+          number: equationNumber(section, indexInSection),
+          section,
+          indexInSection,
+          node,
+        });
+      }
+      return;
+    }
+    if (Array.isArray(node.children)) node.children.forEach(walk);
+  };
+  walk(tree);
+  return labels;
+}

package/src/reference/gate-math.ts

@@ -0,0 +1,250 @@
+/**
+ * The completeness gate, run from the CLI (`pnpm validate:content`) over every
+ * rendered-math context — lesson body `$…$` / `$$…$$` (including math inside
+ * component slots), each `notation.local` `formula`, and any `$…$` in an
+ * assessment `prompt` / `explanation`. It reuses the one resolver the Astro
+ * remark pass uses (`resolveMathGlyphs`), so there is a single glyph table and
+ * a single diagnostic shape; `astro build` re-runs the same resolver on the
+ * render path as a backstop.
+ *
+ * Every failure names `file:line: "token"` and the fix.
+ */
+import { resolveMathGlyphs, GlyphResolutionError } from './math-glyphs.mjs';
+import { stripEquationLabels } from './equations.mjs';
+import type {
+  NotationLessonInput,
+  NotationRegistryInput,
+  SharedNotationDefinitionInput,
+} from './types';
+
+export interface MathGateDiagnostic {
+  readonly context: 'body' | 'formula' | 'assessment';
+  /**
+   * Body / component-slot math blocks the build (the render path needs every
+   * glyph resolved for the KaTeX trust callback). `formula` and `assessment`
+   * math enter as warnings (Tier 3) and are promoted once existing content is
+   * brought into line — they surface pre-existing ambiguities that are a
+   * separate reviewed content pass (D6/D13/D14), not a D3 codemod.
+   */
+  readonly severity: 'error' | 'warning';
+  readonly file: string;
+  readonly line?: number;
+  readonly token?: string;
+  readonly message: string;
+}
+
+const SEVERITY: Record<MathGateDiagnostic['context'], 'error' | 'warning'> = {
+  body: 'error',
+  formula: 'warning',
+  assessment: 'warning',
+};
+
+interface AssessmentItemLike {
+  readonly id?: string;
+  readonly prompt?: string;
+  readonly explanation?: string;
+}
+interface AssessmentLike {
+  readonly id: string;
+  readonly items?: readonly AssessmentItemLike[];
+}
+interface LessonAssessmentLink {
+  readonly lessonId: string;
+  readonly assessmentIds: readonly string[];
+}
+
+const TERM_KEY = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
+const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
+const DISPLAY_MATH = /\$\$([\s\S]+?)\$\$/g;
+const INLINE_MATH = /(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g;
+
+function stripCode(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, ' '))
+    .replace(/(^|[^`])`[^`\n]*`/g, (match) => match.replace(/[^\n]/g, ' '));
+}
+
+function lineOf(text: string, index: number): number {
+  return text.slice(0, index).split('\n').length;
+}
+
+interface MathSpan {
+  readonly latex: string;
+  readonly line: number;
+}
+
+function mathSpans(body: string): MathSpan[] {
+  const searchable = stripCode(body);
+  const spans: MathSpan[] = [];
+  for (const pattern of [DISPLAY_MATH, INLINE_MATH]) {
+    pattern.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = pattern.exec(searchable))) {
+      spans.push({
+        // D7: `\label{eq:…}` is an identity marker, not math KaTeX parses.
+        latex: stripEquationLabels(match[1] ?? ''),
+        line: lineOf(body, match.index),
+      });
+    }
+  }
+  return spans;
+}
+
+type ScopeEntry = { key: string; notation: string };
+
+function pageScope(
+  lesson: NotationLessonInput,
+  sharedByKey: ReadonlyMap<string, SharedNotationDefinitionInput>,
+): ScopeEntry[] {
+  const local = lesson.localDefinitions.map((definition) => ({
+    key: definition.key,
+    notation: definition.notation,
+  }));
+  const localKeys = new Set(local.map((entry) => entry.key));
+
+  const referenced = new Set<string>();
+  for (const pattern of [TERM_KEY, EXPLAIN_KEY]) {
+    for (const match of lesson.body.matchAll(pattern)) referenced.add(match[1]);
+  }
+
+  const scope = [...local];
+  for (const key of referenced) {
+    if (localKeys.has(key)) continue;
+    const shared = sharedByKey.get(key);
+    if (shared) scope.push({ key: shared.key, notation: shared.notation });
+  }
+  return scope;
+}
+
+function resolveInto(
+  latex: string,
+  scope: readonly ScopeEntry[],
+  context: MathGateDiagnostic['context'],
+  file: string,
+  line: number | undefined,
+  fix: string,
+  out: MathGateDiagnostic[],
+): void {
+  let result;
+  try {
+    result = resolveMathGlyphs(latex, [...scope]);
+  } catch (error) {
+    out.push({
+      context,
+      severity: SEVERITY[context],
+      file,
+      line,
+      message:
+        error instanceof GlyphResolutionError
+          ? error.message
+          : `Could not compile math ${JSON.stringify(latex)}: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+    });
+    return;
+  }
+  for (const { token } of result.unresolved) {
+    out.push({
+      context,
+      severity: SEVERITY[context],
+      file,
+      line,
+      token,
+      message: `Unresolved notation ${JSON.stringify(token)} in ${context} math. ${fix}`,
+    });
+  }
+}
+
+const BODY_FIX =
+  'Introduce the symbol with [[key]], define it in notation.local, or wrap it in \\explain{key}{latex}.';
+const FORMULA_FIX =
+  'Every right-hand-side variable of a notation.local formula must resolve to the entry key, another page symbol, or the base library.';
+const ASSESSMENT_FIX =
+  "Introduce the symbol in the owning lesson's prose with [[key]], or wrap it in \\explain{key}{latex}.";
+
+/**
+ * Resolve every rendered-math context against the page glyph table. Returns one
+ * diagnostic per unresolved token; an empty array means the gate passed.
+ */
+export function gateContentMath(input: {
+  readonly notationInput: NotationRegistryInput;
+  readonly assessments: readonly AssessmentLike[];
+  readonly lessonAssessments: readonly LessonAssessmentLink[];
+}): MathGateDiagnostic[] {
+  const { notationInput, assessments, lessonAssessments } = input;
+  const sharedByKey = new Map(
+    notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      definition,
+    ]),
+  );
+  const lessonById = new Map(
+    notationInput.lessons.map((lesson) => [lesson.lessonId, lesson]),
+  );
+  const assessmentById = new Map(
+    assessments.map((assessment) => [assessment.id, assessment]),
+  );
+
+  const diagnostics: MathGateDiagnostic[] = [];
+
+  for (const lesson of notationInput.lessons) {
+    const scope = pageScope(lesson, sharedByKey);
+    const file = lesson.source.file;
+
+    for (const span of mathSpans(lesson.body)) {
+      resolveInto(
+        span.latex,
+        scope,
+        'body',
+        file,
+        span.line,
+        BODY_FIX,
+        diagnostics,
+      );
+    }
+
+    for (const definition of lesson.localDefinitions) {
+      if (!definition.formula) continue;
+      // `scope` already carries every page-local entry, including this one, so
+      // the formula's LHS key resolves against itself.
+      resolveInto(
+        definition.formula,
+        scope,
+        'formula',
+        file,
+        undefined,
+        FORMULA_FIX,
+        diagnostics,
+      );
+    }
+  }
+
+  for (const link of lessonAssessments) {
+    const lesson = lessonById.get(link.lessonId);
+    if (!lesson) continue;
+    const scope = pageScope(lesson, sharedByKey);
+
+    for (const assessmentId of link.assessmentIds) {
+      const assessment = assessmentById.get(assessmentId);
+      if (!assessment?.items) continue;
+      for (const item of assessment.items) {
+        for (const field of [item.prompt, item.explanation]) {
+          if (typeof field !== 'string') continue;
+          for (const span of mathSpans(field)) {
+            resolveInto(
+              span.latex,
+              scope,
+              'assessment',
+              `${assessmentId} (${item.id ?? '?'})`,
+              undefined,
+              ASSESSMENT_FIX,
+              diagnostics,
+            );
+          }
+        }
+      }
+    }
+  }
+
+  return diagnostics;
+}

package/src/reference/katex-options.mjs

@@ -0,0 +1,91 @@
+import { NOTATION_KEY_PATTERN } from './remark-notation.mjs';
+
+export const EXPLAIN_MACRO = String.raw`\htmlData{notation-key=#1}{#2}`;
+
+// Interactive labs render developer-authored math templates that carry two
+// kinds of inert marker: `\explain` for a notation key (as above) and `\slot`
+// for a numeric hole the island rewrites at runtime. Both compile to a single
+// `data-*` attribute and nothing else.
+export const SLOT_MACRO = String.raw`\htmlData{lab-slot=#1}{#2}`;
+const LAB_SLOT_PATTERN = /^[a-z][a-z0-9]*$/;
+
+/**
+ * KaTeX trust callback that permits exactly one inert marker attribute:
+ * `data-notation-key` (a registry key) or `data-lab-slot` (a lab value hole).
+ * Links, styles, classes, IDs, protocols, and every other data attribute stay
+ * untrusted. Key existence is checked by the remark adapter, the lab-math
+ * renderer, and the workspace validator before KaTeX runs.
+ */
+export function trustNotationMarker(context) {
+  if (context?.command !== '\\htmlData') return false;
+  if (!context.attributes || typeof context.attributes !== 'object') {
+    return false;
+  }
+
+  const entries = Object.entries(context.attributes);
+  if (entries.length !== 1) return false;
+  const [name, value] = entries[0];
+  if (typeof value !== 'string') return false;
+
+  if (name === 'data-notation-key') return NOTATION_KEY_PATTERN.test(value);
+  if (name === 'data-lab-slot') return LAB_SLOT_PATTERN.test(value);
+  return false;
+}
+
+function strictNotation(errorCode) {
+  // The trusted macros intentionally use KaTeX's HTML extension. Keep normal
+  // strict-mode warnings for all other non-LaTeX constructs.
+  return errorCode === 'htmlExtension' ? 'ignore' : 'warn';
+}
+
+export const notationKatexOptions = Object.freeze({
+  output: 'htmlAndMathml',
+  throwOnError: true,
+  strict: strictNotation,
+  trust: trustNotationMarker,
+  macros: Object.freeze({
+    '\\explain': EXPLAIN_MACRO,
+    '\\slot': SLOT_MACRO,
+  }),
+});
+
+/**
+ * Add non-security KaTeX settings while keeping the notation macros and trust
+ * boundary non-overridable.
+ */
+export function createNotationKatexOptions(overrides = {}) {
+  if ('output' in overrides) {
+    throw new TypeError(
+      'The notation KaTeX output mode cannot be overridden; HTML and MathML are required.',
+    );
+  }
+  if ('throwOnError' in overrides) {
+    throw new TypeError(
+      'The notation KaTeX error mode cannot be overridden; rendering errors must fail the build.',
+    );
+  }
+  if ('trust' in overrides) {
+    throw new TypeError(
+      'The notation KaTeX trust callback cannot be overridden.',
+    );
+  }
+  if (overrides.macros?.['\\explain'] !== undefined) {
+    throw new TypeError('The \\explain KaTeX macro cannot be overridden.');
+  }
+  if (overrides.macros?.['\\slot'] !== undefined) {
+    throw new TypeError('The \\slot KaTeX macro cannot be overridden.');
+  }
+
+  return {
+    ...notationKatexOptions,
+    ...overrides,
+    output: notationKatexOptions.output,
+    throwOnError: notationKatexOptions.throwOnError,
+    trust: trustNotationMarker,
+    macros: {
+      ...(overrides.macros ?? {}),
+      '\\explain': EXPLAIN_MACRO,
+      '\\slot': SLOT_MACRO,
+    },
+  };
+}

package/src/reference/lab-math-scope.ts

@@ -0,0 +1,54 @@
+import { loadManifest } from '../compiler/manifest';
+import type { LabMathScopeDefinition } from './render-lab-math';
+
+interface LessonNotationFrontmatter {
+  readonly local?: ReadonlyArray<{
+    readonly key: string;
+    readonly latex: string;
+  }>;
+}
+
+const TERM_KEY = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
+const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
+
+/**
+ * The notation a lab's math template may reference: exactly the same page glyph
+ * scope the remark adapter gives lesson `$$` math — this page's
+ * `notation.local` plus the shared entries it names in the body with `[[key]]`
+ * (or `\explain{key}{…}`). No transitive closure, so island math cannot
+ * quietly reach beyond what the lesson introduces.
+ *
+ * Shared definitions are read from the one compiler manifest (Phase D5); this
+ * module never re-reads the content tree.
+ */
+export async function labMathScope(
+  notation: LessonNotationFrontmatter | undefined,
+  body = '',
+): Promise<LabMathScopeDefinition[]> {
+  const local = notation?.local ?? [];
+  const scope: LabMathScopeDefinition[] = local.map((definition) => ({
+    key: definition.key,
+    notation: definition.latex,
+  }));
+
+  const referenced = new Set<string>();
+  for (const pattern of [TERM_KEY, EXPLAIN_KEY]) {
+    for (const match of body.matchAll(pattern)) referenced.add(match[1]);
+  }
+
+  const localKeys = new Set(local.map((definition) => definition.key));
+  const manifest = await loadManifest();
+  const sharedByKey = new Map(
+    manifest.notation.definitions
+      .filter((definition) => definition.kind === 'shared')
+      .map((definition) => [definition.key, definition]),
+  );
+
+  for (const key of referenced) {
+    if (localKeys.has(key)) continue;
+    const shared = sharedByKey.get(key);
+    if (shared) scope.push({ key: shared.key, notation: shared.notation });
+  }
+
+  return scope;
+}