explico 0.6.0 → 0.7.0

package/dist/compiler/logging.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Run logs for `pnpm validate:content`, in Python's `logging` format.
+ *
+ * The terminal keeps the compact `[code] message` lines it has always shown.
+ * This module is the second handler over the same records: it writes them to
+ * `build/logs/<timestamp>/` in the format Python's `logging` emits, so a run
+ * can be grepped by level and by subsystem long after the terminal scrolled
+ * away.
+ *
+ *     %(asctime)s %(levelname)s %(name)s: %(message)s
+ *
+ *     2026-09-18 03:22:47,482 WARNING explico.notation: [undefined-reference] …
+ *
+ * Three files per run, each a superset of the one above it, so you open the
+ * narrowest one that still answers the question:
+ *
+ *     build/logs/2026-09-18T03-22-47/
+ *       error.log     errors only
+ *       warning.log   errors + warnings
+ *       info.log      errors + warnings + info
+ *
+ * Nothing is pruned — `build/` is git-ignored, so old runs are yours to clean
+ * up — and `build/logs/latest` points at the newest run.
+ *
+ * Levels carry their Python meaning. `error` is a blocking diagnostic (the
+ * caller still throws; this module only records), `warning` is a non-blocking
+ * finding, and `info` is the run summary plus the severity-`info` diagnostics
+ * the engine has always produced but never printed.
+ *
+ * Each level method **returns its message**, so a call site can log and print
+ * in one expression without the two drifting apart:
+ *
+ *     console.warn(log.warning('notation', `[${d.code}] ${d.message}`));
+ */
+/** Sits beside `build/manifest.json` and `build/resolution/` (Phase F). */
+declare const LOGS_DIR: string;
+/** Python's levels, narrowed to the three the engine actually emits. */
+type LogLevel = 'ERROR' | 'WARNING' | 'INFO';
+/**
+ * Python's `%(asctime)s` — local time, with the comma before the milliseconds
+ * that `logging.Formatter` writes by default.
+ */
+declare function formatTimestamp(date: Date): string;
+/** A filesystem-safe local-time stamp for the run directory's name. */
+declare function formatRunStamp(date: Date): string;
+/**
+ * `explico.<source>` — the logger name is the diagnostic's subsystem, so
+ * filtering by name is filtering by subsystem. `rawFloats` becomes
+ * `explico.raw-floats`; anything already lowercase passes through.
+ */
+declare function loggerName(source: string): string;
+/** One formatted line, without its trailing newline. */
+declare function formatRecord(level: LogLevel, source: string, message: string, date: Date): string;
+interface RunLogSummary {
+    /** Absolute path of this run's directory. */
+    readonly directory: string;
+    /** Repo-relative form, for printing. */
+    readonly relativeDirectory: string;
+    readonly counts: Readonly<Record<LogLevel, number>>;
+}
+/** One diagnostic, across every category's slightly different shape. */
+interface AnyDiagnostic {
+    readonly severity?: string;
+    readonly message: string;
+    readonly code?: string;
+    readonly kind?: string;
+    readonly file?: string;
+    readonly line?: number;
+    readonly column?: number;
+}
+/** `manifest.diagnostics`, structurally — one array per subsystem. */
+type DiagnosticGroups = Readonly<Record<string, readonly AnyDiagnostic[]>>;
+interface RunLog {
+    /** Absolute path of this run's directory. */
+    readonly directory: string;
+    /** Records at `ERROR` and returns `message`. */
+    error(source: string, message: string): string;
+    /** Records at `WARNING` and returns `message`. */
+    warning(source: string, message: string): string;
+    /** Records at `INFO` and returns `message`. */
+    info(source: string, message: string): string;
+    /**
+     * Sweeps every severity-`info` diagnostic in a manifest's `diagnostics` into
+     * `info.log`. Errors and warnings are deliberately **not** taken from here:
+     * they are recorded at the call site that also prints the console line, so
+     * the two can never drift.
+     */
+    infoDiagnostics(diagnostics: DiagnosticGroups): number;
+    /** Refreshes `latest` and reports what the run recorded. */
+    close(): RunLogSummary;
+}
+/** `[code] message`, matching what the console has always printed. */
+declare function diagnosticLine(diagnostic: AnyDiagnostic): string;
+interface RunLogOptions {
+    /** Overridden in tests; defaults to `build/logs` under the repository root. */
+    readonly root?: string;
+    /** Overridden in tests so the directory name is deterministic. */
+    readonly now?: Date;
+    /** Set `false` to skip the `latest` symlink. */
+    readonly latest?: boolean;
+}
+/**
+ * Opens a run directory and returns its log. The directory and its three files
+ * are created up front, so a run that crashes before {@link RunLog.close} still
+ * leaves everything recorded up to that point on disk.
+ */
+declare function createRunLog(options?: RunLogOptions): RunLog;
+
+export { type AnyDiagnostic, type DiagnosticGroups, LOGS_DIR, type LogLevel, type RunLog, type RunLogOptions, type RunLogSummary, createRunLog, diagnosticLine, formatRecord, formatRunStamp, formatTimestamp, loggerName };

