explico 0.7.0 → 0.11.0

package/dist/course-config-Dsnri9Tk.d.ts

@@ -0,0 +1,464 @@
+import { RuleId } from './rules/catalog.js';
+import { CourseRule, CourseRuleDefinitions } from './rules/course-rules.js';
+
+/**
+ * A course's per-rule settings — `rules` in `CourseConfig` — resolved against
+ * the catalog.
+ *
+ * The block is flat by rule ID and holds only deviations from the defaults:
+ *
+ * ```json
+ * "rules": {
+ *   "P5": { "enabled": false },
+ *   "S1": { "maxLength": 72 },
+ *   "N14": { "allow": ["GDP"] }
+ * }
+ * ```
+ *
+ * It also resolves the course's *own* rules — `courseRules`, a separate block
+ * with a separate module (`src/rules/course-rules.ts`) — so that one call hands
+ * the compiler every rule decision the course made, engine or not.
+ *
+ * `resolveRules` validates it (an unknown ID, an unknown key, a value outside
+ * its spec, or `enabled: false` on a locked rule is an error — the settings
+ * file is wrong, and a wrong bump would ship), applies every default from the
+ * catalog, folds in the deprecated top-level `operators` / `romanLabels` /
+ * `abbreviations` blocks, and hands the gates one object to ask. It never
+ * decides *what* a rule means — that is the catalog's job.
+ *
+ * `rulesJsonSchema` renders the same catalog as the JSON Schema fragment the
+ * course's settings form uses (`dist/rules/rules.schema.json`, built by
+ * `scripts/gen-rules-schema.mjs`), with properties ordered by element and an
+ * `x-element` hint per rule so the form can group them.
+ */
+
+/** One rule's block in the settings file. Every key is optional. */
+interface RuleSettingsInput {
+    readonly enabled?: boolean;
+    readonly [key: string]: unknown;
+}
+/** `CourseConfig.rules` — flat by rule ID. */
+type CourseRulesConfig = Readonly<Record<string, RuleSettingsInput>>;
+/** A non-fatal finding about the settings file itself. */
+interface ConfigDiagnostic {
+    readonly code: 'config-deprecated-key' | 'config-retired-rule';
+    readonly severity: 'warning';
+    readonly message: string;
+}
+interface ResolvedRules {
+    /** False only for a rule the course turned off. An invariant is always on. */
+    isEnabled(id: string): boolean;
+    /** The course's own rules (`courseRules`), validated, in file order. */
+    readonly course: readonly CourseRule[];
+    /** The rule's settings with every default applied. `{}` for a rule without any. */
+    settings(id: string): Readonly<Record<string, unknown>>;
+    number(id: string, key: string): number;
+    strings(id: string, key: string): readonly string[];
+    /** Rules the course turned off — catalog order, then its own `X` rules. */
+    readonly disabled: readonly RuleId[];
+    readonly diagnostics: readonly ConfigDiagnostic[];
+}
+/**
+ * Validate `config.rules` (plus the deprecated top-level blocks) against the
+ * catalog and apply defaults. Throws on anything that would make a gate run
+ * with a value the author did not mean.
+ */
+declare function resolveRules(config: CourseConfig): ResolvedRules;
+/** Rule S2's word ranges in the shape `gatePartPages` takes. */
+declare function partPageLimits(rules: ResolvedRules): NormalizedPartPages;
+type JsonSchema = Record<string, unknown>;
+/**
+ * The `rules` property for a course's `course.settings.schema.json`:
+ * self-contained (no `$ref`), properties ordered by primary element, then
+ * catalog order. A retired rule is not in the catalog at all, so it cannot be a
+ * form field; a block for one is a warning at resolve time.
+ */
+declare function rulesJsonSchema(): JsonSchema;
+/** Every rule and invariant ID, for tooling that wants the closed list. */
+declare function catalogIds(): readonly string[];
+/** What the manifest publishes about the course's rule settings. */
+interface ManifestRules {
+    /** Rules the course turned off — catalog order, then its own `X` rules. */
+    readonly disabled: readonly RuleId[];
+    /** Every rule's settings with defaults applied, by ID. `{}` for a rule without any. */
+    readonly settings: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    /**
+     * The course's own rules, as written in `courseRules` and validated. Carried
+     * in the manifest so the rules-in-effect page and `content rules` list them
+     * beside the engine's without re-reading the settings file.
+     */
+    readonly course: readonly CourseRule[];
+}
+declare function rulesSnapshot(rules: ResolvedRules): ManifestRules;
+/** The diagnostic codes owned by every rule the course turned off. */
+declare function disabledCodes(rules: ResolvedRules): ReadonlySet<string>;
+/**
+ * Drop every diagnostic a disabled rule owns. This is how a switch takes
+ * effect for a validator that hosts several owners (`consistency.ts`,
+ * `raw-floats-validate.ts`, the resolver behind `gate-math.ts`): the
+ * validator stays ignorant of the catalog and the manifest filters by code.
+ * A whole-rule gate (N9, N14, S1, S2) is additionally skipped at its call
+ * site so its work is not done at all. Curriculum issues carry `kind`, not
+ * `code`.
+ */
+declare function dropDisabled<T extends {
+    readonly code?: string;
+    readonly kind?: string;
+}>(diagnostics: readonly T[], disabled: ReadonlySet<string>): T[];
+
+/**
+ * The shape `content/course.config.ts` must satisfy (Phase F).
+ *
+ * The engine never imports the course's config file; the wiring layer
+ * (`astro.config.mjs`, `scripts/*`, `src/content.config.ts`) imports the plain
+ * data value and passes it here, typed against `CourseConfig`. A second course
+ * supplies its own value of this shape.
+ */
+/**
+ * One **part** — a sidebar group, holding the chapters (lessons) whose slugs
+ * start with `dir`. A part's 1-based position in `CourseConfig.parts` is the
+ * first number in every section, equation, table, and figure number inside
+ * it. See `docs/authoring/structure.md` for the full level taxonomy.
+ */
+interface CoursePart {
+    /** Lesson-slug prefix, e.g. `bonds` for `bonds/yield-to-maturity`. */
+    readonly dir: string;
+    /** Sidebar group heading. */
+    readonly label: string;
+    /**
+     * The sidebar row that opens this part's **overview page**, when
+     * `content/docs/<dir>/index.mdx` exists. Defaults to `Overview`; the page's
+     * own title stays the part's name, which would only repeat the group
+     * heading one row below it.
+     */
+    readonly overviewLabel?: string;
+}
+/**
+ * @deprecated Renamed to {@link CoursePart}. "Section" now only ever means an
+ * `##` heading inside a lesson. Removed in the next MINOR release.
+ */
+type CourseSection = CoursePart;
+interface CourseConventions {
+    /** Notation key a lesson's stated sign convention must resolve to. */
+    readonly signConventionKey: string;
+    /** Competency id that also counts as declaring the cash-flow perspective. */
+    readonly cashFlowPerspectiveCompetency: string;
+}
+/**
+ * A course's edits to the shipped named-operator baseline (`BASE_OPERATORS`),
+ * consumed by the `operator-explained` consistency check (rule N8). An operator
+ * a lesson uses is fine when it is on the baseline plus `allow` minus `deny`;
+ * otherwise it needs a notation entry the reader can hover.
+ *
+ * Names are the KaTeX command without its backslash (`erf`, not `\erf`) for a
+ * built-in, and the verbatim body for an `\operatorname{…}` operator (`Var`).
+ */
+interface CourseOperators {
+    /** Operators this course also treats as universal (`Var`, `Cov`, `sgn`, …). */
+    readonly allow?: readonly string[];
+    /** Baseline operators this course wants explained anyway. */
+    readonly deny?: readonly string[];
+}
+/**
+ * A course's edits to the shipped roman-label baseline (`BASE_ROMAN_LABELS`),
+ * consumed by the `roman-label-explained` consistency check (rule N10). A
+ * `\mathrm{…}` multi-letter label a lesson uses is fine when it is on the
+ * baseline plus `allow` minus `deny`; otherwise it needs a notation entry the
+ * reader can hover. Same shape as {@link CourseOperators}, one level down:
+ * this governs `\mathrm{KE}`-style labels, not `\operatorname{Var}`-style
+ * operators.
+ */
+interface CourseRomanLabels {
+    /** Labels this course also treats as universal qualifiers (`eff`, `net`, …). */
+    readonly allow?: readonly string[];
+    /** Baseline labels this course wants explained anyway. */
+    readonly deny?: readonly string[];
+}
+/**
+ * A course's edits to the shipped accent baseline (`BASE_ACCENTS`, empty),
+ * consumed by the `accent-explained` consistency check (rule N22). A
+ * decoration a lesson uses (`\hat`, `\bar`, `'`, `*`, …) is fine when it is on
+ * the baseline plus `allow` minus `deny`, explained by an operator entry
+ * (`latex: \hat{}`), or part of a whole-form entry (`latex: \hat{\beta}`).
+ * Same shape as {@link CourseOperators}; set under `rules.N22` only.
+ */
+interface CourseAccents {
+    /** Decorations this course treats as universal (`\dot`, `\vec`, …). */
+    readonly allow?: readonly string[];
+    /** Baseline decorations this course wants explained anyway. */
+    readonly deny?: readonly string[];
+}
+/**
+ * A course's edits to the shipped abbreviation baseline (`BASE_ABBREVIATIONS`),
+ * consumed by the `abbreviation-explained` gate (rule N14). An abbreviation-
+ * shaped token — an all-caps acronym or a dotted form like `w.r.t.` — a
+ * lesson uses in prose is fine when it is on the baseline plus `allow` minus
+ * `deny`; otherwise it needs an entry in the `abbreviations` content
+ * collection, or — if it also names a math quantity — a notation entry the
+ * reader can hover. Same shape as {@link CourseOperators} / {@link
+ * CourseRomanLabels}.
+ */
+interface CourseAbbreviations {
+    /** Abbreviations this course also treats as universal (`GDP`, `CPU`, …). */
+    readonly allow?: readonly string[];
+    /** Baseline abbreviations this course wants explained anyway. */
+    readonly deny?: readonly string[];
+}
+/** One person or team credited for the study material. */
+interface CourseAuthor {
+    readonly name: string;
+    /**
+     * Email, URL, or handle. Rendered in the About panel as a link when it looks
+     * like a `mailto:` or `https:` target, plain text otherwise.
+     */
+    readonly contact?: string;
+}
+/**
+ * The reader-facing "about this material" block, surfaced by the `[?]` panel in
+ * the header (`components/starlight/AboutPanel.astro`) on every page.
+ *
+ * `version` is the course's **knowledge version** — semver over the
+ * learning-facing content, independent of the `explico` engine's own version.
+ * It must equal the newest entry in `content/CHANGELOG.md`; a mismatch is a
+ * Tier-3 `knowledge-version-mismatch` warning (rule C3, `docs/authoring/versioning.md`).
+ */
+interface CourseAbout {
+    /** Display name of the material. Defaults to {@link CourseConfig.title}. */
+    readonly materialName?: string;
+    /** One or two sentences on what the material covers. Defaults to {@link CourseConfig.description}. */
+    readonly summary?: string;
+    /** Knowledge version — semver; equals the latest `content/CHANGELOG.md` heading. */
+    readonly version: string;
+    /** Who authored / maintains the material. At least one entry. */
+    readonly authors: readonly CourseAuthor[];
+    /** Shown verbatim in the About panel — scope, warranty, AI-assistance note. */
+    readonly disclaimer: string;
+    /** Link to the published content changelog (repo blob, docs page, …). */
+    readonly changelogHref?: string;
+}
+/** A heading-like block's collapse default: may it fold, and does it start open? */
+interface CourseHeadingDisclosure {
+    /** Wrap it in a collapsible section. */
+    readonly collapsible?: boolean;
+    /** Its state for a reader with nothing saved yet; ignored when not collapsible. */
+    readonly defaultOpen?: boolean;
+}
+/** A block that always folds; only its first-visit state is a course choice. */
+interface CourseOpenDefault {
+    readonly defaultOpen?: boolean;
+}
+/**
+ * Every collapse default a course sets — the `disclosure` block of the course
+ * settings, in its own shape (docs/plans/titles-and-containers.md Part 4).
+ * Each kind names its default here:
+ *
+ * - **Full collapse**, the section wrapper (`CollapsibleSections.astro`):
+ *   `sections` (`##`), `subsections` (`###`–`######`), `knowledgeChecks`, the
+ *   generated `references` section, `memos` (a memo is a `######`-rank
+ *   section of its own), `folds` (a `<Fold>`, the same without a memo's
+ *   marker, letter or frame) and `workedExamples` (a set is a `##`-rank
+ *   section of its own, Part 6). The notation panel (`notation`) folds the
+ *   same way.
+ * - **A float's own fold**, which keeps its picture and caption line:
+ *   `figures` sets whether a lab's tools start open
+ *   (docs/plans/figures-and-short-captions.md, decision 5); a table is
+ *   minimized by hand, and starts truncated when it has more than
+ *   `tables.truncateAfter` rows. A figure or a diagram never folds by
+ *   itself (decision 7).
+ *
+ * A heading's own marker (`[collapsible]`, `[collapsed]`, `[no-collapsible]`)
+ * and a component's `defaultOpen` prop override the kind's default at one
+ * place. Every collapsible remembers the reader's choice per page.
+ * {@link normalizeDisclosure} fills in the engine defaults — the values each
+ * kind had before they became settings.
+ */
+interface CourseDisclosure {
+    readonly sections?: CourseHeadingDisclosure;
+    readonly subsections?: CourseHeadingDisclosure;
+    readonly knowledgeChecks?: CourseHeadingDisclosure;
+    readonly notation?: CourseOpenDefault;
+    readonly references?: CourseOpenDefault;
+    readonly memos?: CourseOpenDefault;
+    /** Whether a `<Fold>` starts open. */
+    readonly folds?: CourseOpenDefault;
+    /** Whether a lab's tools start open. */
+    readonly figures?: CourseOpenDefault;
+    readonly workedExamples?: CourseOpenDefault;
+    readonly tables?: {
+        /** A table with more rows than this starts truncated. Default `6`. */
+        readonly truncateAfter?: number;
+    };
+}
+/** {@link CourseDisclosure} with every default applied. */
+interface NormalizedDisclosure {
+    readonly sections: Required<CourseHeadingDisclosure>;
+    readonly subsections: Required<CourseHeadingDisclosure>;
+    readonly knowledgeChecks: Required<CourseHeadingDisclosure>;
+    readonly notation: Required<CourseOpenDefault>;
+    readonly references: Required<CourseOpenDefault>;
+    readonly memos: Required<CourseOpenDefault>;
+    readonly folds: Required<CourseOpenDefault>;
+    readonly figures: Required<CourseOpenDefault>;
+    readonly workedExamples: Required<CourseOpenDefault>;
+    readonly tables: {
+        readonly truncateAfter: number;
+    };
+}
+/**
+ * The engine's defaults. Headings do not fold unless the course says so;
+ * the notation panel, References, memos, folds and worked examples start
+ * closed; a knowledge check folds and starts open; a lab's tools start open;
+ * a table over 6 rows starts truncated.
+ */
+declare const DISCLOSURE_DEFAULTS: NormalizedDisclosure;
+/** Validate `CourseConfig.disclosure` and apply its defaults. Throws on a bad value. */
+declare function normalizeDisclosure(config: CourseConfig): NormalizedDisclosure;
+/**
+ * How the course numbers its outline and its floats (`numbering` in the
+ * course settings; docs/authoring/structure.md § Numbering). Every field is
+ * optional; {@link normalizeNumbering} fills in the defaults.
+ */
+interface CourseNumbering {
+    readonly sections?: {
+        /**
+         * Show section numbers: on wide screens, in print, and on a collapsed
+         * section's bar. Default `true`. Off, `[[sec-…]]` prints the title.
+         */
+        readonly show?: boolean;
+        /** The deepest heading level numbered, `2` (`##`) to `6`. Default `4`. */
+        readonly depth?: number;
+    };
+    /**
+     * The scope a float's counter runs over. `chapter` (default) restarts every
+     * kind in each chapter and prints `‹part›.‹chapter›.‹n›`; `part` runs on
+     * across the part's chapters and prints `‹part›.‹n›`. A plain `string`
+     * because the settings arrive as JSON; {@link normalizeNumbering} rejects
+     * any other value.
+     */
+    readonly floats?: string;
+    /**
+     * Resolve a number-form fragment a reader types (`#sec-1.1.2`,
+     * `#fig-2.2.1`) to the named anchor. Default `true`. The site itself only
+     * ever links and copies the named anchor.
+     */
+    readonly aliases?: boolean;
+}
+/** {@link CourseNumbering} with every default applied. */
+interface NormalizedNumbering {
+    readonly sections: {
+        readonly show: boolean;
+        readonly depth: number;
+    };
+    readonly floats: 'chapter' | 'part';
+    readonly aliases: boolean;
+}
+/** Validate `CourseConfig.numbering` and apply its defaults. Throws on a bad value. */
+declare function normalizeNumbering(config: CourseConfig): NormalizedNumbering;
+/**
+ * How a knowledge check's and a worked-example set's heading names its kind
+ * (`blockLabels` in the course settings; docs/plans/titles-and-containers.md
+ * Q11). The engine draws the kind before the author's title: `icon-word`
+ * (the default) shows the kind's icon and its word, "Knowledge check" or
+ * "Example"; `icon` shows the icon alone and keeps the word for a screen
+ * reader.
+ */
+type BlockLabels = 'icon' | 'icon-word';
+/** The engine default for {@link CourseConfig.blockLabels}. */
+declare const BLOCK_LABELS_DEFAULT: BlockLabels;
+/** Validate `CourseConfig.blockLabels` and apply its default. Throws on a bad value. */
+declare function normalizeBlockLabels(config: CourseConfig): BlockLabels;
+/**
+ * Rule S2's word ranges (`rules.S2.bridgeMinWords` … in the course settings),
+ * in the shape `gate-part-pages.ts` takes. Built by `partPageLimits` in
+ * `src/rules/settings.ts`.
+ */
+interface NormalizedPartPages {
+    readonly bridge: {
+        readonly minWords: number;
+        readonly maxWords: number;
+    };
+    readonly scope: {
+        readonly minWords: number;
+        readonly maxWords: number;
+    };
+}
+/** Optional, build-time lesson artifacts exposed to readers. */
+interface LessonExportsConfig {
+    /** Emit one self-contained, offline-capable HTML file per lesson. */
+    readonly standaloneHtml?: boolean;
+    /** Offer the browser's native print dialog with explico's lesson print layout. */
+    readonly print?: boolean;
+    /**
+     * Published course root used for links that intentionally leave the exported
+     * lesson. Required at export time when such a link is present.
+     */
+    readonly canonicalBaseUrl?: string;
+}
+/** The stable, non-optional export settings carried by the manifest. */
+interface NormalizedLessonExports {
+    readonly standaloneHtml: boolean;
+    readonly print: boolean;
+    readonly canonicalBaseUrl?: string;
+}
+interface CourseConfig {
+    readonly title: string;
+    readonly description: string;
+    /**
+     * The course's parts (sidebar groups), in order. Exactly one of `parts` or
+     * the deprecated `sections` must be given.
+     */
+    readonly parts?: readonly CoursePart[];
+    /**
+     * @deprecated Renamed to {@link CourseConfig.parts}. Still honoured, so a
+     * course on the old name keeps building; removed in the next MINOR release.
+     */
+    readonly sections?: readonly CoursePart[];
+    /** Namespaces used by competency / notation `domain` fields. */
+    readonly domains: readonly string[];
+    readonly conventions: CourseConventions;
+    /** Reader-facing identity + knowledge version (the `[?]` About panel). */
+    readonly about: CourseAbout;
+    /**
+     * Per-rule switches and settings, flat by rule ID — only what differs from
+     * the defaults (`{ "P5": { "enabled": false }, "S1": { "maxLength": 72 } }`).
+     * Resolved and validated by `resolveRules` (`src/rules/settings.ts`); the
+     * closed list of IDs and settings is `src/rules/catalog.ts`.
+     */
+    readonly rules?: CourseRulesConfig;
+    /**
+     * The course's *own* rules, on top of the engine's — `X1`…`X99`, each with
+     * its own text, elements, severity and optional `forbid` patterns. A list,
+     * not a map, so the settings form can add and remove one. Resolved and
+     * validated by `resolveCourseRules` (`src/rules/course-rules.ts`).
+     */
+    readonly courseRules?: CourseRuleDefinitions;
+    /** @deprecated Moved to `rules.N8` (same shape). Honoured for now; removed in a later MINOR. */
+    readonly operators?: CourseOperators;
+    /** @deprecated Moved to `rules.N10` (same shape). Honoured for now; removed in a later MINOR. */
+    readonly romanLabels?: CourseRomanLabels;
+    /** @deprecated Moved to `rules.N14` (same shape). Honoured for now; removed in a later MINOR. */
+    readonly abbreviations?: CourseAbbreviations;
+    /** Per-lesson export actions and downloadable artifacts. Disabled when omitted. */
+    readonly lessonExports?: LessonExportsConfig;
+    /** Every collapse default: headings, checks, memos, floats, tables. */
+    readonly disclosure?: CourseDisclosure;
+    /** Outline and float numbering. The defaults apply when omitted. */
+    readonly numbering?: CourseNumbering;
+    /**
+     * How a check's and an example set's heading names its kind: `icon-word`
+     * (default) or `icon` ({@link BlockLabels}). A plain `string` because the
+     * settings arrive as JSON; {@link normalizeBlockLabels} rejects any other
+     * value.
+     */
+    readonly blockLabels?: string;
+}
+/** Validate and canonicalize the build-facing lesson-export configuration. */
+declare function normalizeLessonExports(config: CourseConfig): NormalizedLessonExports;
+/**
+ * The course's parts, from whichever field the config uses. Throws rather than
+ * silently producing a course with no sidebar groups — a config with neither
+ * field would otherwise number every float by the `##`-section fallback.
+ */
+declare function coursePartsOf(config: CourseConfig): readonly CoursePart[];
+
+export { type CourseSection as A, type BlockLabels as B, type CourseConfig as C, DISCLOSURE_DEFAULTS as D, coursePartsOf as E, normalizeBlockLabels as F, normalizeDisclosure as G, normalizeLessonExports as H, normalizeNumbering as I, type LessonExportsConfig as L, type ManifestRules as M, type NormalizedPartPages as N, type ResolvedRules as R, type CourseAbbreviations as a, type NormalizedLessonExports as b, type NormalizedDisclosure as c, type NormalizedNumbering as d, type ConfigDiagnostic as e, type CourseConventions as f, type CourseOperators as g, type CourseRomanLabels as h, type CourseAccents as i, type CourseRulesConfig as j, type RuleSettingsInput as k, catalogIds as l, disabledCodes as m, dropDisabled as n, rulesJsonSchema as o, partPageLimits as p, rulesSnapshot as q, resolveRules as r, BLOCK_LABELS_DEFAULT as s, type CourseAbout as t, type CourseAuthor as u, type CourseDisclosure as v, type CourseHeadingDisclosure as w, type CourseNumbering as x, type CourseOpenDefault as y, type CoursePart as z };

