explico 0.1.1 → 0.3.0

package/src/reference/equations-validate.ts

@@ -53,6 +53,11 @@ export interface EquationLessonInput {
   readonly slug: string;
   readonly file: string;
   readonly body: string;
+  /**
+   * The lesson's 1-based ordinal in the course. When set, equations are
+   * numbered `‹chapter›.‹n›`; when omitted, the legacy `##`-section scheme.
+   */
+  readonly chapter?: number;
 }
 
 const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
@@ -90,7 +95,7 @@ export function validateEquations(
   )) {
     const seen = new Set<string>();
     const table: Record<string, string> = {};
-    for (const raw of scanEquationLabels(lesson.body) as {
+    for (const raw of scanEquationLabels(lesson.body, lesson.chapter) as {
       key: string;
       number: string;
       section: number;

package/src/reference/equations.mjs

@@ -1,22 +1,28 @@
 /**
- * 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. When the caller supplies a `chapter` (the lesson's
+ * ordinal position in the course), the number is `‹chapter›.‹n›` — `n` counts
+ * every display equation in the lesson and `##` headings do not affect it
+ * (`(2.4)` = fourth display equation of the second lesson). With no `chapter`
+ * the number falls back to the `##`-section scheme `‹section›.‹indexInSection›`
+ * (used by hand-built test trees and non-lesson pages). 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,25 +57,68 @@ 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);
 }
 
-function stripFencedCode(markdown) {
+/**
+ * The visible number for one display equation. With `chapter` (the lesson's
+ * course ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings
+ * are ignored; without it, the legacy `##`-section scheme.
+ */
+export function displayEquationNumber({
+  chapter,
+  section,
+  indexInSection,
+  indexInLesson,
+}) {
+  return chapter == null
+    ? equationNumber(section, indexInSection)
+    : `${chapter}.${indexInLesson}`;
+}
+
+/** 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, '-')}`;
+}
+
+export 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, ' '));
 }
 
+/**
+ * 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.
+ *
+ * `keep`, when given, leaves a component of that name untouched instead of
+ * blanking it — `keyed-jsx-floats.mjs` uses this to blank every *other*
+ * component while still finding `<Table>`/`<Figure>` tags at the top level.
+ */
+export function stripJsxComponents(markdown, keep) {
+  return String(markdown).replace(
+    /<([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>/g,
+    (block, name) => (name === keep ? 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.
+ * its assigned number. `$$…$$` blocks only. With `chapter` (the lesson's
+ * course ordinal) the number is `‹chapter›.‹n›`, `n` sequential over every
+ * display block in the lesson; without it, `##` headings advance a section
+ * counter and the number is `‹section›.‹indexInSection›`. Either way every
+ * display block advances the 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);
+export function scanEquationLabels(markdown, chapter) {
+  const text = stripJsxComponents(stripFencedCode(markdown));
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const display = /\$\$([\s\S]+?)\$\$/g;
@@ -79,15 +128,18 @@ 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);
 
   const labels = [];
   let section = 0;
   let indexInSection = 0;
+  let indexInLesson = 0;
   for (const token of tokens) {
     if (token.kind === 'section') {
       section += 1;
@@ -95,9 +147,16 @@ export function scanEquationLabels(markdown) {
       continue;
     }
     indexInSection += 1;
+    indexInLesson += 1;
+    if (token.key == null) continue;
     labels.push({
       key: token.key,
-      number: equationNumber(section, indexInSection),
+      number: displayEquationNumber({
+        chapter,
+        section,
+        indexInSection,
+        indexInLesson,
+      }),
       section,
       indexInSection,
     });
@@ -106,39 +165,57 @@ 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`. `chapter` is threaded the
+ * same way as in `scanEquationLabels`.
  */
-export function collectEquationLabels(tree) {
-  const labels = [];
+export function collectDisplayEquations(tree, chapter) {
+  const equations = [];
   let section = 0;
   let indexInSection = 0;
+  let indexInLesson = 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;
+      indexInLesson += 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),
+      equations.push({
+        key: label ? label[1] : null,
+        number: displayEquationNumber({
+          chapter,
           section,
           indexInSection,
-          node,
-        });
-      }
-      return;
+          indexInLesson,
+        }),
+        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, chapter) {
+  return collectDisplayEquations(tree, chapter).filter(
+    (equation) => equation.key != null,
+  );
 }

package/src/reference/figures-validate.ts

@@ -0,0 +1,40 @@
+/** `validateKeyedFloats` for `<Figure>` — see `keyed-float-validate.ts`. */
+
+import {
+  validateKeyedFloats,
+  type KeyedFloatLabelRecord,
+  type KeyedFloatLessonInput,
+  type KeyedFloatValidation,
+} from './keyed-float-validate';
+
+export type FigureDiagnosticCode =
+  | 'fig-invalid-key'
+  | 'fig-duplicate-key'
+  | 'fig-ref-resolves'
+  | 'fig-key-unused';
+
+export interface FigureDiagnostic {
+  readonly code: FigureDiagnosticCode;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+  readonly key?: string;
+}
+
+export type FigureLabelRecord = KeyedFloatLabelRecord;
+export type FigureLessonInput = KeyedFloatLessonInput;
+
+export interface FigureValidation extends KeyedFloatValidation {
+  readonly diagnostics: readonly FigureDiagnostic[];
+}
+
+export function validateFigures(
+  lessons: readonly FigureLessonInput[],
+): FigureValidation {
+  return validateKeyedFloats(lessons, {
+    tagName: 'Figure',
+    prefix: 'fig',
+    noun: 'figure',
+  }) as FigureValidation;
+}

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),
+  );
+}