package/dist/compiler/logging.js

@@ -0,0 +1,107 @@
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync
+} from "node:fs";
+import { join, relative } from "node:path";
+const REPOSITORY_ROOT = process.cwd();
+const LOGS_DIR = join(REPOSITORY_ROOT, "build", "logs");
+const LEVELS = ["ERROR", "WARNING", "INFO"];
+const FILES = [
+  { name: "error.log", level: "ERROR" },
+  { name: "warning.log", level: "WARNING" },
+  { name: "info.log", level: "INFO" }
+];
+function includes(file, record) {
+  return LEVELS.indexOf(record) <= LEVELS.indexOf(file);
+}
+function pad(value, width = 2) {
+  return String(value).padStart(width, "0");
+}
+function formatTimestamp(date) {
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())},${pad(date.getMilliseconds(), 3)}`;
+}
+function formatRunStamp(date) {
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}-${pad(date.getMinutes())}-${pad(date.getSeconds())}`;
+}
+function loggerName(source) {
+  const normalized = source.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+  return normalized.startsWith("explico.") ? normalized : `explico.${normalized}`;
+}
+function formatRecord(level, source, message, date) {
+  return `${formatTimestamp(date)} ${level} ${loggerName(source)}: ${message}`;
+}
+function diagnosticLine(diagnostic) {
+  const code = diagnostic.code ?? diagnostic.kind;
+  const at = [diagnostic.file, diagnostic.line, diagnostic.column].filter((part) => part !== void 0).join(":");
+  const prefix = code === void 0 ? "" : `[${code}] `;
+  return at === "" ? `${prefix}${diagnostic.message}` : `${prefix}${at}: ${diagnostic.message}`;
+}
+function createRunLog(options = {}) {
+  const root = options.root ?? LOGS_DIR;
+  const started = options.now ?? /* @__PURE__ */ new Date();
+  const stamp = formatRunStamp(started);
+  let directory = join(root, stamp);
+  for (let suffix = 2; existsSync(directory); suffix += 1) {
+    directory = join(root, `${stamp}-${suffix}`);
+  }
+  mkdirSync(directory, { recursive: true });
+  for (const file of FILES) writeFileSync(join(directory, file.name), "");
+  const counts = { ERROR: 0, WARNING: 0, INFO: 0 };
+  const record = (level, source, message) => {
+    counts[level] += 1;
+    const line = `${formatRecord(level, source, message, /* @__PURE__ */ new Date())}
+`;
+    for (const file of FILES) {
+      if (includes(file.level, level)) {
+        appendFileSync(join(directory, file.name), line);
+      }
+    }
+    return message;
+  };
+  return {
+    directory,
+    error: (source, message) => record("ERROR", source, message),
+    warning: (source, message) => record("WARNING", source, message),
+    info: (source, message) => record("INFO", source, message),
+    infoDiagnostics(diagnostics) {
+      let written = 0;
+      for (const [source, group] of Object.entries(diagnostics)) {
+        if (!Array.isArray(group)) continue;
+        for (const diagnostic of group) {
+          if (diagnostic.severity !== "info") continue;
+          record("INFO", source, diagnosticLine(diagnostic));
+          written += 1;
+        }
+      }
+      return written;
+    },
+    close() {
+      if (options.latest !== false) {
+        const link = join(root, "latest");
+        try {
+          rmSync(link, { force: true });
+          symlinkSync(directory, link, "dir");
+        } catch {
+        }
+      }
+      return {
+        directory,
+        relativeDirectory: relative(REPOSITORY_ROOT, directory),
+        counts: { ...counts }
+      };
+    }
+  };
+}
+export {
+  LOGS_DIR,
+  createRunLog,
+  diagnosticLine,
+  formatRecord,
+  formatRunStamp,
+  formatTimestamp,
+  loggerName
+};

