explico 0.4.0 → 0.6.0

package/dist/reference/base-roman-labels.d.mts

@@ -0,0 +1,35 @@
+/**
+ * The roman labels a course treats as common, given its `course.config.ts`
+ * `romanLabels` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} romanLabels
+ * @returns {Set<string>}
+ */
+export function effectiveRomanLabelAllowlist(romanLabels: {
+    allow?: readonly string[];
+    deny?: readonly string[];
+} | undefined): Set<string>;
+/** True when `name` needs no notation entry for this course. */
+export function isBaseRomanLabel(name: any, romanLabels: any): boolean;
+/**
+ * The base roman-label baseline: `\mathrm{…}` multi-letter labels every
+ * reader is assumed to know, so a lesson never has to introduce them with a
+ * notation entry. The `\operatorname{…}` counterpart is `base-operators.mjs`
+ * (rule N8); this is its `\mathrm{…}` twin (rule N10).
+ *
+ * Rationale: the completeness gate has no opinion about `\mathrm{…}` bodies —
+ * they are a typographic label to KaTeX, not a bindable symbol, and N3
+ * requires the format without asking whether the label is ever explained.
+ * The `roman-label-explained` consistency check fills that gap: a label a
+ * lesson uses is either on this list (or the course's additions to it) or it
+ * carries a notation entry the reader can hover.
+ *
+ * Kept intentionally small — unlike `sin`/`exp`, an upright label is almost
+ * always a course-specific named quantity (`KE`, `PV`, `Var`-as-a-label) that
+ * genuinely benefits from a hover card, so the shipped baseline holds only
+ * the qualifiers that function like an operator's extremum subscript
+ * (`x_{\mathrm{opt}}`) rather than naming a quantity of their own. A course
+ * adds a real one via `romanLabels.allow` in `course.config.ts`, the same
+ * shape as `operators.allow`.
+ */
+export const BASE_ROMAN_LABELS: Readonly<Set<string>>;

package/dist/reference/base-roman-labels.mjs

@@ -0,0 +1,43 @@
+/**
+ * The base roman-label baseline: `\mathrm{…}` multi-letter labels every
+ * reader is assumed to know, so a lesson never has to introduce them with a
+ * notation entry. The `\operatorname{…}` counterpart is `base-operators.mjs`
+ * (rule N8); this is its `\mathrm{…}` twin (rule N10).
+ *
+ * Rationale: the completeness gate has no opinion about `\mathrm{…}` bodies —
+ * they are a typographic label to KaTeX, not a bindable symbol, and N3
+ * requires the format without asking whether the label is ever explained.
+ * The `roman-label-explained` consistency check fills that gap: a label a
+ * lesson uses is either on this list (or the course's additions to it) or it
+ * carries a notation entry the reader can hover.
+ *
+ * Kept intentionally small — unlike `sin`/`exp`, an upright label is almost
+ * always a course-specific named quantity (`KE`, `PV`, `Var`-as-a-label) that
+ * genuinely benefits from a hover card, so the shipped baseline holds only
+ * the qualifiers that function like an operator's extremum subscript
+ * (`x_{\mathrm{opt}}`) rather than naming a quantity of their own. A course
+ * adds a real one via `romanLabels.allow` in `course.config.ts`, the same
+ * shape as `operators.allow`.
+ */
+export const BASE_ROMAN_LABELS = Object.freeze(new Set(['opt']));
+
+/**
+ * The roman labels a course treats as common, given its `course.config.ts`
+ * `romanLabels` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} romanLabels
+ * @returns {Set<string>}
+ */
+export function effectiveRomanLabelAllowlist(romanLabels) {
+  const allow = romanLabels?.allow ?? [];
+  const deny = new Set(romanLabels?.deny ?? []);
+  const effective = new Set(BASE_ROMAN_LABELS);
+  for (const name of allow) effective.add(name);
+  for (const name of deny) effective.delete(name);
+  return effective;
+}
+
+/** True when `name` needs no notation entry for this course. */
+export function isBaseRomanLabel(name, romanLabels) {
+  return effectiveRomanLabelAllowlist(romanLabels).has(name);
+}

