explico 0.12.0 → 0.13.1

package/src/reference/text-widths.ts

@@ -0,0 +1,133 @@
+/**
+ * Advance widths of DejaVu Sans (Version 2.37), in font units.
+ * Generated by `scripts/gen-text-widths.mjs` — do not edit by hand.
+ * `-1` marks a code point the font has no glyph for.
+ */
+
+export const UNITS_PER_EM = 2048;
+
+/** `[first code point, widths of it and the code points after it]`. */
+export const WIDTH_BLOCKS: readonly (readonly [number, readonly number[]])[] = [
+  // Basic Latin
+  [
+    0x0020,
+    [
+      651, 821, 942, 1716, 1303, 1946, 1597, 563, 799, 799, 1024, 1716, 651, 739, 651, 690,
+      1303, 1303, 1303, 1303, 1303, 1303, 1303, 1303, 1303, 1303, 690, 690, 1716, 1716, 1716, 1087,
+      2048, 1401, 1405, 1430, 1577, 1294, 1178, 1587, 1540, 604, 604, 1343, 1141, 1767, 1532, 1612,
+      1235, 1612, 1423, 1300, 1251, 1499, 1401, 2025, 1403, 1251, 1403, 799, 690, 799, 1716, 1024,
+      1024, 1255, 1300, 1126, 1300, 1260, 721, 1300, 1298, 569, 569, 1186, 569, 1995, 1298, 1253,
+      1300, 1300, 842, 1067, 803, 1298, 1212, 1675, 1212, 1212, 1075, 1303, 690, 1303, 1716,
+    ],
+  ],
+  // Latin-1 Supplement, Latin Extended-A
+  [
+    0x00a0,
+    [
+      651, 821, 1303, 1303, 1303, 1303, 690, 1024, 1024, 2048, 965, 1253, 1716, 739, 2048, 1024,
+      1024, 1716, 821, 821, 1024, 1303, 1303, 651, 1024, 821, 965, 1253, 1985, 1985, 1985, 1087,
+      1401, 1401, 1401, 1401, 1401, 1401, 1995, 1430, 1294, 1294, 1294, 1294, 604, 604, 604, 604,
+      1587, 1532, 1612, 1612, 1612, 1612, 1612, 1716, 1612, 1499, 1499, 1499, 1499, 1251, 1239, 1290,
+      1255, 1255, 1255, 1255, 1255, 1255, 2011, 1126, 1260, 1260, 1260, 1260, 569, 569, 569, 569,
+      1253, 1298, 1253, 1253, 1253, 1253, 1253, 1716, 1253, 1298, 1298, 1298, 1298, 1212, 1300, 1212,
+      1401, 1255, 1401, 1255, 1401, 1255, 1430, 1126, 1430, 1126, 1430, 1126, 1430, 1126, 1577, 1300,
+      1587, 1300, 1294, 1260, 1294, 1260, 1294, 1260, 1294, 1260, 1294, 1260, 1587, 1300, 1587, 1300,
+      1587, 1300, 1587, 1300, 1540, 1298, 1876, 1423, 604, 569, 604, 569, 604, 569, 604, 569,
+      604, 569, 1208, 1138, 604, 569, 1343, 1186, 1186, 1141, 569, 1141, 569, 1141, 768, 1141,
+      700, 1151, 582, 1532, 1298, 1532, 1298, 1532, 1298, 1666, 1532, 1298, 1612, 1253, 1612, 1253,
+      1612, 1253, 2191, 2095, 1423, 842, 1423, 842, 1423, 842, 1300, 1067, 1300, 1067, 1300, 1067,
+      1300, 1067, 1251, 803, 1251, 803, 1251, 803, 1499, 1298, 1499, 1298, 1499, 1298, 1499, 1298,
+      1499, 1298, 1499, 1298, 2025, 1675, 1251, 1212, 1251, 1403, 1075, 1403, 1075, 1403, 1075, 721,
+    ],
+  ],
+  // Greek
+  [
+    0x0370,
+    [
+      1340, 1163, 1765, 1326, 570, 570, 1532, 1331, -1, -1, 1024, 1125, 1126, 1125, 690, 604,
+      -1, -1, -1, -1, 1024, 1024, 1418, 651, 1528, 1784, 836, -1, 1664, -1, 1689, 1691,
+      693, 1401, 1405, 1141, 1401, 1294, 1403, 1540, 1612, 604, 1343, 1401, 1767, 1532, 1294, 1612,
+      1540, 1235, -1, 1294, 1251, 1251, 1612, 1403, 1612, 1565, 604, 1251, 1350, 1107, 1298, 693,
+      1185, 1350, 1307, 1212, 1253, 1107, 1114, 1298, 1253, 693, 1207, 1212, 1303, 1144, 1142, 1253,
+      1233, 1300, 1202, 1298, 1233, 1185, 1351, 1183, 1351, 1715, 693, 1185, 1253, 1185, 1715, 1343,
+      1258, 1268, 1431, 1725, 1431, 1351, 1715, 1359, 1612, 1253, 1328, 1202, 1178, 939, 1351, 1351,
+      1772, 1285, 1912, 1715, 1553, 1350, 1621, 1259, 1406, 1243, 1572, 1280, 1432, 1253, 1251, 1098,
+      1359, 1300, 1126, 569, 1612, 1260, 1260, 1239, 1300, 1430, 1767, 1333, 1300, 1440, 1430, 1440,
+    ],
+  ],
+  // General Punctuation
+  [
+    0x2000,
+    [
+      1024, 2048, 1024, 2048, 675, 512, 342, 1303, 651, 409, 204, 0, 0, 0, 0, 0,
+      739, 739, 1303, 1024, 2048, 2048, 1024, 1024, 651, 651, 651, 651, 1061, 1061, 1061, 1061,
+      1024, 1024, 1208, 1208, 685, 1367, 2048, 651, 0, 0, 0, 0, 0, 0, 0, 409,
+      2748, 3554, 465, 765, 1065, 465, 765, 1065, 694, 819, 819, 1716, 994, 1087, 1024, 1646,
+      1646, 512, 2048, 1024, 342, 799, 799, 1888, 1501, 1501, 1018, 1303, 1024, 1024, 1024, 690,
+      1646, 1024, 921, 2048, 1646, 1716, 1200, 1358, 1716, 1716, 651, 1633, 1716, 651, 651, 455,
+      0, 0, 0, 0, 0, -1, -1, -1, -1, -1, 0, 0, 0, 0, 0, 0,
+    ],
+  ],
+  // superscripts and subscripts
+  [
+    0x2070,
+    [
+      821, 366, -1, -1, 821, 821, 821, 821, 821, 821, 1081, 1081, 1081, 503, 503, 816,
+      821, 821, 821, 821, 821, 821, 821, 821, 821, 821, 1081, 1081, 1081, 503, 503, -1,
+      802, 854, 847, 909, 854, 828, 872, 340, 1276, 816, 877, 764, 604, -1, -1, -1,
+    ],
+  ],
+  // currency
+  [
+    0x20a0,
+    [
+      1796, 1303, 1303, 1303, 1303, 1995, 1303, 2606, 2199, 2025, 1606, 1303, 1303, 1303, 1303, 2606,
+      1303, 1303, 1303, 1303, 1585, 1303, -1, -1, 1303, 1303, 1303, -1, -1, 1303, -1, -1,
+      -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+    ],
+  ],
+  // letterlike symbols, number forms
+  [
+    0x2100,
+    [
+      2086, 2086, 1430, 2300, 1315, 2086, 2185, 1258, 1430, 1949, -1, 2024, 1545, 1740, 1298, 1298,
+      962, 1428, 1475, 846, 1675, 1640, 2130, 2048, 1428, 1436, 1612, 1634, 1667, 1622, 1836, 1401,
+      2088, 2200, 2048, 1401, 1525, 1183, 1565, 1565, 1262, 693, 1343, 1401, 1610, 1440, 1750, 1212,
+      1240, 1610, 1178, 2190, 946, 1526, 1380, 954, 1320, 778, 1896, 2445, 1438, 1490, 1340, 1738,
+      1660, 1587, 1141, 1141, 1251, 1677, 1450, 1260, 719, 719, -1, 1597, -1, -1, 1078, -1,
+      1985, 1985, 2806, 1985, 1985, 1985, 1985, 1985, 1985, 1985, 1985, 1985, 1985, 1985, 1985, 1163,
+      604, 1008, 1412, 1890, 1401, 1889, 2293, 2697, 1879, 1403, 1911, 2317, 1141, 1430, 1577, 1767,
+      569, 937, 1305, 1662, 1212, 1661, 2029, 2397, 1677, 1212, 1684, 2052, 569, 1126, 1300, 1995,
+      2550, 1577, 2550, 1440, 1125, 1430, -1, -1, -1, 1985, -1, -1, -1, -1, -1, -1,
+    ],
+  ],
+  // arrows, mathematical operators
+  [
+    0x2190,
+    [
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1401, 1303, 1059, 1294, 1294, 1784, 1370, 1370, 1784, 1784, 1470, 1784, 1784, 1470, 1303, 1550,
+      1550, 1380, 1716, 1716, 1716, 690, 1304, 1716, 1282, 1282, 1305, 1305, 1305, 1463, 1706, 1716,
+      1836, 1836, 1716, 1024, 1024, 1024, 1024, 1499, 1499, 1499, 1499, 1067, 1616, 2165, 1067, 1616,
+      2165, 1067, 1067, 1067, 1303, 1303, 533, 1303, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      768, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1718, 1718, 2048, 2048, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 2144, 2144, 950, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1499, 1499, 1499, 1716,
+      1716, 1716, 1716, 1598, 1598, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1784, 1784, 1784, 1784, 1066, 1066, 1784, 1784, 1784, 1784, 1784, 1784, 1784, 1784,
+      1716, 1716, 1716, 1716, 1716, 1716, 2048, 2048, 1716, 1716, 1066, 1499, 1499, 1499, 1716, 1716,
+      1680, 1680, 1680, 1680, 1282, 651, 1282, 1716, 2048, 2048, 2048, 2048, 2048, 1716, 1500, 1500,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 2913, 2913, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 2048, 2048,
+      2048, 2048, 2048, 1784, 1470, 1784, 1784, 1470, 1784, 1784, 2048, 1784, 1470, 1784, 1470, 1784,
+    ],
+  ],
+];