package/dist/compiler/manifest.d.ts

@@ -96,8 +96,12 @@ import '../reference/keyed-float-validate.js';
  * engine-authored sections, not written by a lesson, so they get their own
  * default independent of a course's `##` heading default; closed unless the
  * course sets one.
+ * v15 (diagnostic severity): public diagnostic severity unions add `info` for
+ * optional advice. Unused keys/definitions and restructuring candidates move
+ * from `warning` to `info`; their diagnostic codes and container fields stay
+ * unchanged.
  */
-declare const MANIFEST_SCHEMA_VERSION = 14;
+declare const MANIFEST_SCHEMA_VERSION = 15;
 declare const MANIFEST_PATH: string;
 interface ManifestCitation {
     readonly id: string;
@@ -324,11 +328,11 @@ interface Manifest {
         readonly notation: readonly NotationDiagnostic[];
         readonly alignment: readonly NotationDiagnostic[];
         readonly math: readonly MathGateDiagnostic[];
-        /** Tier-3 corpus consistency checks (D6). Warnings only. */
+        /** Tier-3 corpus consistency checks (D6). Warnings and optional info. */
         readonly consistency: readonly ConsistencyDiagnostic[];
         /** Knowledge-version checks (C3): `about.version` vs `content/CHANGELOG.md`. Warnings only. */
         readonly knowledge: readonly KnowledgeVersionDiagnostic[];
-        /** Equation-identity checks (D7): `eq-duplicate-key`, `eq-ref-resolves` (error); `eq-key-unused` (warning). */
+        /** Equation identity: broken identities are errors; unused keys are info. */
         readonly equations: readonly EquationDiagnostic[];
         /** `<Table>` identity checks (F-tables-figures) — same codes, `tab-` prefixed. */
         readonly tables: readonly TableDiagnostic[];

package/dist/compiler/manifest.js

@@ -75,7 +75,7 @@ import {
   isLessonSlug,
   lessonIdFromSlug
 } from "./lesson-derivation.js";
-const MANIFEST_SCHEMA_VERSION = 14;
+const MANIFEST_SCHEMA_VERSION = 15;
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const MANIFEST_PATH = join(REPOSITORY_ROOT, "build", "manifest.json");

package/dist/reference/base-abbreviations.mjs

@@ -20,12 +20,18 @@ export const BASE_ABBREVIATIONS = Object.freeze(
     'e.g.',
     'i.e.',
     'etc.',
+    'e.t.c.',
     'cf.',
     'vs.',
-    'a.m.',
-    'p.m.',
     'a.k.a.',
     'et al.',
+    // time of day, in each casing/punctuation style a lesson might use
+    'a.m.',
+    'p.m.',
+    'A.M.',
+    'P.M.',
+    'AM',
+    'PM',
     // generic acronyms with no domain-specific meaning in this engine
     'AI',
     'ID',

package/dist/reference/consistency.d.ts

@@ -8,11 +8,11 @@ import { NotationRegistry, NotationRegistryInput } from './types.js';
  * Corpus consistency checks (Step D6) — the Tier 1–2 checks from the cleanup
  * plan's "Enforced checks" section that no earlier step covers.
  *
- * Every check here enters as a **Tier-3 warning**: `pnpm validate:content`
- * surfaces the counts, `manifest.diagnostics.consistency` records the detail,
- * and `resolution/consistency-report.json` is the committed, diff-checkable
- * snapshot. Nothing here changes content — each finding is an open item for a
- * separate human-quantitative-reviewed pass. A finding is silenced only by a
+ * Every check here is non-blocking Tier 3: repairable violations are warnings
+ * and optional restructuring advice is info. `pnpm validate:content` surfaces
+ * warning counts, `manifest.diagnostics.consistency` records every detail, and
+ * `resolution/consistency-report.json` is the committed, diff-checkable
+ * snapshot. Nothing here changes content. A finding is silenced only by a
  * reviewed line in `lint-ignore.yml` (see `./lint-ignore`).
  *
  *   (a) glyph-unique-in-corpus       one rendered glyph → one meaning corpus-wide
@@ -20,8 +20,6 @@ import { NotationRegistry, NotationRegistryInput } from './types.js';
  *                                     unit strings drawn from a controlled vocab
  *   (c) convention-single-definition  a sign / cash-flow-perspective convention a
  *                                     lesson uses resolves to one declaration
- *   (e) numerals-tagged              numerals in `$…$` / result tables are tagged
- *                                     to a `src/domain/` call or a source locator
  *   (f) weak-local                   a `notation.local` symbol used only in its
  *                                     own defining equation and prose
  *   (g) notation-source-locator      every notation `sources` entry has a locator
@@ -37,11 +35,11 @@ import { NotationRegistry, NotationRegistryInput } from './types.js';
  * `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' | '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';
 interface ConsistencyDiagnostic {
     readonly code: ConsistencyCode;
-    /** Tier 3 — every finding here is a warning until content is brought clean. */
-    readonly severity: 'warning';
+    /** Tier 3 — repairable violations are warnings; optional advice is info. */
+    readonly severity: 'warning' | 'info';
     readonly message: string;
     readonly file?: string;
     readonly lessonId?: string;

package/dist/reference/consistency.js

@@ -17,23 +17,6 @@ function mathSpans(body) {
   }
   return spans;
 }
-function tableRows(body) {
-  const rows = [];
-  for (const line of stripCode(body).split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed.startsWith("|") || !trimmed.slice(1).includes("|")) continue;
-    if (/^\s*\|[\s:|-]+\|\s*$/.test(line)) continue;
-    rows.push(line);
-  }
-  return rows;
-}
-const NUMERAL_RE = /(?<![\w.])-?\d+(?:\.\d+)?/g;
-function numeralCount(text) {
-  return (text.replace(/\\[a-zA-Z]+/g, " ").match(NUMERAL_RE) ?? []).length;
-}
-function isTagged(text) {
-  return /\[@[a-z0-9]/i.test(text) || /<!--\s*domain:/i.test(text);
-}
 function glyphMatcher(latex) {
   const trimmed = latex.trim();
   if (trimmed === "") return void 0;
@@ -141,31 +124,6 @@ function checkConventionSingleDefinition(input, out) {
     });
   }
 }
-function checkNumeralsTagged(input, out) {
-  for (const lesson of input.notationInput.lessons) {
-    if (input.lintIgnore.matches("numerals-tagged", lesson.lessonId)) continue;
-    let math = 0;
-    for (const span of mathSpans(lesson.body)) {
-      if (isTagged(span.latex)) continue;
-      math += numeralCount(span.latex);
-    }
-    let table = 0;
-    for (const row of tableRows(lesson.body)) {
-      if (isTagged(row)) continue;
-      table += numeralCount(row.replace(/\$[^$\n]*\$/g, " "));
-    }
-    const count = math + table;
-    if (count === 0) continue;
-    out.push({
-      code: "numerals-tagged",
-      severity: "warning",
-      lessonId: lesson.lessonId,
-      file: lesson.source.file,
-      count,
-      message: `${lesson.lessonId}: ${count} numeral(s) in $\u2026$ / result tables (${math} in math, ${table} in tables) are not tagged to a src/domain/ call or a source locator`
-    });
-  }
-}
 function checkWeakLocal(input, out) {
   for (const lesson of input.notationInput.lessons) {
     const spans = mathSpans(lesson.body).map((span) => span.latex);
@@ -177,7 +135,7 @@ function checkWeakLocal(input, out) {
       if (uses > 1) continue;
       out.push({
         code: "weak-local",
-        severity: "warning",
+        severity: "info",
         lessonId: lesson.lessonId,
         file: lesson.source.file,
         key: definition.key,
@@ -228,7 +186,7 @@ function checkGlossWantsPromoting(input, out) {
     if (input.lintIgnore.matches("gloss-wants-promoting", glyph)) continue;
     out.push({
       code: "gloss-wants-promoting",
-      severity: "warning",
+      severity: "info",
       glyph,
       message: `gloss ${JSON.stringify(glyph)} (${label}) is declared on ${keys.size} entries (${[...keys].sort().join(", ")}); a meaning reused this widely wants promoting to a card`
     });
@@ -250,7 +208,7 @@ function checkCardWantsDemoting(input, out) {
     }
     out.push({
       code: "card-wants-demoting",
-      severity: "warning",
+      severity: "info",
       key: definition.key,
       file: definition.source.file,
       count: words,
@@ -381,7 +339,6 @@ const CHECKS = [
   checkGlyphUniqueness,
   checkNotationUnits,
   checkConventionSingleDefinition,
-  checkNumeralsTagged,
   checkWeakLocal,
   checkNotationSourceLocator,
   checkGlossWantsPromoting,
@@ -403,7 +360,6 @@ function consistencyCounts(diagnostics) {
     "notation-units": 0,
     "units-vocab": 0,
     "convention-single-definition": 0,
-    "numerals-tagged": 0,
     "weak-local": 0,
     "notation-source-locator": 0,
     "gloss-wants-promoting": 0,

package/dist/reference/delimiter-size.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Rule N17: nested scalable delimiters must make their hierarchy visible.
+ *
+ * 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.
+ */
+declare const DELIMITER_SIZE_DIAGNOSTIC_CODE: "delimiter-size-hierarchy";
+type DelimiterSizeName = 'automatic' | 'big' | 'Big' | 'bigg' | 'Bigg';
+interface DelimiterSizeSuggestion {
+    readonly size: Exclude<DelimiterSizeName, 'automatic' | 'big'>;
+    readonly open: string;
+    readonly close: string;
+    readonly latex: string;
+}
+interface DelimiterSizeDiagnostic {
+    readonly code: typeof DELIMITER_SIZE_DIAGNOSTIC_CODE;
+    readonly severity: 'warning';
+    readonly offset: number;
+    readonly line: number;
+    readonly column: number;
+    readonly outerSize: DelimiterSizeName;
+    readonly nestedSize: DelimiterSizeName;
+    readonly suggestion?: DelimiterSizeSuggestion;
+    readonly message: string;
+}
+/**
+ * Warn when a scalable outer pair is not at least one manual size level above
+ * everything nested inside it. `\left` and `\big` form the baseline level;
+ * progressively larger levels are `\Big`, `\bigg`, and `\Bigg`.
+ *
+ * Only `()`, `[]`, and `\{\}` are parsed. Bare delimiters are intentionally
+ * ignored: N15 owns that separate error, while ordinary semantic notation
+ * such as `f(x)` and `\mathbb{E}[X]` must not trigger this size-only linter.
+ */
+declare function lintDelimiterSizes(latex: string): DelimiterSizeDiagnostic[];
+
+export { DELIMITER_SIZE_DIAGNOSTIC_CODE, type DelimiterSizeDiagnostic, type DelimiterSizeName, type DelimiterSizeSuggestion, lintDelimiterSizes };

package/dist/reference/delimiter-size.js

@@ -0,0 +1,177 @@
+const DELIMITER_SIZE_DIAGNOSTIC_CODE = "delimiter-size-hierarchy";
+const SIZE_SPECS = [
+  {
+    name: "automatic",
+    rank: 1,
+    openCommand: "\\left",
+    closeCommand: "\\right",
+    kind: "automatic"
+  },
+  {
+    name: "big",
+    rank: 1,
+    openCommand: "\\bigl",
+    closeCommand: "\\bigr",
+    kind: "manual"
+  },
+  {
+    name: "Big",
+    rank: 2,
+    openCommand: "\\Bigl",
+    closeCommand: "\\Bigr",
+    kind: "manual"
+  },
+  {
+    name: "bigg",
+    rank: 3,
+    openCommand: "\\biggl",
+    closeCommand: "\\biggr",
+    kind: "manual"
+  },
+  {
+    name: "Bigg",
+    rank: 4,
+    openCommand: "\\Biggl",
+    closeCommand: "\\Biggr",
+    kind: "manual"
+  }
+];
+const COMMAND_SPECS = SIZE_SPECS.flatMap((spec) => [
+  { ...spec, command: spec.openCommand, tokenKind: "open" },
+  { ...spec, command: spec.closeCommand, tokenKind: "close" }
+]).sort((left, right) => right.command.length - left.command.length);
+const SUGGESTION_BY_RANK = new Map(
+  SIZE_SPECS.filter((spec) => spec.rank >= 2).map((spec) => [spec.rank, spec])
+);
+function delimiterAt(latex, offset, kind) {
+  const candidates = kind === "open" ? ["\\{", "(", "["] : ["\\}", ")", "]"];
+  for (const delimiter of candidates) {
+    if (latex.startsWith(delimiter, offset)) {
+      return { delimiter, end: offset + delimiter.length };
+    }
+  }
+  return void 0;
+}
+function tokenAt(latex, offset) {
+  if (latex[offset] !== "\\") return void 0;
+  for (const spec of COMMAND_SPECS) {
+    if (!latex.startsWith(spec.command, offset)) continue;
+    const afterCommand = offset + spec.command.length;
+    if (/[A-Za-z]/.test(latex[afterCommand] ?? "")) continue;
+    let delimiterOffset = afterCommand;
+    while (/\s/.test(latex[delimiterOffset] ?? "")) delimiterOffset += 1;
+    const delimiter = delimiterAt(latex, delimiterOffset, spec.tokenKind);
+    if (!delimiter) continue;
+    return {
+      kind: spec.tokenKind,
+      pairKind: spec.kind,
+      rank: spec.rank,
+      size: spec.name,
+      delimiter: delimiter.delimiter,
+      offset,
+      end: delimiter.end
+    };
+  }
+  return void 0;
+}
+function pairMatches(open, close) {
+  return open.kind === "open" && close.kind === "close" && open.pairKind === close.pairKind && open.rank === close.rank;
+}
+function isEscaped(latex, offset) {
+  let slashes = 0;
+  for (let index = offset - 1; index >= 0 && latex[index] === "\\"; index -= 1) {
+    slashes += 1;
+  }
+  return slashes % 2 === 1;
+}
+function parseDelimiterPairs(latex) {
+  const roots = [];
+  const stack = [];
+  for (let offset = 0; offset < latex.length; offset += 1) {
+    if (latex[offset] === "%" && !isEscaped(latex, offset)) {
+      const newline = latex.indexOf("\n", offset + 1);
+      if (newline === -1) break;
+      offset = newline;
+      continue;
+    }
+    const token = isEscaped(latex, offset) ? void 0 : tokenAt(latex, offset);
+    if (!token) continue;
+    offset = token.end - 1;
+    if (token.kind === "open") {
+      const pair2 = { open: token, children: [] };
+      const parent = stack[stack.length - 1];
+      if (parent) parent.children.push(pair2);
+      else roots.push(pair2);
+      stack.push(pair2);
+      continue;
+    }
+    const pair = stack[stack.length - 1];
+    if (!pair || !pairMatches(pair.open, token)) return void 0;
+    pair.close = token;
+    stack.pop();
+  }
+  return stack.length === 0 ? roots : void 0;
+}
+function lineAndColumn(source, offset) {
+  const before = source.slice(0, offset);
+  const lastNewline = before.lastIndexOf("\n");
+  return {
+    line: before.split("\n").length,
+    column: offset - lastNewline
+  };
+}
+function sizeName(rank) {
+  return SUGGESTION_BY_RANK.get(rank)?.name ?? "Bigg";
+}
+function suggestionFor(pair, requiredRank) {
+  const close = pair.close;
+  const spec = SUGGESTION_BY_RANK.get(requiredRank);
+  if (!close || !spec || spec.name === "automatic" || spec.name === "big") {
+    return void 0;
+  }
+  return {
+    size: spec.name,
+    open: `${spec.openCommand}${pair.open.delimiter}`,
+    close: `${spec.closeCommand}${close.delimiter}`,
+    latex: `${spec.openCommand}${pair.open.delimiter} ... ${spec.closeCommand}${close.delimiter}`
+  };
+}
+function lintDelimiterSizes(latex) {
+  const roots = parseDelimiterPairs(latex);
+  if (!roots) return [];
+  const diagnostics = [];
+  const assess = (pair) => {
+    let largestNestedRequirement = 0;
+    let representativeNestedSize = "automatic";
+    for (const child of pair.children) {
+      const childRequired = assess(child);
+      if (childRequired > largestNestedRequirement) {
+        largestNestedRequirement = childRequired;
+        representativeNestedSize = sizeName(childRequired);
+      }
+    }
+    const requiredRank = largestNestedRequirement === 0 ? pair.open.rank : largestNestedRequirement + 1;
+    pair.requiredRank = Math.max(pair.open.rank, requiredRank);
+    if (largestNestedRequirement > 0 && pair.open.rank < requiredRank) {
+      const location = lineAndColumn(latex, pair.open.offset);
+      const suggestion = suggestionFor(pair, requiredRank);
+      diagnostics.push({
+        code: DELIMITER_SIZE_DIAGNOSTIC_CODE,
+        severity: "warning",
+        offset: pair.open.offset,
+        ...location,
+        outerSize: pair.open.size,
+        nestedSize: representativeNestedSize,
+        ...suggestion ? { suggestion } : {},
+        message: suggestion ? `Outer delimiters are not larger than their nested pair. Use ${suggestion.latex}; preserve the original opening and closing delimiter shapes (rule N17).` : `Outer delimiters are not larger than their nested pair, and no larger standard manual delimiter size remains. Preserve the original opening and closing shapes and restructure the expression if necessary (rule N17).`
+      });
+    }
+    return pair.requiredRank;
+  };
+  for (const root of roots) assess(root);
+  return diagnostics.sort((left, right) => left.offset - right.offset);
+}
+export {
+  DELIMITER_SIZE_DIAGNOSTIC_CODE,
+  lintDelimiterSizes
+};

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

@@ -5,7 +5,7 @@ import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } fr
 type DiagramDiagnosticCode = 'dia-invalid-key' | 'dia-duplicate-key' | 'dia-ref-resolves' | 'dia-key-unused';
 interface DiagramDiagnostic {
     readonly code: DiagramDiagnosticCode;
-    readonly severity: 'error' | 'warning';
+    readonly severity: 'error' | 'warning' | 'info';
     readonly message: string;
     readonly file?: string;
     readonly lessonId?: string;

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

@@ -4,7 +4,7 @@
  * - `eq-duplicate-key` (Tier 1, error): an `eq:` key is unique per lesson.
  * - `eq-ref-resolves` (Tier 1, error): every `[[eq-key]]` / `[[slug#eq-key]]`
  *   points at a display equation that carries `\label{eq:key}`.
- * - `eq-key-unused` (Tier 3, warning): a labelled equation never referenced.
+ * - `eq-key-unused` (info): a labelled equation is never referenced.
  *
  * The remark pass enforces the same rules on the render path; this gives the
  * fast `pnpm validate:content` the same coverage and feeds the manifest.
@@ -26,7 +26,7 @@ interface EquationRefRecord {
 type EquationDiagnosticCode = 'eq-duplicate-key' | 'eq-ref-resolves' | 'eq-key-unused';
 interface EquationDiagnostic {
     readonly code: EquationDiagnosticCode;
-    readonly severity: 'error' | 'warning';
+    readonly severity: 'error' | 'warning' | 'info';
     readonly message: string;
     readonly file?: string;
     readonly lessonId?: string;

package/dist/reference/equations-validate.js

@@ -73,7 +73,7 @@ function validateEquations(lessons) {
     if (referenced.has(`${label.slug}#${label.key}`)) continue;
     diagnostics.push({
       code: "eq-key-unused",
-      severity: "warning",
+      severity: "info",
       message: `${label.lessonId} labels eq:${label.key} (${label.number}) but nothing references it with [[eq-${label.key}]]`,
       file: label.slug,
       lessonId: label.lessonId,