explico 0.8.0 → 0.11.1

package/src/content-config.ts

@@ -124,19 +124,31 @@ const notationEntryShape = z.object({
 
 const localNotationDefinition = notationEntryShape;
 
+/**
+ * One `notation.suspend` item (rule N22): a decoration (`'`, `\hat`, …) that
+ * is not an operator on this page. The loader (`collections.ts`) checks the
+ * name against the decorations the resolver knows.
+ */
+const notationSuspension = z.object({
+  operator: z.string().min(1),
+  reason: z.string().min(1).optional(),
+});
+
 const lessonNotation = z
   .object({
     // `notation.uses` is retired (D3): a lesson pulls a shared key into scope
     // by referencing it in prose (`[[key]]`) or math (`\explain`).
     local: z.array(localNotationDefinition).default([]),
+    suspend: z.array(notationSuspension).default([]),
   })
-  .default({ local: [] });
+  .default({ local: [], suspend: [] });
 
 /**
  * Lesson frontmatter — reduced shape (Phase C1 schema, C2 codemod applied).
  *
  * Authored:  `title`, `description` (Starlight base), `teaches` (ordered — the
  *            curriculum contract, never derived), `assumptions`,
+ *            `studyMinutes` (optional reader-facing estimate),
  *            `notation.local` (page-local symbols only).
  * Artifact:  `editorialStatus` (human-set trust flag).
  * Derived (in `content/collections.ts` + `content/lesson-derivation.ts`, never
@@ -144,10 +156,33 @@ const lessonNotation = z
  *            prerequisites of `teaches`, minus `teaches`), `sources` (`[@…]`
  *            occurrences), `assessments` (colocated `<lesson>.checks.yml`),
  *            `sidebar` order (track order).
- * Dropped:   `aiAssisted`, `lastReviewed`, `riskTier`, `estimatedMinutes`
- *            (git history + `editorialStatus` + `NEEDS_SOURCE` carry provenance);
- *            `notation.uses` (D3 — a shared symbol is imported by using it).
+ * Dropped:   `aiAssisted`, `lastReviewed`, `riskTier` (git history +
+ *            `editorialStatus` + `NEEDS_SOURCE` carry provenance);
+ *            `estimatedMinutes`, whose reader-facing half returned as the
+ *            optional `studyMinutes` once part pages had somewhere to total
+ *            it; `notation.uses` (D3 — a shared symbol is imported by using
+ *            it).
+ */
+/**
+ * How long this chapter takes to study: `40`, or a `[low, high]` range in
+ * minutes. It is a reader-facing estimate the author makes, aggregated by
+ * `<PartOverview>` and `<CourseContents>` into a part and course total — not
+ * the provenance field `estimatedMinutes` used to be, and nothing derives it.
+ *
+ * A part only reports a total when every one of its chapters states one, so a
+ * half-annotated course shows the chapters it knows about and no misleading
+ * sum.
  */
+const studyMinutes = z
+  .union([
+    z.number().int().positive(),
+    z.tuple([z.number().int().positive(), z.number().int().positive()]),
+  ])
+  .refine((value) => !Array.isArray(value) || value[0] <= value[1], {
+    message:
+      'studyMinutes as a range is [low, high]; the low end cannot exceed the high end.',
+  });
+
 const docs = defineCollection({
   loader: docsGlob,
   schema: docsSchema({
@@ -155,6 +190,7 @@ const docs = defineCollection({
       editorialStatus: editorialStatus.default('draft'),
       teaches: z.array(id).default([]),
       assumptions: z.array(z.string().min(1)).default([]),
+      studyMinutes: studyMinutes.optional(),
       notation: lessonNotation,
     }),
   }),

package/src/reference/base-accents.mjs

@@ -0,0 +1,31 @@
+/**
+ * The base accent baseline: decorations every reader is assumed to know, so a
+ * lesson never has to explain them (rule N22). The named-operator counterpart
+ * is `base-operators.mjs` (rule N8).
+ *
+ * It ships **empty**, because no decoration has one meaning across fields:
+ * `\hat` can mean an estimator, a unit vector or a Fourier transform; `\bar`
+ * a mean, a conjugate or a closure; `'` a derivative or "another one". A
+ * course that uses one consistently says so with `rules.N22.allow` (a physics
+ * course might allow `\dot` and `\vec`); anything else is explained by an
+ * operator entry (`latex: \hat{}`) or a whole-form entry (`latex:
+ * \hat{\beta}`). Names are the canonical ones in `DECORATION_NAMES`
+ * (`math-glyphs.mjs`): `\hat`, `\overline`, `'`, `*`, `\dagger`, ….
+ */
+export const BASE_ACCENTS = Object.freeze(new Set());
+
+/**
+ * The decorations a course treats as universal, given its `rules.N22` block:
+ * the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} accents
+ * @returns {Set<string>}
+ */
+export function effectiveAccentAllowlist(accents) {
+  const allow = accents?.allow ?? [];
+  const deny = new Set(accents?.deny ?? []);
+  const effective = new Set(BASE_ACCENTS);
+  for (const name of allow) effective.add(name);
+  for (const name of deny) effective.delete(name);
+  return effective;
+}

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

@@ -5,8 +5,8 @@
  * (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.
+ * they are a typographic label to KaTeX, not a bindable symbol, so the
+ * format half of rule N10 says nothing about whether the label is 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.

package/src/reference/consistency.ts

@@ -24,12 +24,21 @@
  *                                     uses is on the shipped/course roman-label
  *                                     allowlist or carries a notation entry
  *                                     (rule N10)
+ *   (j) accent-explained             a decoration a lesson composes (`\hat`,
+ *                                     `'`, `^*`, …) is on the course accent
+ *                                     allowlist, explained by an operator entry,
+ *                                     or part of a whole-form entry (rule N22)
+ *   (k) operator-suspended /         a `notation.suspend` item, with or without
+ *       operator-suspension-reason   its reason, and a whole-form entry that
+ *       / operator-shadowed          shadows an operator the page does not
+ *                                     suspend (rule N22)
  *
  * Check (d) — the committed per-lesson resolution report — lives in
  * `src/content/resolution-report.ts`.
  */
 
 import type {
+  CourseAccents,
   CourseConventions,
   CourseOperators,
   CourseRomanLabels,
@@ -37,9 +46,19 @@ import type {
 import type { CurriculumCatalog } from '../curriculum/validation';
 import type { NotationSpec } from '../compiler/collections';
 import type { LintIgnore } from './lint-ignore';
+import { effectiveAccentAllowlist } from './base-accents.mjs';
 import { effectiveOperatorAllowlist } from './base-operators.mjs';
 import { effectiveRomanLabelAllowlist } from './base-roman-labels.mjs';
-import { collectOperators, collectRomanLabels } from './math-glyphs.mjs';
+import { stripEquationLabels } from './equations.mjs';
+import { pageScope } from './gate-math';
+import {
+  collectDecorations,
+  collectOperators,
+  collectRomanLabels,
+  decorationOfEntry,
+  operatorEntryLatex,
+  resolveMathGlyphs,
+} from './math-glyphs.mjs';
 import { offVocabularyTokens } from './units-vocab';
 import type {
   NotationDefinitionRecord,
@@ -58,7 +77,11 @@ export type ConsistencyCode =
   | 'card-wants-demoting'
   | 'gloss-name-shape'
   | 'operator-explained'
-  | 'roman-label-explained';
+  | 'roman-label-explained'
+  | 'accent-explained'
+  | 'operator-suspended'
+  | 'operator-suspension-reason'
+  | 'operator-shadowed';
 
 export interface ConsistencyDiagnostic {
   readonly code: ConsistencyCode;
@@ -85,6 +108,8 @@ export interface ConsistencyInput {
   readonly operators?: CourseOperators;
   /** This course's edits to the roman-label baseline (rule N10). */
   readonly romanLabels?: CourseRomanLabels;
+  /** This course's edits to the (empty) accent baseline (rule N22). */
+  readonly accents?: CourseAccents;
 }
 
 const CONVENTION_RE =
@@ -102,11 +127,17 @@ interface MathSpan {
   readonly latex: string;
 }
 
+/**
+ * Every `$$…$$` then `$…$` span in `body`, outside code. A `\label{eq:…}`
+ * (D7) is stripped: it is an identity marker KaTeX cannot parse, and the
+ * scans below treat an unparseable span as having nothing in it — so left in,
+ * every labelled display equation was invisible to rules N8, N10 and N22.
+ */
 function mathSpans(body: string): MathSpan[] {
   const searchable = stripCode(body);
   const spans: MathSpan[] = [];
   for (const match of searchable.matchAll(/\$\$([\s\S]+?)\$\$/g)) {
-    spans.push({ latex: match[1] ?? '' });
+    spans.push({ latex: stripEquationLabels(match[1] ?? '') });
   }
   for (const match of searchable
     .replace(/\$\$([\s\S]+?)\$\$/g, (block) => block.replace(/[^\n]/g, ' '))
@@ -508,8 +539,8 @@ function checkOperatorExplained(
 
 /**
  * (i) roman-label-explained (rule N10) — the `\mathrm{…}` twin of (h)
- * above: N3 requires the *format* (`\mathrm{KE}`, never bare `KE`) but has
- * no opinion on whether the label is ever explained, because the glyph
+ * above: N10's format half (`\mathrm{KE}`, never bare `KE`) says nothing
+ * about whether the label is ever explained, because the glyph
  * resolver skips a `\mathrm{…}` body whole. This is the check that looks at
  * them; it reads `collectRomanLabels`, which parses with the same pinned
  * KaTeX as the completeness gate.
@@ -566,6 +597,140 @@ function checkRomanLabelExplained(
   }
 }
 
+function sharedScopeByKey(
+  input: ConsistencyInput,
+): Map<string, { key: string; notation: string }> {
+  return new Map(
+    input.notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      { key: definition.key, notation: definition.notation },
+    ]),
+  );
+}
+
+/**
+ * (j) accent-explained (rule N22) — the decoration twin of (h): an accent or
+ * superscript mark a lesson *composes* (`\hat{\beta}` read as "hat applied to
+ * β") is universal for the course (`rules.N22.allow`; the shipped list is
+ * empty), explained by an operator entry in the page's scope (`latex:
+ * \hat{}`), or not composing at all because a whole-form entry covers it
+ * (`latex: \hat{\beta}`). Only the resolver knows which whole form covered an
+ * occurrence (`\theta^*` and `\theta^{*}` are one form), so this runs it over
+ * each span with the same page scope as the completeness gate. A span that
+ * will not resolve is the gate's to report, not this check's.
+ */
+function checkAccentExplained(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const allowlist = effectiveAccentAllowlist(input.accents);
+  const sharedByKey = sharedScopeByKey(input);
+
+  for (const lesson of input.notationInput.lessons) {
+    const scope = pageScope(lesson, sharedByKey);
+    const suspended = (lesson.suspended ?? []).map((item) => item.operator);
+    const reported = new Set<string>();
+    for (const span of mathSpans(lesson.body)) {
+      let decorations;
+      try {
+        ({ decorations } = resolveMathGlyphs(span.latex, scope, { suspended }));
+      } catch {
+        continue;
+      }
+      for (const decoration of decorations) {
+        if (decoration.wholeForm !== null || decoration.operator !== null) continue;
+        // A suspended decoration never composes; the gate fails it instead.
+        if (suspended.includes(decoration.name)) continue;
+        if (allowlist.has(decoration.name)) continue;
+        if (reported.has(decoration.name)) continue;
+        reported.add(decoration.name);
+        if (input.lintIgnore.matches('accent-explained', decoration.name)) {
+          continue;
+        }
+        out.push({
+          code: 'accent-explained',
+          severity: 'warning',
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          glyph: decoration.name,
+          message: `${lesson.lessonId}: decoration ${JSON.stringify(decoration.name)} (in ${JSON.stringify(decoration.token)}) is an operator that is neither universal for this course nor explained; give it an operator entry (latex ${JSON.stringify(operatorEntryLatex(decoration.name))}) introduced with [[key]] or in notation.local, give the whole form its own entry (latex ${JSON.stringify(decoration.token)}), or add ${JSON.stringify(decoration.name)} to rules.N22.allow`,
+        });
+      }
+    }
+  }
+}
+
+/**
+ * (k) operator-suspended / operator-suspension-reason / operator-shadowed
+ * (rule N22). A `notation.suspend` item is a deliberate departure from N22 on
+ * one page: with its `reason` it is recorded (info), without one it is a
+ * warning — the reason is what a reviewer needs. And a whole-form entry whose
+ * decoration is explained or universal on its page, but not suspended there,
+ * is noted (info): the entry's card wins for that form, which is right for a
+ * refinement ("β̂ is the OLS estimate") and a smell when the decoration never
+ * means the operator on that page.
+ */
+function checkOperatorSuspension(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const allowlist = effectiveAccentAllowlist(input.accents);
+  const sharedByKey = sharedScopeByKey(input);
+
+  for (const lesson of input.notationInput.lessons) {
+    const suspensions = lesson.suspended ?? [];
+    for (const { operator, reason } of suspensions) {
+      const code =
+        reason === undefined ? 'operator-suspension-reason' : 'operator-suspended';
+      if (input.lintIgnore.matches(code, operator)) continue;
+      out.push({
+        code,
+        severity: reason === undefined ? 'warning' : 'info',
+        lessonId: lesson.lessonId,
+        file: lesson.source.file,
+        glyph: operator,
+        message:
+          reason === undefined
+            ? `${lesson.lessonId}: notation.suspend suspends ${JSON.stringify(operator)} with no reason; say why it is not an operator on this page (reason: …)`
+            : `${lesson.lessonId}: ${JSON.stringify(operator)} is not an operator on this page (notation.suspend): ${reason}`,
+      });
+    }
+
+    const suspended = new Set(suspensions.map((item) => item.operator));
+    const scope = pageScope(lesson, sharedByKey);
+    const explained = new Set(
+      scope
+        .map((entry) => decorationOfEntry(entry.notation))
+        .filter((name): name is string => name !== undefined),
+    );
+    for (const entry of scope) {
+      if (decorationOfEntry(entry.notation) !== undefined) continue;
+      const names = new Set(
+        collectDecorations(entry.notation).map((decoration) => decoration.name),
+      );
+      for (const name of names) {
+        if (suspended.has(name)) continue;
+        const how = explained.has(name)
+          ? 'explained by an operator entry'
+          : allowlist.has(name)
+            ? 'universal for this course'
+            : undefined;
+        if (how === undefined) continue;
+        if (input.lintIgnore.matches('operator-shadowed', entry.key)) continue;
+        out.push({
+          code: 'operator-shadowed',
+          severity: 'info',
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          key: entry.key,
+          glyph: name,
+          message: `${lesson.lessonId}: ${entry.key} (${entry.notation}) has its own entry, so its card wins over the ${JSON.stringify(name)} operator (${how}) for that form; if ${JSON.stringify(name)} never means the operator on this page, suspend it (notation.suspend)`,
+        });
+      }
+    }
+  }
+}
+
 const CHECKS: ((
   input: ConsistencyInput,
   out: ConsistencyDiagnostic[],
@@ -580,6 +745,8 @@ const CHECKS: ((
   checkGlossNameShape,
   checkOperatorExplained,
   checkRomanLabelExplained,
+  checkAccentExplained,
+  checkOperatorSuspension,
 ];
 
 /**
@@ -618,6 +785,10 @@ export function consistencyCounts(
     'gloss-name-shape': 0,
     'operator-explained': 0,
     'roman-label-explained': 0,
+    'accent-explained': 0,
+    'operator-suspended': 0,
+    'operator-suspension-reason': 0,
+    'operator-shadowed': 0,
   } satisfies Record<ConsistencyCode, number>;
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

package/src/reference/delimiter-size.ts

@@ -9,8 +9,9 @@
  *
  * This deliberately parses only sizing syntax. It does not decide whether a
  * parenthesis, bracket, or brace is semantic, and it never recommends changing
- * one delimiter shape into another. N16's alternating-shape preference remains
- * a review-only authoring concern.
+ * one delimiter shape into another — N17's other half, that a delimiter's shape
+ * is fixed by its meaning and never alternates to show depth, stays a
+ * review-only authoring concern (which is why N17 is `partial`).
  */
 
 export const DELIMITER_SIZE_DIAGNOSTIC_CODE = 'delimiter-manual-size' as const;

package/src/reference/diagrams-validate.ts

@@ -11,7 +11,8 @@ export type DiagramDiagnosticCode =
   | 'dia-invalid-key'
   | 'dia-duplicate-key'
   | 'dia-ref-resolves'
-  | 'dia-key-unused';
+  | 'dia-key-unused'
+  | 'dia-removed-prop';
 
 export interface DiagramDiagnostic {
   readonly code: DiagramDiagnosticCode;
@@ -29,6 +30,13 @@ export interface DiagramValidation extends KeyedFloatValidation {
   readonly diagnostics: readonly DiagramDiagnostic[];
 }
 
+/**
+ * The fix for a compaction prop: a diagram is always its graph and then its
+ * caption line (docs/plans/figures-and-short-captions.md, decision 7).
+ */
+export const DIAGRAM_NO_LONGER_FOLDS =
+  'a diagram no longer folds by itself — delete the prop. To let a reader fold it away, wrap it in a `<Fold>` or put it in a collapsible section.';
+
 export function validateDiagrams(
   lessons: readonly DiagramLessonInput[],
 ): DiagramValidation {
@@ -36,5 +44,13 @@ export function validateDiagrams(
     tagName: 'Diagram',
     prefix: 'dia',
     noun: 'diagram',
+    removedProps: {
+      label:
+        'rename it `caption` (shown below the diagram with its number), and add an optional `short` caption if the caption is long.',
+      title:
+        'a diagram is named by its `caption` (shown below it with its number) and an optional `short` caption.',
+      defaultOpen: DIAGRAM_NO_LONGER_FOLDS,
+      rememberState: DIAGRAM_NO_LONGER_FOLDS,
+    },
   }) as DiagramValidation;
 }

package/src/reference/equations-validate.ts

@@ -15,6 +15,8 @@ import { parseEquationRef, scanEquationLabels } from './equations.mjs';
 export interface EquationLabelRecord {
   readonly key: string;
   readonly number: string;
+  /** The equation's `\caption{…}` short caption, when it has one. */
+  readonly short?: string;
   readonly lessonId: string;
   readonly slug: string;
   readonly section: number;
@@ -54,12 +56,13 @@ export interface EquationLessonInput {
   readonly file: string;
   readonly body: string;
   /**
-   * `{ prefix, offset }` — the part's 1-based ordinal among the sidebar groups,
-   * and how many display equations earlier lessons of that part already used.
-   * When set, equations are numbered `‹part›.‹offset + n›`; when omitted, the
-   * legacy `##`-section scheme. See `docs/authoring/structure.md`.
+   * `{ prefix, offset }` — the lesson's float-number prefix (`‹part›.‹chapter›`,
+   * or `‹part›` under `numbering.floats: "part"`) and how many display
+   * equations precede the lesson in that scope. When set, equations are
+   * numbered `‹prefix›.‹offset + n›`; when omitted, the legacy `##`-section
+   * scheme. See `docs/authoring/structure.md`.
    */
-  readonly numbering?: { readonly prefix: number; readonly offset: number };
+  readonly numbering?: { readonly prefix: number | string; readonly offset: number };
 }
 
 const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
@@ -100,6 +103,7 @@ export function validateEquations(
     for (const raw of scanEquationLabels(lesson.body, lesson.numbering) as {
       key: string;
       number: string;
+      short: string | null;
       section: number;
       indexInSection: number;
     }[]) {
@@ -119,6 +123,7 @@ export function validateEquations(
       labels.push({
         key: raw.key,
         number: raw.number,
+        ...(raw.short ? { short: raw.short } : {}),
         lessonId: lesson.lessonId,
         slug: lesson.slug,
         section: raw.section,