explico 0.1.0

package/dist/reference/consistency.js

@@ -0,0 +1,234 @@
+import { offVocabularyTokens } from "./units-vocab";
+const CONVENTION_RE = /\bsign convention\b|\bcash-flow perspective\b|\bholder(?:'s)?(?:\s+\w+){0,2}\s+perspective\b|\bfrom (?:a|one|the|its)(?:\s+\w+){0,3}\s+perspective\b|\breverses? every sign\b|\bpositive (?:means|amounts?)\b/i;
+function stripCode(text) {
+  return text.replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, " ")).replace(/(^|[^`])`[^`\n]*`/g, (match) => match.replace(/[^\n]/g, " "));
+}
+function mathSpans(body) {
+  const searchable = stripCode(body);
+  const spans = [];
+  for (const match of searchable.matchAll(/\$\$([\s\S]+?)\$\$/g)) {
+    spans.push({ latex: match[1] ?? "" });
+  }
+  for (const match of searchable.replace(/\$\$([\s\S]+?)\$\$/g, (block) => block.replace(/[^\n]/g, " ")).matchAll(/(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g)) {
+    spans.push({ latex: match[1] ?? "" });
+  }
+  return spans;
+}
+function tableRows(body) {
+  const rows = [];
+  for (const line of stripCode(body).split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|") || !trimmed.slice(1).includes("|")) continue;
+    if (/^\s*\|[\s:|-]+\|\s*$/.test(line)) continue;
+    rows.push(line);
+  }
+  return rows;
+}
+const NUMERAL_RE = /(?<![\w.])-?\d+(?:\.\d+)?/g;
+function numeralCount(text) {
+  return (text.replace(/\\[a-zA-Z]+/g, " ").match(NUMERAL_RE) ?? []).length;
+}
+function isTagged(text) {
+  return /\[@[a-z0-9]/i.test(text) || /<!--\s*domain:/i.test(text);
+}
+function glyphMatcher(latex) {
+  const trimmed = latex.trim();
+  if (trimmed === "") return void 0;
+  if (/^[A-Za-z]$/.test(trimmed)) {
+    return new RegExp(`(?<![A-Za-z\\\\])${trimmed}(?![A-Za-z])`);
+  }
+  const escaped = trimmed.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(
+    /[A-Za-z]$/.test(trimmed) ? `${escaped}(?![A-Za-z])` : escaped
+  );
+}
+function checkGlyphUniqueness(input, out) {
+  const byId = new Map(
+    input.registry.definitions.map((definition) => [definition.id, definition])
+  );
+  const glyphs = /* @__PURE__ */ new Map();
+  const record = (glyph, key, lessonId) => {
+    const trimmed = glyph.trim();
+    if (trimmed === "") return;
+    const keys = glyphs.get(trimmed) ?? /* @__PURE__ */ new Map();
+    const lessons = keys.get(key) ?? /* @__PURE__ */ new Set();
+    lessons.add(lessonId);
+    keys.set(key, lessons);
+    glyphs.set(trimmed, keys);
+  };
+  for (const definition of input.registry.definitions) {
+    if (definition.kind === "local") {
+      record(definition.notation, definition.key, definition.lessonId);
+    }
+  }
+  for (const bundle of input.registry.bundles) {
+    for (const binding of bundle.bindings) {
+      const definition = byId.get(binding.definitionId);
+      if (definition) record(definition.notation, binding.key, bundle.lessonId);
+    }
+  }
+  for (const [glyph, keys] of [...glyphs].sort(
+    ([a], [b]) => a.localeCompare(b)
+  )) {
+    if (keys.size < 2) continue;
+    if (input.lintIgnore.matches("glyph-unique-in-corpus", glyph)) continue;
+    const detail = [...keys].sort(([a], [b]) => a.localeCompare(b)).map(([key, lessons]) => `${key} (${[...lessons].sort().join(", ")})`).join("; ");
+    out.push({
+      code: "glyph-unique-in-corpus",
+      severity: "warning",
+      glyph,
+      message: `glyph ${JSON.stringify(glyph)} resolves to ${keys.size} meanings across the corpus: ${detail}`
+    });
+  }
+}
+function checkNotationUnits(input, out) {
+  for (const spec of input.specs) {
+    if (spec.units === void 0 && !spec.dimensionless) {
+      if (input.lintIgnore.matches("notation-units", spec.key)) continue;
+      out.push({
+        code: "notation-units",
+        severity: "warning",
+        key: spec.key,
+        file: spec.file,
+        ...spec.lessonId ? { lessonId: spec.lessonId } : {},
+        message: `notation ${spec.key} (${spec.scope}) declares neither units nor dimensionless`
+      });
+      continue;
+    }
+    if (spec.units === void 0) continue;
+    const offVocab = offVocabularyTokens(spec.units);
+    if (offVocab.length === 0) continue;
+    if (input.lintIgnore.matches("units-vocab", spec.key)) continue;
+    out.push({
+      code: "units-vocab",
+      severity: "warning",
+      key: spec.key,
+      file: spec.file,
+      ...spec.lessonId ? { lessonId: spec.lessonId } : {},
+      message: `notation ${spec.key} units ${JSON.stringify(spec.units)} use non-vocabulary token(s): ${offVocab.join(", ")}`
+    });
+  }
+}
+function checkConventionSingleDefinition(input, out) {
+  const lessonById = new Map(
+    input.catalog.lessons.map((lesson) => [lesson.id, lesson])
+  );
+  for (const lesson of input.notationInput.lessons) {
+    const body = lesson.body;
+    if (!CONVENTION_RE.test(body)) continue;
+    const meta = lessonById.get(lesson.lessonId);
+    const { signConventionKey, cashFlowPerspectiveCompetency } = input.conventions;
+    const anchoredByCompetency = [
+      ...meta?.teaches ?? [],
+      ...meta?.requires ?? []
+    ].includes(cashFlowPerspectiveCompetency);
+    const anchoredByTerm = new RegExp(
+      `\\[\\[\\s*${signConventionKey}\\s*\\]\\]`
+    ).test(body);
+    if (anchoredByCompetency || anchoredByTerm) continue;
+    if (input.lintIgnore.matches("convention-single-definition", lesson.lessonId)) {
+      continue;
+    }
+    out.push({
+      code: "convention-single-definition",
+      severity: "warning",
+      lessonId: lesson.lessonId,
+      file: lesson.source.file,
+      message: `${lesson.lessonId} states a sign / cash-flow-perspective convention in prose but does not resolve it to a single declaration ([[${signConventionKey}]] or ${cashFlowPerspectiveCompetency})`
+    });
+  }
+}
+function checkNumeralsTagged(input, out) {
+  for (const lesson of input.notationInput.lessons) {
+    if (input.lintIgnore.matches("numerals-tagged", lesson.lessonId)) continue;
+    let math = 0;
+    for (const span of mathSpans(lesson.body)) {
+      if (isTagged(span.latex)) continue;
+      math += numeralCount(span.latex);
+    }
+    let table = 0;
+    for (const row of tableRows(lesson.body)) {
+      if (isTagged(row)) continue;
+      table += numeralCount(row.replace(/\$[^$\n]*\$/g, " "));
+    }
+    const count = math + table;
+    if (count === 0) continue;
+    out.push({
+      code: "numerals-tagged",
+      severity: "warning",
+      lessonId: lesson.lessonId,
+      file: lesson.source.file,
+      count,
+      message: `${lesson.lessonId}: ${count} numeral(s) in $\u2026$ / result tables (${math} in math, ${table} in tables) are not tagged to a src/domain/ call or a source locator`
+    });
+  }
+}
+function checkWeakLocal(input, out) {
+  for (const lesson of input.notationInput.lessons) {
+    const spans = mathSpans(lesson.body).map((span) => span.latex);
+    for (const definition of lesson.localDefinitions) {
+      if (input.lintIgnore.matches("weak-local", definition.key)) continue;
+      const matcher = glyphMatcher(definition.notation);
+      if (!matcher) continue;
+      const uses = spans.filter((latex) => matcher.test(latex)).length;
+      if (uses > 1) continue;
+      out.push({
+        code: "weak-local",
+        severity: "warning",
+        lessonId: lesson.lessonId,
+        file: lesson.source.file,
+        key: definition.key,
+        count: uses,
+        message: `${lesson.lessonId}: local symbol ${definition.key} (${definition.notation}) appears in ${uses} body equation(s); referenced only in its defining equation and prose \u2014 inline candidate`
+      });
+    }
+  }
+}
+function checkNotationSourceLocator(input, out) {
+  for (const spec of input.specs) {
+    for (const [index, source] of spec.sources.entries()) {
+      if (source.hasLocator) continue;
+      if (input.lintIgnore.matches("notation-source-locator", spec.key)) break;
+      out.push({
+        code: "notation-source-locator",
+        severity: "warning",
+        key: spec.key,
+        file: spec.file,
+        ...spec.lessonId ? { lessonId: spec.lessonId } : {},
+        message: `notation ${spec.key} sources[${index}] (${source.id || "bare id"}) has no non-empty locator`
+      });
+    }
+  }
+}
+const CHECKS = [
+  checkGlyphUniqueness,
+  checkNotationUnits,
+  checkConventionSingleDefinition,
+  checkNumeralsTagged,
+  checkWeakLocal,
+  checkNotationSourceLocator
+];
+function runConsistencyChecks(input) {
+  const diagnostics = [];
+  for (const check of CHECKS) check(input, diagnostics);
+  return diagnostics.sort(
+    (left, right) => left.code.localeCompare(right.code) || (left.lessonId ?? "").localeCompare(right.lessonId ?? "") || (left.key ?? "").localeCompare(right.key ?? "") || (left.glyph ?? "").localeCompare(right.glyph ?? "") || left.message.localeCompare(right.message)
+  );
+}
+function consistencyCounts(diagnostics) {
+  const counts = {
+    "glyph-unique-in-corpus": 0,
+    "notation-units": 0,
+    "units-vocab": 0,
+    "convention-single-definition": 0,
+    "numerals-tagged": 0,
+    "weak-local": 0,
+    "notation-source-locator": 0
+  };
+  for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
+  return counts;
+}
+export {
+  consistencyCounts,
+  runConsistencyChecks
+};

package/dist/reference/curriculum-alignment.d.ts

@@ -0,0 +1,7 @@
+import { CurriculumCatalog } from '../curriculum/validation.js';
+import { NotationRegistry, NotationDiagnostic } from './types.js';
+
+declare function validateNotationAlignment(registry: NotationRegistry, catalog: CurriculumCatalog): readonly NotationDiagnostic[];
+declare function assertValidNotationAlignment(registry: NotationRegistry, catalog: CurriculumCatalog): void;
+
+export { assertValidNotationAlignment, validateNotationAlignment };

package/dist/reference/curriculum-alignment.js

@@ -0,0 +1,166 @@
+import { compareDiagnostics } from "./references";
+function validateNotationAlignment(registry, catalog) {
+  const diagnostics = [];
+  const competencies = new Map(
+    catalog.competencies.map((entry) => [
+      entry.id,
+      entry
+    ])
+  );
+  const lessons = new Map(catalog.lessons.map((entry) => [entry.id, entry]));
+  const sources = new Map(catalog.sources.map((entry) => [entry.id, entry]));
+  const trackPositions = buildTrackPositions(catalog, diagnostics);
+  for (const definition of registry.definitions) {
+    validateSources(definition, sources, diagnostics);
+    const alignment = definition.alignment;
+    if (alignment.kind === "general") continue;
+    const competency = competencies.get(alignment.introducedByCompetency);
+    const lesson = lessons.get(alignment.introducedInLesson);
+    if (!competency) {
+      diagnostics.push(
+        error(
+          "alignment-unknown-competency",
+          `${definition.id} is aligned to unknown competency ${alignment.introducedByCompetency}`,
+          definition
+        )
+      );
+    }
+    if (!lesson) {
+      diagnostics.push(
+        error(
+          "alignment-unknown-lesson",
+          `${definition.id} is introduced in unknown lesson ${alignment.introducedInLesson}`,
+          definition
+        )
+      );
+      continue;
+    }
+    if (!lesson.teaches.includes(alignment.introducedByCompetency)) {
+      diagnostics.push(
+        error(
+          "alignment-introduction",
+          `${definition.id} names ${alignment.introducedInLesson} as its introduction, but that lesson does not teach ${alignment.introducedByCompetency}`,
+          definition
+        )
+      );
+    }
+    if (definition.kind === "local" && alignment.introducedInLesson !== definition.lessonId) {
+      diagnostics.push(
+        error(
+          "alignment-introduction",
+          `${definition.id} is page-local to ${definition.lessonId} but declares its introduction in ${alignment.introducedInLesson}`,
+          definition
+        )
+      );
+    }
+    validateIntroductionOrder(
+      definition,
+      alignment.introducedInLesson,
+      registry,
+      trackPositions,
+      diagnostics
+    );
+    if (definition.status === "reviewed" && (lesson.status !== "reviewed" || competency?.editorialStatus !== "reviewed")) {
+      diagnostics.push(
+        error(
+          "alignment-review-state",
+          `${definition.id} is reviewed while its owning lesson or competency is not reviewed`,
+          definition
+        )
+      );
+    }
+  }
+  return diagnostics.sort(compareDiagnostics);
+}
+function assertValidNotationAlignment(registry, catalog) {
+  const errors = validateNotationAlignment(registry, catalog).filter(
+    (diagnostic) => diagnostic.severity === "error"
+  );
+  if (errors.length === 0) return;
+  throw new Error(
+    `Invalid notation alignment:
+${errors.map((diagnostic) => `- [${diagnostic.code}] ${diagnostic.message}`).join("\n")}`
+  );
+}
+function buildTrackPositions(catalog, diagnostics) {
+  const positions = /* @__PURE__ */ new Map();
+  for (const track of catalog.tracks) {
+    const trackMap = /* @__PURE__ */ new Map();
+    track.lessons.forEach((lessonId, index) => trackMap.set(lessonId, index));
+    positions.set(track.id, trackMap);
+  }
+  if (positions.size === 0 && catalog.lessons.length > 0) {
+    diagnostics.push({
+      code: "alignment-unavailable",
+      severity: "error",
+      message: "notation introduction order cannot be checked without a track"
+    });
+  }
+  return positions;
+}
+function validateIntroductionOrder(definition, introductionLessonId, registry, trackPositions, diagnostics) {
+  const usedIn = registry.backlinks.filter((backlink) => backlink.definitionId === definition.id).map((backlink) => backlink.lessonId);
+  for (const [trackId, positions] of trackPositions) {
+    const introductionPosition = positions.get(introductionLessonId);
+    for (const lessonId of usedIn) {
+      const usePosition = positions.get(lessonId);
+      if (usePosition === void 0) continue;
+      if (introductionPosition === void 0) {
+        diagnostics.push(
+          error(
+            "alignment-unavailable",
+            `${definition.id} is used by ${lessonId} in track ${trackId}, but its declared introduction ${introductionLessonId} is absent from that track`,
+            definition,
+            lessonId
+          )
+        );
+      } else if (usePosition < introductionPosition) {
+        diagnostics.push(
+          error(
+            "alignment-introduction",
+            `${definition.id} is used by ${lessonId} before its declared introduction ${introductionLessonId} in track ${trackId}`,
+            definition,
+            lessonId
+          )
+        );
+      }
+    }
+  }
+}
+function validateSources(definition, sources, diagnostics) {
+  for (const sourceId of definition.sources) {
+    const source = sources.get(sourceId);
+    if (!source) {
+      diagnostics.push(
+        error(
+          "alignment-unavailable",
+          `${definition.id} cites unknown source ${sourceId}`,
+          definition
+        )
+      );
+    } else if (definition.status === "reviewed" && source.editorialStatus !== "reviewed") {
+      diagnostics.push(
+        error(
+          "alignment-review-state",
+          `${definition.id} is reviewed while source ${sourceId} is ${source.editorialStatus}`,
+          definition
+        )
+      );
+    }
+  }
+}
+function error(code, message, definition, lessonId) {
+  return {
+    code,
+    severity: "error",
+    message,
+    key: definition.key,
+    definitionId: definition.id,
+    lessonId: lessonId ?? (definition.kind === "local" ? definition.lessonId : void 0),
+    source: definition.source
+  };
+}
+export {
+  assertValidNotationAlignment,
+  validateNotationAlignment
+};

package/dist/reference/equations-validate.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+interface EquationLabelRecord {
+    readonly key: string;
+    readonly number: string;
+    readonly lessonId: string;
+    readonly slug: string;
+    readonly section: number;
+    readonly indexInSection: number;
+}
+interface EquationRefRecord {
+    readonly key: string;
+    readonly lessonId: string;
+    /** Target lesson slug for a cross-page reference; `undefined` = same page. */
+    readonly targetSlug?: string;
+}
+type EquationDiagnosticCode = 'eq-duplicate-key' | 'eq-ref-resolves' | 'eq-key-unused';
+interface EquationDiagnostic {
+    readonly code: EquationDiagnosticCode;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+    readonly key?: string;
+}
+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[];
+}
+interface EquationLessonInput {
+    readonly lessonId: string;
+    readonly slug: string;
+    readonly file: string;
+    readonly body: string;
+}
+declare function validateEquations(lessons: readonly EquationLessonInput[]): EquationValidation;
+
+export { type EquationDiagnostic, type EquationDiagnosticCode, type EquationLabelRecord, type EquationLessonInput, type EquationRefRecord, type EquationValidation, validateEquations };

package/dist/reference/equations-validate.js

@@ -0,0 +1,90 @@
+import { parseEquationRef, scanEquationLabels } from "./equations.mjs";
+const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
+function stripCode(text) {
+  return text.replace(/```[\s\S]*?```/g, " ").replace(/~~~[\s\S]*?~~~/g, " ").replace(/`[^`\n]*`/g, " ");
+}
+function bodyEquationRefs(lesson) {
+  const refs = [];
+  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;
+}
+function validateEquations(lessons) {
+  const labels = [];
+  const diagnostics = [];
+  const numbersBySlug = {};
+  for (const lesson of [...lessons].sort(
+    (a, b) => a.lessonId.localeCompare(b.lessonId)
+  )) {
+    const seen = /* @__PURE__ */ new Set();
+    const table = {};
+    for (const raw of scanEquationLabels(lesson.body)) {
+      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 = /* @__PURE__ */ new Set();
+  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 === void 0) {
+        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 };
+}
+export {
+  validateEquations
+};

package/dist/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;
+}