package/src/reference/types.ts

@@ -1,5 +1,3 @@
-export type EditorialStatus = 'draft' | 'in-review' | 'reviewed';
-
 export interface SourceSpan {
   readonly file: string;
   readonly line?: number;
@@ -19,7 +17,13 @@ export type NotationAlignment =
       readonly rationale: string;
     };
 
-export type NotationReferenceKind = 'prose' | 'math' | 'definition';
+/**
+ * Where a reference was written: in prose, in math, in a definition's meaning
+ * or body, or in its `formula`. A formula's references bring their cards onto
+ * the page but are no dependency: two formulas may name each other
+ * (γ = 1 − α, α = 1 − γ).
+ */
+export type NotationReferenceKind = 'prose' | 'math' | 'definition' | 'formula';
 
 /**
  * A gloss resolved by the loader (D15). Declared on a card, keyed
@@ -50,10 +54,17 @@ export interface SharedNotationDefinitionInput {
   readonly domain: string;
   readonly formula?: string;
   readonly units?: string;
+  /** Rule N23: an index entry's title for what it indexes, `{base} …`. */
+  readonly reads?: string;
+  /** Rule N23: the set a running index letter runs over. */
+  readonly range?: string;
+  /** Rule N23: as an index, a fixed label rather than a running position. */
+  readonly fixedIndex?: true;
+  /** Rule N23: an index entry's `formula` as written, `{base}` unbound. */
+  readonly formulaTemplate?: string;
   readonly sources: readonly string[];
   readonly seeAlso: readonly string[];
   readonly alignment: NotationAlignment;