package/dist/reference/base-accents.d.mts

@@ -0,0 +1,26 @@
+/**
+ * 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: {
+    allow?: readonly string[];
+    deny?: readonly string[];
+} | undefined): Set<string>;
+/**
+ * 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: Readonly<Set<any>>;

package/dist/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/dist/reference/base-roman-labels.d.mts

@@ -18,8 +18,8 @@ export function isBaseRomanLabel(name: any, romanLabels: any): boolean;
  * (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/dist/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/dist/reference/consistency.d.ts

@@ -1,8 +1,10 @@
-import { CourseConventions, CourseOperators, CourseRomanLabels } from '../compiler/course-config.js';
+import { f as CourseConventions, g as CourseOperators, h as CourseRomanLabels, i as CourseAccents } from '../course-config-Dsnri9Tk.js';
 import { CurriculumCatalog } from '../curriculum/validation.js';
 import { NotationSpec } from '../compiler/collections.js';
 import { LintIgnore } from './lint-ignore.js';
 import { NotationRegistry, NotationRegistryInput } from './types.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.js';
 
 /**
  * Corpus consistency checks (Step D6) — the Tier 1–2 checks from the cleanup
@@ -30,12 +32,20 @@ import { NotationRegistry, NotationRegistryInput } from './types.js';
  *                                     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`.
  */
 
-type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'weak-local' | 'notation-source-locator' | 'gloss-wants-promoting' | 'card-wants-demoting' | 'gloss-name-shape' | 'operator-explained' | 'roman-label-explained';
+type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'weak-local' | 'notation-source-locator' | 'gloss-wants-promoting' | 'card-wants-demoting' | 'gloss-name-shape' | 'operator-explained' | 'roman-label-explained' | 'accent-explained' | 'operator-suspended' | 'operator-suspension-reason' | 'operator-shadowed';
 interface ConsistencyDiagnostic {
     readonly code: ConsistencyCode;
     /** Tier 3 — repairable violations are warnings; optional advice is info. */
@@ -60,6 +70,8 @@ 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;
 }
 /**
  * Run every consistency check. The result is sorted deterministically (code,