explico 0.1.1 → 0.2.0

package/src/reference/consistency.ts

@@ -42,7 +42,10 @@ export type ConsistencyCode =
   | 'convention-single-definition'
   | 'numerals-tagged'
   | 'weak-local'
-  | 'notation-source-locator';
+  | 'notation-source-locator'
+  | 'gloss-wants-promoting'
+  | 'card-wants-demoting'
+  | 'gloss-name-shape';
 
 export interface ConsistencyDiagnostic {
   readonly code: ConsistencyCode;
@@ -325,6 +328,150 @@ function checkNotationSourceLocator(
   }
 }
 
+/**
+ * The two-tier vocabulary needs both directions kept honest (D15).
+ *
+ * A gloss is cheap on purpose, and cheapness invites copying: the same symbol
+ * and name glossed on three cards is a shared meaning that should be a card,
+ * reviewed once, with sources and a curriculum home. `GLOSS_PROMOTION_LIMIT`
+ * is where "a letter this formula needs" stops being a plausible reading.
+ */
+const GLOSS_PROMOTION_LIMIT = 3;
+
+function checkGlossWantsPromoting(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const owners = new Map<string, { label: string; keys: Set<string> }>();
+  const record = (
+    ownerKey: string,
+    gloss: { notation: string; label: string },
+  ) => {
+    const id = `${gloss.notation}\u0000${gloss.label.toLowerCase()}`;
+    const current = owners.get(id) ?? { label: gloss.label, keys: new Set() };
+    current.keys.add(ownerKey);
+    owners.set(id, current);
+  };
+
+  for (const definition of input.notationInput.sharedDefinitions) {
+    for (const gloss of definition.glosses) record(definition.key, gloss);
+  }
+  for (const lesson of input.notationInput.lessons) {
+    for (const definition of lesson.localDefinitions) {
+      for (const gloss of definition.glosses) record(definition.key, gloss);
+    }
+  }
+
+  for (const [id, { label, keys }] of [...owners].sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    if (keys.size < GLOSS_PROMOTION_LIMIT) continue;
+    const glyph = id.split('\u0000')[0] ?? '';
+    if (input.lintIgnore.matches('gloss-wants-promoting', glyph)) continue;
+    out.push({
+      code: 'gloss-wants-promoting',
+      severity: 'warning',
+      glyph,
+      message: `gloss ${JSON.stringify(glyph)} (${label}) is declared on ${keys.size} entries (${[...keys].sort().join(', ')}); a meaning reused this widely wants promoting to a card`,
+    });
+  }
+}
+
+/**
+ * The other direction: a card that never grew past its name is carrying the
+ * full weight of the card tier — a glossary entry, a curriculum node, a review
+ * obligation — for something a gloss would say as well.
+ */
+const CARD_BODY_MINIMUM_WORDS = 25;
+
+function checkCardWantsDemoting(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const used = new Set(
+    input.registry.backlinks.map((backlink) => backlink.key),
+  );
+
+  for (const definition of input.notationInput.sharedDefinitions) {
+    if (definition.formula !== undefined) continue;
+    if (definition.sources.length > 0) continue;
+    if (used.has(definition.key)) continue;
+    const words = stripCode(definition.body)
+      .split(/\s+/)
+      .filter((word) => word.length > 0).length;
+    if (words >= CARD_BODY_MINIMUM_WORDS) continue;
+    if (input.lintIgnore.matches('card-wants-demoting', definition.key)) {
+      continue;
+    }
+    out.push({
+      code: 'card-wants-demoting',
+      severity: 'warning',
+      key: definition.key,
+      file: definition.source.file,
+      count: words,
+      message: `notation card ${definition.key} has no formula, no sources, a ${words}-word body, and no lesson uses it; it carries no more than a name — a gloss on the entry that needs it may be the right home`,
+    });
+  }
+}
+
+/**
+ * A gloss `name` is the name of a symbol, not a description of it — the
+ * description tier is the card. The schema already blocks the unambiguous
+ * failure (LaTeX in the name); this catches the softer drift toward prose.
+ *
+ * The word limit is measured, not guessed: across the 62 shared cards the
+ * longest name is six words (`cds protection buyer net present value`), and
+ * that is the most complicated quantity in the course. A gloss names a *letter*
+ * inside one formula, so it should be shorter still. Seven or more words means
+ * the author is describing rather than naming — a warning, never a block,
+ * because a genuinely complicated quantity may earn the exception through
+ * `lint-ignore.yml`.
+ */
+const GLOSS_NAME_WORD_LIMIT = 6;
+const GLOSS_NAME_PROSE = /[.;]|\b(?:which|whose|that is|such that)\b/i;
+
+function checkGlossNameShape(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const check = (
+    gloss: { key: string; label: string },
+    file: string,
+    lessonId?: string,
+  ) => {
+    const words = gloss.label.trim().split(/\s+/).filter(Boolean);
+    const reason =
+      words.length > GLOSS_NAME_WORD_LIMIT
+        ? `${words.length} words`
+        : GLOSS_NAME_PROSE.test(gloss.label)
+          ? 'sentence punctuation or a relative clause'
+          : undefined;
+    if (reason === undefined) return;
+    if (input.lintIgnore.matches('gloss-name-shape', gloss.key)) return;
+    out.push({
+      code: 'gloss-name-shape',
+      severity: 'warning',
+      key: gloss.key,
+      file,
+      ...(lessonId ? { lessonId } : {}),
+      message: `gloss ${gloss.key} is named ${JSON.stringify(gloss.label)} (${reason}); a gloss name is a short noun phrase naming the symbol, not a description of it`,
+    });
+  };
+
+  for (const definition of input.notationInput.sharedDefinitions) {
+    for (const gloss of definition.glosses) {
+      check(gloss, definition.source.file);
+    }
+  }
+  for (const lesson of input.notationInput.lessons) {
+    for (const definition of lesson.localDefinitions) {
+      for (const gloss of definition.glosses) {
+        check(gloss, definition.source.file, lesson.lessonId);
+      }
+    }
+  }
+}
+
 const CHECKS: ((
   input: ConsistencyInput,
   out: ConsistencyDiagnostic[],
@@ -335,6 +482,9 @@ const CHECKS: ((
   checkNumeralsTagged,
   checkWeakLocal,
   checkNotationSourceLocator,
+  checkGlossWantsPromoting,
+  checkCardWantsDemoting,
+  checkGlossNameShape,
 ];
 
 /**
@@ -369,6 +519,9 @@ export function consistencyCounts(
     'numerals-tagged': 0,
     'weak-local': 0,
     'notation-source-locator': 0,
+    'gloss-wants-promoting': 0,
+    'card-wants-demoting': 0,
+    'gloss-name-shape': 0,
   } satisfies Record<ConsistencyCode, number>;
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

package/src/reference/equations.mjs

@@ -1,22 +1,24 @@
 /**
- * Equation identity (Step D7) — shared, framework-free helpers.
+ * Equation identity (Step D7, extended F3) — 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`):
+ * Every display equation (`$$…$$`) in a lesson is numbered and given an
+ * `id`, from appearance order scoped to the enclosing `##` section (`(2.4)` =
+ * fourth display equation under the second section). An author additionally
+ * marks an equation with a trailing `\label{eq:<key>}` inside its `$$…$$`
+ * block (inside math, so the `:` is safe and the form matches amsmath) when
+ * they want a *stable* anchor that survives edits and cross-page references:
  *
  *   [[eq-discount-factor-def]]           same page  → "(2.4)" linked to #eq-…
  *   [[foundations/present-value#eq-pv]]  cross page → number from the manifest
  *
+ * An unkeyed equation still gets a positional anchor (`#eq-2-4`) so it can be
+ * deep-linked, but only a keyed equation is referenceable by name.
+ *
  * `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.
+ * numbering algorithm. `collectDisplayEquations` is the superset the render
+ * path uses to number and anchor every display equation, keyed or not.
  */
 
 /** `eq:` key grammar — the notation-key shape without the dotted namespaces. */
@@ -51,11 +53,16 @@ export function stripEquationLabels(latex) {
     .trim();
 }
 
-/** The visible number for the `index`-th keyed equation under `section`. */
+/** The visible number for the `index`-th display equation under `section`. */
 function equationNumber(section, index) {
   return section > 0 ? `${section}.${index}` : String(index);
 }
 
+/** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
+export function equationAnchorId({ key, number }) {
+  return key ? `eq-${key}` : `eq-${String(number).replace(/\./g, '-')}`;
+}
+
 function stripFencedCode(markdown) {
   return String(markdown)
     .replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, ' '))
@@ -63,13 +70,29 @@ function stripFencedCode(markdown) {
     .replace(/(^|[^`])`[^`\n]*`/g, (match) => match.replace(/[^\n]/g, ' '));
 }
 
+/**
+ * Blank the body of every block-level MDX component (`<Capitalised …> … </…>`)
+ * so a `$$…$$` used to illustrate a worked example inside `<CompactExample>`
+ * (or an `<Aside>`, etc.) is not counted as a lesson-body equation. The
+ * outermost match wins, so nested components are blanked in one pass;
+ * newlines are kept so line/section structure is unchanged.
+ */
+function stripJsxComponents(markdown) {
+  return String(markdown).replace(
+    /<([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>/g,
+    (block) => block.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.
+ * the section counter. Every display block advances the in-section index, so a
+ * keyed equation's number reflects its position among *all* display equations,
+ * not only the keyed ones.
  */
 export function scanEquationLabels(markdown) {
-  const text = stripFencedCode(markdown);
+  const text = stripJsxComponents(stripFencedCode(markdown));
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const display = /\$\$([\s\S]+?)\$\$/g;
@@ -79,9 +102,11 @@ export function scanEquationLabels(markdown) {
   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.push({
+      kind: 'equation',
+      index: match.index,
+      key: label ? label[1] : null,
+    });
   }
   tokens.sort((a, b) => a.index - b.index);
 
@@ -95,6 +120,7 @@ export function scanEquationLabels(markdown) {
       continue;
     }
     indexInSection += 1;
+    if (token.key == null) continue;
     labels.push({
       key: token.key,
       number: equationNumber(section, indexInSection),
@@ -106,39 +132,49 @@ export function scanEquationLabels(markdown) {
 }
 
 /**
- * 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:…}`.
+ * The mdast equivalent of `scanEquationLabels` for *every* display equation:
+ * walk the tree in document order, advancing the section counter on every
+ * depth-2 heading and emitting a record for every `math` node. `key` is the
+ * `\label{eq:…}` payload when present, else `null`.
  */
-export function collectEquationLabels(tree) {
-  const labels = [];
+export function collectDisplayEquations(tree) {
+  const equations = [];
   let section = 0;
   let indexInSection = 0;
 
-  const walk = (node) => {
-    if (!node || typeof node !== 'object') return;
+  // Only top-level blocks: a `$$…$$` nested in an MDX component (a
+  // `<CompactExample>` worked example, an `<Aside>`) is illustrative, not part
+  // of the lesson's equation sequence, and its container may be collapsed.
+  const children = Array.isArray(tree?.children) ? tree.children : [];
+  for (const node of children) {
+    if (!node || typeof node !== 'object') continue;
     if (node.type === 'heading' && node.depth === 2) {
       section += 1;
       indexInSection = 0;
-      return;
+      continue;
     }
     if (node.type === 'math') {
+      indexInSection += 1;
       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;
+      equations.push({
+        key: label ? label[1] : null,
+        number: equationNumber(section, indexInSection),
+        section,
+        indexInSection,
+        node,
+      });
     }
-    if (Array.isArray(node.children)) node.children.forEach(walk);
-  };
-  walk(tree);
-  return labels;
+  }
+  return equations;
+}
+
+/**
+ * The keyed subset of `collectDisplayEquations` — the tree-walk counterpart of
+ * `scanEquationLabels`. Numbers reflect position among all display equations.
+ */
+export function collectEquationLabels(tree) {
+  return collectDisplayEquations(tree).filter(
+    (equation) => equation.key != null,
+  );
 }

package/src/reference/gate-math.ts

@@ -11,6 +11,8 @@
  */
 import { resolveMathGlyphs, GlyphResolutionError } from './math-glyphs.mjs';
 import { stripEquationLabels } from './equations.mjs';
+import { formulaGlyphScope, unknownFormulaScopeKeys } from './gloss';
+import type { GlyphScopeEntry } from './gloss';
 import type {
   NotationLessonInput,
   NotationRegistryInput,
@@ -21,10 +23,11 @@ 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.
+   * glyph resolved for the KaTeX trust callback). `formula` joined it at D15:
+   * a formula's glyphs are now rendered live and explorable, so an unresolved
+   * one is a hole the reader can see, and the corpus was brought to zero when
+   * the tier was promoted. `assessment` math stays a Tier-3 warning until its
+   * own reviewed content pass (D6/D13/D14).
    */
   readonly severity: 'error' | 'warning';
   readonly file: string;
@@ -35,7 +38,7 @@ export interface MathGateDiagnostic {
 
 const SEVERITY: Record<MathGateDiagnostic['context'], 'error' | 'warning'> = {
   body: 'error',
-  formula: 'warning',
+  formula: 'error',
   assessment: 'warning',
 };
 
@@ -157,6 +160,51 @@ function resolveInto(
 
 const BODY_FIX =
   'Introduce the symbol with [[key]], define it in notation.local, or wrap it in \\explain{key}{latex}.';
+function dedupeScope(scope: readonly GlyphScopeEntry[]): GlyphScopeEntry[] {
+  const seen = new Set<string>();
+  const out: GlyphScopeEntry[] = [];
+  for (const entry of scope) {
+    if (seen.has(entry.key)) continue;
+    seen.add(entry.key);
+    out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * `\explain{key}` in a formula widens the glyph scope without becoming a
+ * reference edge (D15), so nothing else checks that the key exists. Report it
+ * here: a marker pointing at no card is an authoring mistake, not a silent
+ * fall-through to an unresolved glyph.
+ */
+function reportUnknownScopeKeys(
+  definition: {
+    readonly key: string;
+    readonly formula?: string;
+    readonly glosses: readonly { readonly key: string }[];
+  },
+  cardKeys: ReadonlySet<string>,
+  file: string,
+  out: MathGateDiagnostic[],
+): void {
+  const glossKeys = new Set(definition.glosses.map((gloss) => gloss.key));
+  for (const key of unknownFormulaScopeKeys(
+    definition.formula,
+    glossKeys,
+    cardKeys,
+  )) {
+    out.push({
+      context: 'formula',
+      severity: SEVERITY.formula,
+      file,
+      token: key,
+      message: `${definition.key} formula names unknown notation key ${JSON.stringify(key)}. Name an existing card, or declare the symbol under glosses: on this entry.`,
+    });
+  }
+}
+
+const SHARED_FORMULA_FIX =
+  'Every symbol in a notation entry formula must resolve to the entry itself, one of its glosses:, a card the formula names with \\explain{key}{latex}, or the base library.';
 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 =
@@ -178,6 +226,18 @@ export function gateContentMath(input: {
       definition,
     ]),
   );
+  const sharedCards = new Map<string, GlyphScopeEntry>(
+    notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      { key: definition.key, notation: definition.notation },
+    ]),
+  );
+  const cardKeys = new Set<string>([
+    ...sharedCards.keys(),
+    ...notationInput.lessons.flatMap((lesson) =>
+      lesson.localDefinitions.map((definition) => definition.key),
+    ),
+  ]);
   const lessonById = new Map(
     notationInput.lessons.map((lesson) => [lesson.lessonId, lesson]),
   );
@@ -206,19 +266,56 @@ export function gateContentMath(input: {
     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.
+      // the formula's LHS key resolves against itself; its glosses (D15) name
+      // the letters the formula introduces and nothing else on the page.
       resolveInto(
         definition.formula,
-        scope,
+        dedupeScope([
+          ...scope,
+          ...definition.glosses.map((gloss) => ({
+            key: gloss.key,
+            notation: gloss.notation,
+          })),
+        ]),
         'formula',
         file,
         undefined,
         FORMULA_FIX,
         diagnostics,
       );
+      reportUnknownScopeKeys(definition, cardKeys, file, diagnostics);
     }
   }
 
+  // Shared cards carry their own rigorous `formula`. It resolves against the
+  // entry-scoped table (D15) — the card, its glosses, and the cards the
+  // formula names with `\explain` — not the registry-wide table the card's
+  // body math uses.
+  for (const definition of notationInput.sharedDefinitions) {
+    if (!definition.formula) continue;
+    resolveInto(
+      definition.formula,
+      formulaGlyphScope({
+        key: definition.key,
+        notation: definition.notation,
+        formula: definition.formula,
+        glosses: definition.glosses,
+        cardsByKey: sharedCards,
+      }),
+      'formula',
+      definition.source.file,
+      undefined,
+      SHARED_FORMULA_FIX,
+      diagnostics,
+    );
+    reportUnknownScopeKeys(
+      definition,
+      cardKeys,
+      definition.source.file,
+      diagnostics,
+    );
+  }
+
   for (const link of lessonAssessments) {
     const lesson = lessonById.get(link.lessonId);
     if (!lesson) continue;

package/src/reference/gloss.ts

@@ -0,0 +1,153 @@
+/**
+ * Glosses and formula scope (D15) — the second tier of the notation
+ * vocabulary.
+ *
+ * A **card** is a `content/notation/*.md` entry (or a `notation.local` entry):
+ * symbol, name, description, units, sources, curriculum alignment, review
+ * state. It gets a glossary card and is a node in the curriculum graph.
+ *
+ * A **gloss** is declared on a card, in that card's `glosses:` frontmatter,
+ * and carries a symbol, a name, and optionally a bare units string. It exists
+ * for one reason: so a card's rigorous `formula` can name its own letters
+ * without each letter having to become a card. A gloss has no description, no
+ * sources, no alignment, no review state, and no glossary card — and, the
+ * point of the whole tier, **it creates no curriculum edge**. A card that
+ * dragged its formula's letters into the registry would drag them into the
+ * lesson bundle of every lesson that uses it, and a foundations lesson would
+ * fail `alignment-introduction` on a symbol introduced six lessons later.
+ *
+ * The editorial convention (not enforced here): a card's formula may introduce
+ * glosses; glosses terminate — they have no formula of their own. A symbol
+ * that later needs a real definition is **promoted**: delete the gloss line,
+ * add `content/notation/<key>.md`. Because a formula spells LaTeX and never a
+ * key, nothing else in the corpus changes.
+ */
+export interface NotationGlossInput {
+  readonly latex: string;
+  readonly name: string;
+  readonly units?: string;
+}
+
+/** A gloss with its derived key and display label. */
+export interface ResolvedGloss {
+  /** `<card key>.<slug(name)>` — derived, never authored. */
+  readonly key: string;
+  readonly notation: string;
+  readonly label: string;
+  readonly units?: string;
+  /** The card that declares it. */
+  readonly ownerKey: string;
+}
+
+/** One `{key, notation}` row of the flat table `resolveMathGlyphs` consumes. */
+export interface GlyphScopeEntry {
+  readonly key: string;
+  readonly notation: string;
+}
+
+/**
+ * The key segment derived from a gloss name: lower-cased, runs of anything
+ * that is not a letter or digit collapsed to a single `-`. Returns `undefined`
+ * when the name has no usable characters, so the schema can reject it rather
+ * than the loader minting an invalid key.
+ */
+export function glossKeySegment(name: string): string | undefined {
+  const segment = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return segment.length > 0 ? segment : undefined;
+}
+
+/**
+ * Derive a gloss's key. Dotted onto the owning card's key, so a gloss is
+ * entry-scoped by construction: two cards may each gloss `T`, and a gloss can
+ * never be confused with a card in the flat registry.
+ */
+export function glossKey(ownerKey: string, name: string): string {
+  const segment = glossKeySegment(name);
+  if (segment === undefined) {
+    throw new Error(
+      `Gloss name ${JSON.stringify(name)} on ${ownerKey} yields no key segment.`,
+    );
+  }
+  return `${ownerKey}.${segment}`;
+}
+
+/** Resolve a card's authored `glosses:` list into keyed, labelled entries. */
+export function resolveGlosses(
+  ownerKey: string,
+  glosses: readonly NotationGlossInput[],
+): ResolvedGloss[] {
+  return glosses.map((gloss) => ({
+    key: glossKey(ownerKey, gloss.name),
+    notation: gloss.latex,
+    label: gloss.name,
+    ownerKey,
+    ...(gloss.units === undefined ? {} : { units: gloss.units }),
+  }));
+}
+
+/** `\explain{key}` occurrences in a formula — scope only, never a reference. */
+const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
+
+export function formulaExplainKeys(formula: string): string[] {
+  EXPLAIN_KEY.lastIndex = 0;
+  return [...formula.matchAll(EXPLAIN_KEY)].map((match) => match[1] ?? '');
+}
+
+/**
+ * The glyph table a card's `formula` resolves against:
+ *
+ *     {the card itself} ∪ {its glosses} ∪ {cards its formula names} ∪ base library
+ *
+ * Narrower than the registry-wide table a card's *body* math still uses, and
+ * narrower than a lesson page's scope. A card named with `\explain{key}` in
+ * the formula joins the table for glyph resolution **only**: its existence is
+ * checked, but it deliberately becomes no reference edge, because a
+ * definitional letter is not a curriculum prerequisite. See the module note.
+ */
+export function formulaGlyphScope(input: {
+  readonly key: string;
+  readonly notation: string;
+  readonly formula?: string;
+  readonly glosses: readonly ResolvedGloss[];
+  /** Every card by key — shared entries, plus page-local ones for a lesson. */
+  readonly cardsByKey: ReadonlyMap<string, GlyphScopeEntry>;
+}): GlyphScopeEntry[] {
+  const scope: GlyphScopeEntry[] = [
+    { key: input.key, notation: input.notation },
+  ];
+  const seen = new Set([input.key]);
+
+  for (const gloss of input.glosses) {
+    if (seen.has(gloss.key)) continue;
+    seen.add(gloss.key);
+    scope.push({ key: gloss.key, notation: gloss.notation });
+  }
+
+  for (const key of formulaExplainKeys(input.formula ?? '')) {
+    if (seen.has(key)) continue;
+    const card = input.cardsByKey.get(key);
+    if (!card) continue;
+    seen.add(key);
+    scope.push({ key: card.key, notation: card.notation });
+  }
+
+  return scope;
+}
+
+/**
+ * Keys named by a formula that no card defines. The build reports these — an
+ * `\explain{…}` pointing at nothing is an authoring mistake, not a silent
+ * fallback to an unresolved glyph.
+ */
+export function unknownFormulaScopeKeys(
+  formula: string | undefined,
+  glossKeys: ReadonlySet<string>,
+  cardKeys: ReadonlySet<string>,
+): string[] {
+  return formulaExplainKeys(formula ?? '').filter(
+    (key) => !cardKeys.has(key) && !glossKeys.has(key),
+  );
+}