-  readonly status: EditorialStatus;
   readonly aiAssisted: boolean;
   readonly body: string;
   /** References harvested from the Markdown body. */
@@ -70,6 +81,14 @@ export interface LocalNotationDefinitionInput {
   readonly summary: string;
   readonly formula?: string;
   readonly units?: string;
+  /** Rule N23: an index entry's title for what it indexes, `{base} …`. */
+  readonly reads?: string;
+  /** Rule N23: the set a running index letter runs over. */
+  readonly range?: string;
+  /** Rule N23: as an index, a fixed label rather than a running position. */
+  readonly fixedIndex?: true;
+  /** Rule N23: an index entry's `formula` as written, `{base}` unbound. */
+  readonly formulaTemplate?: string;
   readonly sources: readonly string[];
   readonly seeAlso: readonly string[];
   readonly alignment: NotationAlignment;
@@ -94,7 +113,6 @@ export interface NotationSuspension {
 
 export interface NotationLessonInput {
   readonly lessonId: string;
-  readonly status: EditorialStatus;
   readonly localDefinitions: readonly LocalNotationDefinitionInput[];
   /**
    * Decorations this page suspends (`notation.suspend`, rule N22). Optional
@@ -144,11 +162,12 @@ export type NotationDiagnosticCode =
   | 'undefined-reference'
   | 'reference-cycle'
   | 'unused-definition'
+  | 'local-shadows-shared'
+  | 'malformed-reference'
   | 'alignment-unknown-competency'
   | 'alignment-unknown-lesson'
   | 'alignment-introduction'
   | 'alignment-unavailable'
-  | 'alignment-review-state'
   | 'gloss-collides-with-card';
 
 export type DiagnosticSeverity = 'error' | 'warning' | 'info';
@@ -188,9 +207,16 @@ interface NotationDefinitionRecordBase {
   readonly scope: NotationDefinitionScope;
   readonly notation: string;
   readonly label: string;
+  /** Rule N23: an index entry's title for what it indexes, `{base} …`. */
+  readonly reads?: string;
+  /** Rule N23: the set a running index letter runs over. */
+  readonly range?: string;
+  /** Rule N23: as an index, a fixed label rather than a running position. */
+  readonly fixedIndex?: true;
+  /** Rule N23: an index entry's `formula` as written, `{base}` unbound. */
+  readonly formulaTemplate?: string;
   readonly seeAlso: readonly string[];
   readonly alignment: NotationAlignment;
-  readonly status: EditorialStatus;
   readonly source: SourceSpan;
   readonly resolvedReferences: readonly ResolvedNotationReference[];
 }
@@ -226,7 +252,6 @@ export interface NotationBinding {
 
 export interface NotationPageBundle {
   readonly lessonId: string;
-  readonly status: EditorialStatus;
   readonly source: SourceSpan;
   readonly bindings: readonly NotationBinding[];
   readonly definitionIds: readonly string[];
@@ -245,3 +270,45 @@ export interface NotationRegistry {
   readonly backlinks: readonly NotationBacklink[];
   readonly diagnostics: readonly NotationDiagnostic[];
 }
+
+/** A derived card a math source uses (rule N23): `key` is `<base>.sub.<index>`. */
+export interface DerivedUse {
+  readonly key: string;
+  readonly base: string;
+  readonly index: string;
+}
+
+/**
+ * How one symbol with a subscript is explained (rule N23), as
+ * `resolveMathGlyphs` reports it in `indices`.
+ */
+export interface IndexedSymbol {
+  readonly token: string;
+  readonly start: number;
+  readonly end: number;
+  readonly base: string;
+  readonly index: string;
+  readonly how:
+    | 'whole-form'
+    | 'family'
+    | 'derived'
+    | 'inside-form'
+    | 'explicit'
+    | 'swallowed'
+    | 'inside-wrap'
+    | 'composed'
+    | 'unresolved';
+  readonly key: string | null;
+  readonly explained: boolean;
+  readonly baseExplained: boolean;
+  /** The parts no card explains: the base first, when it has none, then each slot. */
+  readonly unexplained: readonly string[];
+  /** Running index letters (`i`, `k`, `t`) in its slots, for the index-set check. */
+  readonly running: readonly {
+    readonly letter: string;
+    readonly start: number;
+    readonly end: number;
+    readonly key: string | null;
+    readonly cover: string | null;
+  }[];
+}

package/src/rules/catalog.ts

@@ -168,6 +168,7 @@ const GATE_MATH: Emitter = { module: 'src/reference/gate-math.ts', fn: 'resolveI
 const GLYPHS: Emitter = { module: 'src/reference/math-glyphs.mjs', fn: 'resolveMathGlyphs' };
 const REGISTRY: Emitter = { module: 'src/reference/registry.ts', fn: 'buildNotationRegistry' };
 const KEYED_FLOATS: Emitter = { module: 'src/reference/keyed-float-validate.ts', fn: 'validateKeyedFloats' };
+const INDICES: Emitter = { module: 'src/reference/gate-indices.ts', fn: 'gateIndices' };
 
 function consistency(fn: string): Emitter {
   return { module: 'src/reference/consistency.ts', fn };
@@ -203,6 +204,15 @@ function keyedFloatChecks(): RuleCheck[] {
       check(`${prefix}-duplicate-key`, 'error', false, emitter),
       check(`${prefix}-ref-resolves`, 'error', false, emitter),
     );
+    // A display block is one numbered equation: a second `\label` in it
+    // would name nothing.
+    if (prefix === 'eq') {
+      out.push(
+        check('eq-label-repeated', 'error', false, emitter),
+        // LaTeX's `\eqref{eq:key}` in prose, which MDX cannot parse.
+        check('eq-latex-ref', 'error', false, emitter),
+      );
+    }
     if (prefix === 'tab' || prefix === 'fig' || prefix === 'dia' || prefix === 'ex') {
       out.push(check(`${prefix}-key-unused`, 'info', false, emitter));
       // A prop that is gone: a name prop the caption pair (`caption` +
@@ -212,6 +222,20 @@ function keyedFloatChecks(): RuleCheck[] {
       // JSX float; a table never had one to remove.
       out.push(check(`${prefix}-removed-prop`, 'error', false, emitter));
     }
+    // A `short={…}` / `caption={…}` the manifest cannot read: a reference's
+    // card, a copied link and the float index name the float without it.
+    if (prefix !== 'eq' && prefix !== 'check') {
+      out.push(check(`${prefix}-unread-prop`, 'warning', false, emitter));
+    }
+    // A `<Table>` holding a second table, which every export would drop.
+    if (prefix === 'tab') {
+      out.push(
+        check('tab-several-tables', 'error', false, {
+          module: 'src/reference/tables-validate.ts',
+          fn: 'validateTables',
+        }),
+      );
+    }
   }
   // A worked-example set cannot do without its `id` (its anchor and
   // `[[ex-…]]`) or its `short` title (its heading after the "Example" badge).
@@ -221,13 +245,18 @@ function keyedFloatChecks(): RuleCheck[] {
       fn: 'validateExamples',
     }),
   );
-  // A section's key is its heading's anchor, which the slugger makes unique,
-  // so only the reference can go wrong.
+  // A section's key is its heading's anchor, which the slugger makes unique
+  // among headings; the reference can go wrong, and so can an anchor the
+  // engine already gives a float, a memo or the References section.
   out.push(
     check('sec-ref-resolves', 'error', true, {
       module: 'src/reference/sections-validate.ts',
       fn: 'validateSectionRefs',
     }),
+    check('heading-anchor-collision', 'error', true, {
+      module: 'src/reference/sections-validate.ts',
+      fn: 'validateHeadingAnchors',
+    }),
   );
   // A `<Fold>` is named by its `label`, or by the numbered floats it holds;
   // one with neither has an empty bar.
@@ -356,7 +385,7 @@ const RULES: readonly RuleEntry[] = [
     elements: ['prose', 'assessment', 'table'],
     doc: 'notation.md#n9',
     summary:
-      'Never write `45 m/s`, `t (s)`, `vx` or `KE/m` as plain text, and never spell a stated quantity\'s unit out: "4 seconds", "2 meters per second squared", "30 degrees", "$x = 3$ meters" are `$4\\ \\text{s}$`, `$2\\ \\text{m/s}^2$`, `$30^{\\circ}$`, `$x = 3\\ \\text{m}$`. A unit inside math is `\\text{}`-wrapped, short form, in the same span as its number or symbol. A unit named on its own ("measured in meters") stays a word; a sentence that defines a unit is waived. JSX prop strings (`caption="…"`) and assessment choice labels render no math, so N9 does not apply there.',
+      'Never write `45 m/s`, `t (s)`, `vx` or `KE/m` as plain text, and never spell a stated quantity\'s unit out: "4 seconds", "2 meters per second squared", "30 degrees", "$x = 3$ meters" are `$4\\ \\text{s}$`, `$2\\ \\text{m/s}^2$`, `$30^{\\circ}$`, `$x = 3\\ \\text{m}$`. A unit inside math is `\\text{}`-wrapped, short form, in the same span as its number or symbol. A unit named on its own ("measured in meters") stays a word; a sentence that defines a unit is waived. JSX prop strings (`caption="…"`) render no math, so N9 does not apply there; nor does it apply to an assessment choice label, which may still hold math (`$30^{\\circ}$`).',
     checks: [
       check(
         'prose-notation',
@@ -530,7 +559,7 @@ const RULES: readonly RuleEntry[] = [
     elements: ['notation'],
     doc: 'notation.md#n19',
     summary:
-      'Every notation entry has `units:` from `units-vocab.ts` (`m/s`, `s`, `kg`, …) or `dimensionless: true`. A token outside the vocabulary is a warning.',
+      'Every notation entry has `units:` from `units-vocab.ts` (`m/s`, `s`, `kg`, …) or `dimensionless: true`, except an index entry (`latex: "{}_0"`, N23), which takes neither. A token outside the vocabulary is a warning.',
     checks: [
       check('notation-units', 'warning', false, consistency('checkNotationUnits')),
       check('units-vocab', 'warning', false, consistency('checkNotationUnits')),
@@ -557,7 +586,7 @@ const RULES: readonly RuleEntry[] = [
     elements: ['notation'],
     doc: 'notation.md#n21',
     summary:
-      'A gloss `label` names the symbol in a few words (“launch angle”); a clause, sentence punctuation, or a definition belongs in a full notation entry instead.',
+      'A gloss `name` names the symbol in a few words (“launch angle”); a clause, sentence punctuation, or a definition belongs in a full notation entry instead.',
     checks: [check('gloss-name-shape', 'warning', false, consistency('checkGlossNameShape'))],
   },
   {
@@ -572,6 +601,7 @@ const RULES: readonly RuleEntry[] = [
       'A decoration (`\\hat`, `\\bar`, `\\overline`, `\'`, `^*`, `^\\dagger`, …) is on the course’s `allow` list (shipped empty), explained by an operator entry (`latex: \\hat{}`), or the decorated form has its own entry (`latex: \\hat{\\beta}`), which wins for that form. A page may suspend a decoration in `notation.suspend`, with a `reason`; every decorated form of it there then needs its own entry.',
     checks: [
       check('accent-explained', 'warning', false, consistency('checkAccentExplained')),
+      check('accent-swallowed', 'warning', false, consistency('checkAccentExplained')),
       check('suspended-operator-unresolved', 'error', true, GATE_MATH),
       check('operator-suspension-reason', 'warning', false, consistency('checkOperatorSuspension')),
       check('operator-suspended', 'info', false, consistency('checkOperatorSuspension')),
@@ -579,6 +609,25 @@ const RULES: readonly RuleEntry[] = [
     ],
     settings: baselineEdits('Decorations'),
   },
+  {
+    kind: 'rule',
+    id: 'N23',
+    short: 'An index is part of the symbol: whole form, family or index entry',
+    title:
+      'An index is part of the symbol: a subscript is explained by the indexed symbol’s entry, a family entry, or an index entry.',
+    elements: ['math', 'notation'],
+    doc: 'notation.md#n23',
+    summary:
+      'A subscript on a symbol is explained by the indexed symbol’s own entry (`latex: v_0`), a family entry whose index runs (`latex: x_k` explains `x_1`), or an index entry for the subscript (`latex: "{}_0"`, which composes a derived card); a card on the base alone does not explain it, and arithmetic on an index letter with its own card does (`X_{t-1}`). A running index — a lowercase letter not marked `fixedIndex` — states its set, as `range` on its card or after a `\\quad` on the first display line that uses it. Never wrap an indexed symbol in `\\explain` with a key whose `latex` has no index.',
+    checks: [
+      check('index-explained', 'error', true, INDICES),
+      check('index-swallowed', 'error', true, INDICES),
+      check('index-range', 'error', true, INDICES),
+      check('derived-key-taken', 'error', true, INDICES),
+    ],
+    unchecked:
+      'whether a `\\quad` clause states the set correctly; whether a lowercase index is really running; lab math whose glyph table is a copy of the one `labMathScope` returned.',
+  },
 
   // ---- V — visualizations -----------------------------------------------------
   {
@@ -613,12 +662,16 @@ const RULES: readonly RuleEntry[] = [
     elements: ['plot'],
     doc: 'visualizations.md#v3',
     summary:
-      'An interactive figure is an island under `content/labs/` inside a `<Figure>`, renders its equations through `renderLabMath` (`{ display: false }` for a legend, an axis title or a label; a `{ math }` run for the caption clause) and never KaTeX directly, and labels its controls; the figure’s caption is its name, so the lab writes no accessible name or text alternative of its own.',
+      'An interactive figure is an island under `content/labs/` inside a `<Figure>`, renders its equations through `renderLabMath` (`{ display: false }` for a legend, an axis title or a label; a `{ math }` run for the caption clause) and never KaTeX directly, and labels its controls; the figure’s caption is its name, so the lab writes no accessible name or text alternative of its own. Its default picture is drawn at build time too and handed to the island as children, so the built page has it.',
     checks: [
       check('lab-katex-direct', 'error', false, {
         module: 'src/reference/lab-katex-validate.ts',
         fn: 'validateLabKatexImports',
       }),
+      check('lab-picture-undrawn', 'warning', false, {
+        module: 'src/reference/figure-pictures.ts',
+        fn: 'undrawnFigurePictures',
+      }),
     ],
     unchecked:
       'that a lab labels its controls and writes no name of its own, and math a lab draws without importing `katex` — the build’s rendered check (`figure-symbols.ts`) covers the page it renders.',
@@ -673,6 +726,57 @@ const RULES: readonly RuleEntry[] = [
       },
     ],
   },
+  {
+    kind: 'rule',
+    id: 'V7',
+    short: 'A figure’s picture fits on one screen',
+    title: 'A figure’s picture takes at most `maxPercent` of the screen height.',
+    elements: ['plot'],
+    doc: 'visualizations.md#v7',
+    summary:
+      'The default slot of a `<Figure>` — plot, key and tables — stays within `maxPercent` of the viewport height, so the reader sees the picture and its caption line together. A square or tall plot gets a fixed width instead of the full column.',
+    checks: [
+      check('figure-too-tall', 'warning', false, {
+        module: 'src/reference/figure-fit.ts',
+        fn: 'checkFigureFit',
+      }),
+    ],
+    unchecked:
+      'any page or viewport the course’s Playwright suite does not open — the check runs in the browser, not in the build.',
+    settings: [
+      {
+        key: 'maxPercent',
+        title: 'Largest picture height (% of screen)',
+        description: 'How much of the viewport height a figure’s picture may take.',
+        schema: { type: 'integer', minimum: 10, default: 80 },
+      },
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'V8',
+    short: 'A diagram fits the lesson column',
+    title: 'A diagram is no wider than the lesson column.',
+    elements: ['diagram'],
+    doc: 'visualizations.md#v8',
+    summary:
+      'A `<Diagram>` lays out no wider than `columnWidth`, the lesson column at a 1366px-wide window, so the reader sees the whole graph without scrolling it. Narrow it with `direction="TB"`, a shorter label or a node `width` (its label wraps inside it); `warnAboveWidth={false}` marks a diagram meant to scroll.',
+    checks: [
+      check('dia-too-wide', 'warning', false, {
+        module: 'src/reference/diagram-fit.ts',
+        fn: 'oversizedDiagrams',
+      }),
+    ],
+    settings: [
+      {
+        key: 'columnWidth',
+        title: 'Column width (px)',
+        description:
+          'The widest a diagram may lay out: the lesson column at the window width the course is read at most (707px at 1366px).',
+        schema: { type: 'integer', minimum: 200, default: 707 },
+      },
+    ],
+  },
 
   // ---- C — versioning ---------------------------------------------------------
   {
@@ -838,24 +942,6 @@ const RULES: readonly RuleEntry[] = [
       }),
     ],
   },
-  {
-    kind: 'rule',
-    id: 'S5',
-    short: 'A sign / perspective convention is declared once and cited elsewhere',
-    title: 'A sign or perspective convention is declared once and cited everywhere else.',
-    elements: ['prose'],
-    doc: 'structure-rules.md#s5',
-    summary:
-      'Prose that states a sign / cash-flow-perspective convention resolves it to the single declaration — the `conventions.signConventionKey` notation entry (`[[key]]`) or the `conventions.cashFlowPerspectiveCompetency` competency — rather than restating it.',
-    checks: [
-      check(
-        'convention-single-definition',
-        'warning',
-        false,
-        consistency('checkConventionSingleDefinition'),
-      ),
-    ],
-  },
   {
     kind: 'rule',
     id: 'S6',
@@ -871,6 +957,12 @@ const RULES: readonly RuleEntry[] = [
         module: 'src/reference/gate-heading-structure.ts',
         fn: 'gateHeadingStructure',
       }),
+      // A knowledge check or a worked-example set, which draws an `<h2>`,
+      // inside a memo or a short note.
+      check('heading-nested', 'error', true, {
+        module: 'src/reference/gate-heading-structure.ts',
+        fn: 'gateHeadingStructure',
+      }),
     ],
   },
   {
@@ -1111,6 +1203,13 @@ const RETIRED: readonly RetiredRule[] = [
     into: 'C3',
     why: 'The release procedure and the invariant it keeps are one rule, and `knowledge-changelog-missing` (owned by C3) was already the check that fired on a half-finished release.',
   },
+  {
+    id: 'S5',
+    title: 'A sign or perspective convention is declared once and cited everywhere else.',
+    date: '2026-10-07',
+    into: 'N4',
+    why: 'Its check knew one finance course’s phrasing and one key per course, and never fired in any course; the `conventions` setting it read is gone. A convention is a definition, so it is now N4’s: defined once on its notation entry, whose `meaning` names the other choice and whose body says how to convert.',
+  },
 ];
 
 const INVARIANTS: readonly InvariantEntry[] = [
@@ -1121,7 +1220,7 @@ const INVARIANTS: readonly InvariantEntry[] = [
     elements: ['notation', 'math'],
     doc: 'components.md#reference-systems',
     summary:
-      'A `[[key]]` or `\\explain{key}{…}` names an existing entry; a key is kebab-case; a shared entry is defined once; formula references never form a cycle.',
+      'A `[[key]]` or `\\explain{key}{…}` names an existing entry; a key is kebab-case; a shared entry is defined once; references in meanings and bodies never form a cycle (formulas may name each other).',
     checks: [
       check('undefined-reference', 'error', false, REGISTRY),
       check('invalid-key', 'error', false, REGISTRY, GLYPHS),
@@ -1137,6 +1236,10 @@ const INVARIANTS: readonly InvariantEntry[] = [
       }),
       check('malformed-explicit-binding', 'error', true, GLYPHS),
       check('unused-definition', 'info', false, REGISTRY),
+      // A page-local entry under a shared key: two meanings for one key.
+      check('local-shadows-shared', 'warning', false, REGISTRY),
+      // A `[[` that never closes, before the render fails on it.
+      check('malformed-reference', 'error', false, REGISTRY),
     ],
   },
   {
@@ -1157,6 +1260,11 @@ const INVARIANTS: readonly InvariantEntry[] = [
       check('ambiguous-base-fallback', 'error', true, GLYPHS),
       check('ambiguous-canonical-notation', 'error', false, GLYPHS),
       check('math-compile-error', 'error', true, GATE_MATH),
+      // `$5 to $6`: money remark-math reads as one math span.
+      check('currency-dollar', 'error', true, {
+        module: 'src/reference/gate-math.ts',
+        fn: 'gateContentMath',
+      }),
     ],
   },
   {
@@ -1176,7 +1284,7 @@ const INVARIANTS: readonly InvariantEntry[] = [
     elements: ['changelog'],
     doc: 'README.md#amending',
     summary:
-      'A `rules.<ID>` block names a live rule; a deprecated top-level key (`operators`, `romanLabels`, `abbreviations`) still works but warns until it is moved under `rules`.',
+      'A `rules.<ID>` block names a live rule; a deprecated top-level key (`operators`, `romanLabels`, `abbreviations`) still works but warns until it is moved under `rules`; `conventions` is ignored and warns until it is deleted.',
     checks: [
       check('config-deprecated-key', 'warning', false, {
         module: 'src/rules/settings.ts',
@@ -1223,8 +1331,10 @@ const INVARIANTS: readonly InvariantEntry[] = [
           'track-order',
           'assessment-coverage',
           'invalid-assessment',
-          'review-state',
+          'missing-assumptions',
           'teaches-support',
+          // `[text [@id]](url)`: a citation the page prints as typed.
+          'citation-in-link',
         ] as const
       ).map((code) =>
         check(code, 'error', false, {
@@ -1238,7 +1348,6 @@ const INVARIANTS: readonly InvariantEntry[] = [
           'alignment-unknown-lesson',
           'alignment-introduction',
           'alignment-unavailable',
-          'alignment-review-state',
         ] as const
       ).map((code) =>
         check(code, 'error', false, {
@@ -1246,7 +1355,74 @@ const INVARIANTS: readonly InvariantEntry[] = [
           fn: 'validateNotationAlignment',
         }),
       ),
-    ] as [RuleCheck, ...RuleCheck[]],
+      // A course's parts and the lessons in them (`compileManifest`): a
+      // lesson in a directory no part lists, and a part with nothing in it yet.
+      check('lesson-outside-parts', 'error', false, {
+        module: 'src/compiler/manifest.ts',
+        fn: 'compileManifest',
+      }),
+      check('part-empty', 'warning', false, {
+        module: 'src/compiler/manifest.ts',
+        fn: 'compileManifest',
+      }),
+    ] as unknown as [RuleCheck, ...RuleCheck[]],
+  },
+  {
+    kind: 'invariant',
+    id: 'content-schema',
+    title: 'Every content file satisfies its collection’s schema.',
+    elements: ['notation', 'assessment', 'source', 'changelog'],
+    doc: 'structure.md#content-schemas',
+    summary:
+      'A page’s explico fields, a notation entry, an abbreviation, a competency, an assessment, a source and a track match the schema `astro build` loads them with (`compiler/content-schemas.ts`); `validate:content` reports the field and its line.',
+    checks: [
+      check('content-schema', 'error', false, {
+        module: 'src/compiler/content-schema.ts',
+        fn: 'validateContentSchemas',
+      }),
+    ],
+  },
+  {
+    kind: 'invariant',
+    id: 'retired-keys',
+    title: 'No content file sets a key the engine has retired or cannot honour.',
+    elements: ['changelog'],
+    doc: 'structure.md#retired-keys',
+    summary:
+      'A frontmatter or JSON key explico no longer reads (`editorialStatus`) fails the build at every file that still sets it; delete the line. A lesson’s `draft: true` fails it too (the sidebar would name a page the build drops), and its `sidebar.order` warns (chapters follow the tracks).',
+    checks: [
+      check('retired-key', 'error', false, {
+        module: 'src/reference/gate-retired-keys.ts',
+        fn: 'findRetiredKeys',
+      }),
+      check('unsupported-key', 'error', false, {
+        module: 'src/reference/gate-retired-keys.ts',
+        fn: 'findUnsupportedKeys',
+      }),
+      check('ignored-key', 'warning', false, {
+        module: 'src/reference/gate-retired-keys.ts',
+        fn: 'findUnsupportedKeys',
+      }),
+    ],
+  },
+  {
+    kind: 'invariant',
+    id: 'prop-text',
+    title: 'A component’s quoted prop holds plain text, and prose holds no `{…}` expression.',
+    elements: ['math', 'plot', 'diagram', 'table'],
+    doc: 'components.md#props-are-plain-text',
+    summary:
+      'A quoted prop (`caption="…"`, `short="…"`, `title="…"`, `label="…"`) reaches the page as plain text: no KaTeX, reference or citation runs in it. `$…$`, `[[…]]` or `[@…]` in one fails the build, since it would print as typed; write the symbol in Unicode or words, and reference or cite from the prose next to the component. MDX reads `{…}` in prose as JavaScript (`{a}` fails the build, "a is not defined"): write `\\{a\\}`, or `$\\{a\\}$` for a set.',
+    checks: [
+      check('markup-in-prop', 'error', false, {
+        module: 'src/reference/gate-prop-text.ts',
+        fn: 'findMarkupInProps',
+      }),
+      check('mdx-expression', 'error', false, {
+        module: 'src/reference/gate-mdx-expression.ts',
+        fn: 'gateMdxExpressions',
+      }),
+    ],
   },
 ];