package/dist/reference/consistency.d.ts

@@ -1,4 +1,4 @@
-import { CourseConventions, CourseOperators } from '../compiler/course-config.js';
+import { CourseConventions, CourseOperators, CourseRomanLabels } from '../compiler/course-config.js';
 import { CurriculumCatalog } from '../curriculum/validation.js';
 import { NotationSpec } from '../compiler/collections.js';
 import { LintIgnore } from './lint-ignore.js';
@@ -28,12 +28,16 @@ import { NotationRegistry, NotationRegistryInput } from './types.js';
  *   (h) operator-explained           a named operator a lesson uses is on the
  *                                     shipped/course operator allowlist or
  *                                     carries a notation entry (rule N8)
+ *   (i) roman-label-explained        a `\mathrm{…}` multi-letter label a lesson
+ *                                     uses is on the shipped/course roman-label
+ *                                     allowlist or carries a notation entry
+ *                                     (rule N10)
  *
  * Check (d) — the committed per-lesson resolution report — lives in
  * `src/content/resolution-report.ts`.
  */
 
-type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'numerals-tagged' | 'weak-local' | 'notation-source-locator' | 'gloss-wants-promoting' | 'card-wants-demoting' | 'gloss-name-shape' | 'operator-explained';
+type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'numerals-tagged' | 'weak-local' | 'notation-source-locator' | 'gloss-wants-promoting' | 'card-wants-demoting' | 'gloss-name-shape' | 'operator-explained' | 'roman-label-explained';
 interface ConsistencyDiagnostic {
     readonly code: ConsistencyCode;
     /** Tier 3 — every finding here is a warning until content is brought clean. */
@@ -56,6 +60,8 @@ interface ConsistencyInput {
     readonly conventions: CourseConventions;
     /** This course's edits to the named-operator baseline (rule N8). */
     readonly operators?: CourseOperators;
+    /** This course's edits to the roman-label baseline (rule N10). */
+    readonly romanLabels?: CourseRomanLabels;
 }
 /**
  * Run every consistency check. The result is sorted deterministically (code,

package/dist/reference/consistency.js

@@ -1,5 +1,6 @@
 import { effectiveOperatorAllowlist } from "./base-operators.mjs";
-import { collectOperators } from "./math-glyphs.mjs";
+import { effectiveRomanLabelAllowlist } from "./base-roman-labels.mjs";
+import { collectOperators, collectRomanLabels } from "./math-glyphs.mjs";
 import { offVocabularyTokens } from "./units-vocab.js";
 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) {
@@ -332,6 +333,50 @@ function checkOperatorExplained(input, out) {
     }
   }
 }
+function checkRomanLabelExplained(input, out) {
+  const allowlist = effectiveRomanLabelAllowlist(input.romanLabels);
+  const byId = new Map(
+    input.registry.definitions.map((definition) => [definition.id, definition])
+  );
+  const bindingsByLesson = new Map(
+    input.registry.bundles.map((bundle) => [bundle.lessonId, bundle.bindings])
+  );
+  for (const lesson of input.notationInput.lessons) {
+    const explained = /* @__PURE__ */ new Set();
+    const noteEntryLabels = (latex) => {
+      for (const label of collectRomanLabels(latex)) {
+        explained.add(label.name);
+      }
+    };
+    for (const definition of lesson.localDefinitions) {
+      noteEntryLabels(definition.notation);
+    }
+    for (const binding of bindingsByLesson.get(lesson.lessonId) ?? []) {
+      const definition = byId.get(binding.definitionId);
+      if (definition) noteEntryLabels(definition.notation);
+    }
+    const reported = /* @__PURE__ */ new Set();
+    for (const span of mathSpans(lesson.body)) {
+      for (const label of collectRomanLabels(span.latex)) {
+        if (allowlist.has(label.name)) continue;
+        if (explained.has(label.name)) continue;
+        if (reported.has(label.name)) continue;
+        reported.add(label.name);
+        if (input.lintIgnore.matches("roman-label-explained", label.name)) {
+          continue;
+        }
+        out.push({
+          code: "roman-label-explained",
+          severity: "warning",
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          glyph: label.name,
+          message: `${lesson.lessonId}: roman label ${JSON.stringify(`\\mathrm{${label.name}}`)} is neither on the course roman-label allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(`\\mathrm{${label.name}}`)}) introduced with [[key]], or add ${JSON.stringify(label.name)} to romanLabels.allow in course.config.ts`
+        });
+      }
+    }
+  }
+}
 const CHECKS = [
   checkGlyphUniqueness,
   checkNotationUnits,
@@ -342,7 +387,8 @@ const CHECKS = [
   checkGlossWantsPromoting,
   checkCardWantsDemoting,
   checkGlossNameShape,
-  checkOperatorExplained
+  checkOperatorExplained,
+  checkRomanLabelExplained
 ];
 function runConsistencyChecks(input) {
   const diagnostics = [];
@@ -363,7 +409,8 @@ function consistencyCounts(diagnostics) {
     "gloss-wants-promoting": 0,
     "card-wants-demoting": 0,
     "gloss-name-shape": 0,
-    "operator-explained": 0
+    "operator-explained": 0,
+    "roman-label-explained": 0
   };
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

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

@@ -0,0 +1,21 @@
+import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } from './keyed-float-validate.js';
+
+/** `validateKeyedFloats` for `<Diagram>` — see `keyed-float-validate.ts`. */
+
+type DiagramDiagnosticCode = 'dia-invalid-key' | 'dia-duplicate-key' | 'dia-ref-resolves' | 'dia-key-unused';
+interface DiagramDiagnostic {
+    readonly code: DiagramDiagnosticCode;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+    readonly key?: string;
+}
+type DiagramLabelRecord = KeyedFloatLabelRecord;
+type DiagramLessonInput = KeyedFloatLessonInput;
+interface DiagramValidation extends KeyedFloatValidation {
+    readonly diagnostics: readonly DiagramDiagnostic[];
+}
+declare function validateDiagrams(lessons: readonly DiagramLessonInput[]): DiagramValidation;
+
+export { type DiagramDiagnostic, type DiagramDiagnosticCode, type DiagramLabelRecord, type DiagramLessonInput, type DiagramValidation, validateDiagrams };

package/dist/reference/diagrams-validate.js

@@ -0,0 +1,13 @@
+import {
+  validateKeyedFloats
+} from "./keyed-float-validate.js";
+function validateDiagrams(lessons) {
+  return validateKeyedFloats(lessons, {
+    tagName: "Diagram",
+    prefix: "dia",
+    noun: "diagram"
+  });
+}
+export {
+  validateDiagrams
+};

package/dist/reference/equations.d.mts

@@ -51,8 +51,15 @@ export function stripFencedCode(markdown: any): string;
  * `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.
+ *
+ * `transparent`, when given, removes only those components' opening/closing
+ * tags and exposes their body to the later blanking pass. `<Memo>` and
+ * `<ShortNote>` are intentional uses: unlike a worked-example/presentation
+ * wrapper, their bodies are details in the lesson's reading order, so numbered
+ * equations/floats in them stay in the official sequence. Section headings in
+ * a transparent body do not change the surrounding page's section counter.
  */
-export function stripJsxComponents(markdown: any, keep: any): string;
+export function stripJsxComponents(markdown: any, keep: any, transparent?: any[]): string;
 /**
  * Every display equation in a Markdown body, keyed or not, in appearance order
  * with its assigned number. `$$…$$` blocks only. With `numbering`
@@ -90,24 +97,12 @@ export function countDisplayEquations(markdown: any): number;
  * `\label{eq:…}` payload when present, else `null`. `numbering` is threaded the
  * same way as in `scanEquationLabels`.
  */
-export function collectDisplayEquations(tree: any, numbering: any): {
-    key: string | null;
-    number: string;
-    section: number;
-    indexInSection: number;
-    node: any;
-}[];
+export function collectDisplayEquations(tree: any, numbering: any): any[];
 /**
  * The keyed subset of `collectDisplayEquations` — the tree-walk counterpart of
  * `scanEquationLabels`. Numbers reflect position among all display equations.
  */
-export function collectEquationLabels(tree: any, numbering: any): {
-    key: string | null;
-    number: string;
-    section: number;
-    indexInSection: number;
-    node: any;
-}[];
+export function collectEquationLabels(tree: any, numbering: any): any[];
 /**
  * Equation identity (Step D7, extended F3) — shared, framework-free helpers.
  *

package/dist/reference/equations.mjs

@@ -128,9 +128,36 @@ export function stripFencedCode(markdown) {
  * `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.
+ *
+ * `transparent`, when given, removes only those components' opening/closing
+ * tags and exposes their body to the later blanking pass. `<Memo>` and
+ * `<ShortNote>` are intentional uses: unlike a worked-example/presentation
+ * wrapper, their bodies are details in the lesson's reading order, so numbered
+ * equations/floats in them stay in the official sequence. Section headings in
+ * a transparent body do not change the surrounding page's section counter.
  */
-export function stripJsxComponents(markdown, keep) {
-  return String(markdown).replace(
+export function stripJsxComponents(markdown, keep, transparent = []) {
+  let source = String(markdown);
+  const attributes = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'])*`;
+  for (const name of transparent) {
+    const component = new RegExp(
+      `<${name}\\b${attributes}>([\\s\\S]*?)<\\/${name}\\s*>`,
+      'g',
+    );
+    source = source.replace(component, (block, body) => {
+      const bodyStart = block.indexOf(body);
+      const visibleBody = body.replace(
+        /(^|\n)([ \t]{0,3})##(?=[ \t]+\S)/g,
+        (match) => match.replace(/#/g, ' '),
+      );
+      return (
+        block.slice(0, bodyStart).replace(/[^\n]/g, ' ') +
+        visibleBody +
+        block.slice(bodyStart + body.length).replace(/[^\n]/g, ' ')
+      );
+    });
+  }
+  return source.replace(
     /<([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>/g,
     (block, name) => (name === keep ? block : block.replace(/[^\n]/g, ' ')),
   );
@@ -149,7 +176,10 @@ export function stripJsxComponents(markdown, keep) {
  */
 export function scanDisplayEquations(markdown, numbering) {
   const { prefix, offset } = resolveNumbering(numbering);
-  const text = stripJsxComponents(stripFencedCode(markdown));
+  const text = stripJsxComponents(stripFencedCode(markdown), undefined, [
+    'Memo',
+    'ShortNote',
+  ]);
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const display = /\$\$([\s\S]+?)\$\$/g;
@@ -225,17 +255,13 @@ export function collectDisplayEquations(tree, numbering) {
   let indexInSection = 0;
   let indexInLesson = 0;
 
-  // 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;
-      continue;
-    }
+  // Top-level blocks plus the bodies of `<Memo>` and `<ShortNote>`: other MDX
+  // components (a `<CompactExample>` worked example, an `<Aside>`) remain
+  // illustrative and outside the lesson's official equation sequence. These
+  // two detail components are deliberately transparent because they occupy an
+  // exact point in the reading order, even while visually collapsed.
+  const collectFromDetail = (node) => {
+    if (!node || typeof node !== 'object') return;
     if (node.type === 'math') {
       indexInSection += 1;
       indexInLesson += 1;
@@ -254,6 +280,33 @@ export function collectDisplayEquations(tree, numbering) {
         indexInSection,
         node,
       });
+      return;
+    }
+    if (
+      node.type === 'mdxJsxFlowElement' &&
+      node.name !== 'Memo' &&
+      node.name !== 'ShortNote'
+    ) {
+      return;
+    }
+    if (!Array.isArray(node.children)) return;
+    for (const child of node.children) collectFromDetail(child);
+  };
+
+  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;
+      continue;
+    }
+    if (node.type === 'math') collectFromDetail(node);
+    else if (
+      node.type === 'mdxJsxFlowElement' &&
+      (node.name === 'Memo' || node.name === 'ShortNote')
+    ) {
+      collectFromDetail(node);
     }
   }
   return equations;

package/dist/reference/gate-abbreviations.d.ts

@@ -0,0 +1,17 @@
+import { MathGateDiagnostic } from './gate-math.js';
+import { NotationRegistryInput, AbbreviationDefinitionInput } from './types.js';
+import { CourseAbbreviations } from '../compiler/course-config.js';
+
+/**
+ * Scan every lesson body for an abbreviation-shaped token outside `$…$` that
+ * is neither universal nor explained. Returns one `MathGateDiagnostic`
+ * (context `'abbreviation'`, always an error) per unresolved token, deduped
+ * per lesson so a term used many times on one page is reported once.
+ */
+declare function gateAbbreviations(input: {
+    readonly notationInput: NotationRegistryInput;
+    readonly abbreviations: readonly AbbreviationDefinitionInput[];
+    readonly courseAbbreviations?: CourseAbbreviations;
+}): MathGateDiagnostic[];
+
+export { gateAbbreviations };

package/dist/reference/gate-abbreviations.js

@@ -0,0 +1,64 @@
+import { collectOperators, collectRomanLabels } from "./math-glyphs.mjs";
+import { isBaseAbbreviation } from "./base-abbreviations.mjs";
+import { pageScope } from "./gate-math.js";
+import { lineOf, proseOnly } from "./gate-prose-notation.js";
+const CAPS_RUN = /\b([A-Z]{2,})(?:'s|s)?\b/g;
+const DOTTED_ABBR = /\b(?:[A-Za-z]\.){2,}/g;
+function findAbbreviationLikeTokens(text) {
+  const out = [];
+  for (const match of text.matchAll(CAPS_RUN)) {
+    out.push({ token: match[1] ?? match[0], index: match.index ?? 0 });
+  }
+  for (const match of text.matchAll(DOTTED_ABBR)) {
+    out.push({ token: match[0], index: match.index ?? 0 });
+  }
+  return out.sort((a, b) => a.index - b.index);
+}
+const FIX = "Add it to an abbreviations-table entry (content/abbreviations/*.md), allowlist it in abbreviations.allow in course.config.ts if it is common, non-technical usage, or \u2014 if it names a math quantity \u2014 introduce it as \\mathrm{\u2026} (or \\operatorname{\u2026}) bound to a notation entry the reader can hover. See docs/authoring/notation.md#n14.";
+function gateAbbreviations(input) {
+  const { notationInput, abbreviations, courseAbbreviations } = input;
+  const tableTokens = /* @__PURE__ */ new Set();
+  for (const entry of abbreviations) {
+    tableTokens.add(entry.abbr);
+    for (const alias of entry.aliases) tableTokens.add(alias);
+  }
+  const sharedByKey = new Map(
+    notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      { key: definition.key, notation: definition.notation }
+    ])
+  );
+  const diagnostics = [];
+  for (const lesson of notationInput.lessons) {
+    const mathQuantityNames = /* @__PURE__ */ new Set();
+    for (const entry of pageScope(lesson, sharedByKey)) {
+      for (const label of collectRomanLabels(entry.notation)) {
+        mathQuantityNames.add(label.name);
+      }
+      for (const operator of collectOperators(entry.notation)) {
+        mathQuantityNames.add(operator.name);
+      }
+    }
+    const text = proseOnly(lesson.body);
+    const reported = /* @__PURE__ */ new Set();
+    for (const { token, index } of findAbbreviationLikeTokens(text)) {
+      if (reported.has(token)) continue;
+      if (isBaseAbbreviation(token, courseAbbreviations)) continue;
+      if (tableTokens.has(token)) continue;
+      if (mathQuantityNames.has(token)) continue;
+      reported.add(token);
+      diagnostics.push({
+        context: "abbreviation",
+        severity: "error",
+        file: lesson.source.file,
+        line: lineOf(lesson.body, index),
+        token,
+        message: `Unexplained abbreviation ${JSON.stringify(token)} outside math. ${FIX}`
+      });
+    }
+  }
+  return diagnostics;
+}
+export {
+  gateAbbreviations
+};

package/dist/reference/gate-heading-length.d.ts

@@ -0,0 +1,12 @@
+import { MathGateDiagnostic } from './gate-math.js';
+import { NotationLessonInput } from './types.js';
+
+declare const HEADING_LENGTH_LIMIT = 65;
+/**
+ * Scan every lesson body for a heading or a keyed float's title running past
+ * `HEADING_LENGTH_LIMIT` characters. Returns one `MathGateDiagnostic`
+ * (context `'structure'`, always an error) per finding.
+ */
+declare function gateHeadingLength(lessons: readonly NotationLessonInput[]): MathGateDiagnostic[];
+
+export { HEADING_LENGTH_LIMIT, gateHeadingLength };

package/dist/reference/gate-heading-length.js

@@ -0,0 +1,79 @@
+import { stripFencedCode } from "./equations.mjs";
+import { lineOf } from "./gate-prose-notation.js";
+const HEADING_LENGTH_LIMIT = 65;
+const HEADING_LINE = /^[ \t]{0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/gm;
+const TITLE_ATTRIBUTE_BY_TAG = {
+  Figure: "title",
+  Diagram: "label",
+  Memo: "title",
+  ShortNote: "title"
+};
+function readAttribute(attributesSource, name) {
+  const pattern = new RegExp(`\\b${name}\\s*=\\s*(["'])([^"']*)\\1`);
+  const match = pattern.exec(attributesSource);
+  return match ? match[2] : void 0;
+}
+function overLimitMessage(kind, text) {
+  return `${kind} ${JSON.stringify(text)} is ${text.length} characters, over the ${HEADING_LENGTH_LIMIT}-character limit (rule S1). Shorten it and move the rest into the paragraph or caption that follows.`;
+}
+function headingFindings(text) {
+  const out = [];
+  const re = new RegExp(HEADING_LINE.source, HEADING_LINE.flags);
+  let match;
+  while (match = re.exec(text)) {
+    const level = match[1]?.length ?? 1;
+    const title = (match[2] ?? "").trim();
+    if (title.length > HEADING_LENGTH_LIMIT) {
+      out.push({
+        index: match.index,
+        token: title,
+        message: overLimitMessage(`${"#".repeat(level)} heading`, title)
+      });
+    }
+  }
+  return out;
+}
+function floatTitleFindings(text) {
+  const out = [];
+  for (const [tagName, attribute] of Object.entries(TITLE_ATTRIBUTE_BY_TAG)) {
+    const opening = new RegExp(`<${tagName}\\b([^>]*)>`, "g");
+    let match;
+    while (match = opening.exec(text)) {
+      const value = readAttribute(match[1] ?? "", attribute)?.trim();
+      if (value && value.length > HEADING_LENGTH_LIMIT) {
+        out.push({
+          index: match.index,
+          token: value,
+          message: overLimitMessage(`<${tagName} ${attribute}>`, value)
+        });
+      }
+    }
+  }
+  return out;
+}
+function findingsIn(text) {
+  return [...headingFindings(text), ...floatTitleFindings(text)].sort(
+    (a, b) => a.index - b.index
+  );
+}
+function gateHeadingLength(lessons) {
+  const diagnostics = [];
+  for (const lesson of lessons) {
+    const text = stripFencedCode(lesson.body);
+    for (const finding of findingsIn(text)) {
+      diagnostics.push({
+        context: "structure",
+        severity: "error",
+        file: lesson.source.file,
+        line: lineOf(lesson.body, finding.index),
+        token: finding.token,
+        message: finding.message
+      });
+    }
+  }
+  return diagnostics;
+}
+export {
+  HEADING_LENGTH_LIMIT,
+  gateHeadingLength
+};

package/dist/reference/gate-math.d.ts

@@ -1,14 +1,29 @@
-import { NotationRegistryInput } from './types.js';
+import { NotationRegistryInput, NotationLessonInput } from './types.js';
 
 interface MathGateDiagnostic {
-    readonly context: 'body' | 'formula' | 'assessment';
+    readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation' | 'structure';
     /**
      * Body / component-slot math blocks the build (the render path needs every
      * 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).
+     * the tier was promoted. `assessment` joined the same way when
+     * `AssessmentRunner` started rendering `prompt` / `explanation` through
+     * KaTeX (`mixed-content.ts`) instead of showing them as raw text: an
+     * unresolved glyph is now a visible hole in the assessment UI, not an
+     * invisible warning, so the corpus was brought to zero and the tier
+     * promoted in the same change — see `CHANGELOG.md`. `prose` (N9,
+     * `gate-prose-notation.ts`) is the complementary direction — plain-text
+     * notation sitting *outside* `$…$` — and ships straight as an error: it has
+     * no partial corpus to absorb, since every prior instance was fixed in the
+     * same change that introduced the check. `abbreviation` (N14,
+     * `gate-abbreviations.ts`) is the same "ships straight as an error" story
+     * for a different shape of plain-text token — an unexplained acronym or
+     * dotted abbreviation, rather than a mis-typed quantity/unit. `structure`
+     * (S1, `gate-heading-length.ts`) is unrelated to notation — it caps how
+     * long a heading or a keyed float's title may run — but reuses this same
+     * diagnostic shape and the one `manifest.diagnostics.math` array rather
+     * than adding a second array the CLI has to know about.
      */
     readonly severity: 'error' | 'warning';
     readonly file: string;
@@ -29,6 +44,18 @@ interface LessonAssessmentLink {
     readonly lessonId: string;
     readonly assessmentIds: readonly string[];
 }
+type ScopeEntry = {
+    key: string;
+    notation: string;
+};
+/**
+ * A lesson's flat glyph table: its own `notation.local` entries plus every
+ * shared card it introduces with `[[key]]` / `\explain{key}`. Exported so a
+ * caller that needs the *same* scope for a different purpose — rendering an
+ * assessment's math (`mixed-content.ts`), say — doesn't reconstruct it by
+ * hand and risk drifting from what the completeness gate actually checks.
+ */
+declare function pageScope(lesson: NotationLessonInput, sharedByKey: ReadonlyMap<string, ScopeEntry>): ScopeEntry[];
 /**
  * Resolve every rendered-math context against the page glyph table. Returns one
  * diagnostic per unresolved token; an empty array means the gate passed.
@@ -39,4 +66,4 @@ declare function gateContentMath(input: {
     readonly lessonAssessments: readonly LessonAssessmentLink[];
 }): MathGateDiagnostic[];
 
-export { type MathGateDiagnostic, gateContentMath };
+export { type MathGateDiagnostic, type ScopeEntry, gateContentMath, pageScope };

package/dist/reference/gate-math.js

@@ -4,7 +4,10 @@ import { formulaGlyphScope, unknownFormulaScopeKeys } from "./gloss.js";
 const SEVERITY = {
   body: "error",
   formula: "error",
-  assessment: "warning"
+  assessment: "error",
+  prose: "error",
+  abbreviation: "error",
+  structure: "error"
 };
 const TERM_KEY = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
 const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
@@ -218,5 +221,6 @@ function gateContentMath(input) {
   return diagnostics;
 }
 export {
-  gateContentMath
+  gateContentMath,
+  pageScope
 };