explico 0.8.0 → 0.11.0

package/dist/reference/gate-math-punctuation.js

@@ -0,0 +1,251 @@
+import { equationLinkFor, mathSpans } from "./gate-math.js";
+import { lessonLine } from "./gate-prose-notation.js";
+const MATH_END_ABBREVIATIONS = [
+  "a.e.",
+  "a.s.",
+  "c.c.",
+  "const.",
+  "h.c.",
+  "i.i.d."
+];
+const LETTERS = /[A-Za-z]+/y;
+function tokenize(latex) {
+  const tokens = [];
+  const stack = [];
+  let i = 0;
+  while (i < latex.length) {
+    const ch = latex[i];
+    const parent = stack.length === 0 ? -1 : stack[stack.length - 1];
+    if (ch === "%") {
+      const newline = latex.indexOf("\n", i);
+      i = newline === -1 ? latex.length : newline;
+      continue;
+    }
+    if (ch === "\\") {
+      LETTERS.lastIndex = i + 1;
+      const letters = LETTERS.exec(latex);
+      const name = letters ? letters[0] : latex.charAt(i + 1);
+      tokens.push({ kind: "command", text: name, start: i, match: -1, parent });
+      i += 1 + Math.max(name.length, 1);
+      continue;
+    }
+    if (ch === "{") {
+      tokens.push({ kind: "open", text: ch, start: i, match: -1, parent });
+      stack.push(tokens.length - 1);
+    } else if (ch === "}") {
+      const open = stack.pop();
+      const index = tokens.length;
+      tokens.push({
+        kind: "close",
+        text: ch,
+        start: i,
+        match: open ?? -1,
+        parent: open === void 0 ? -1 : tokens[open].parent
+      });
+      if (open !== void 0) tokens[open].match = index;
+    } else {
+      tokens.push({ kind: /\s/.test(ch) ? "space" : "char", text: ch, start: i, match: -1, parent });
+    }
+    i += 1;
+  }
+  return tokens;
+}
+const MARKS = /* @__PURE__ */ new Set([".", ",", ";", ":"]);
+const INVISIBLE = /* @__PURE__ */ new Set([
+  ",",
+  ";",
+  ":",
+  "!",
+  " ",
+  "\\",
+  "quad",
+  "qquad",
+  "enspace",
+  "thinspace",
+  "medspace",
+  "thickspace",
+  "negthinspace",
+  "negmedspace",
+  "negthickspace",
+  "nonumber",
+  "notag",
+  "displaystyle",
+  "textstyle"
+]);
+const SKIPPED_GROUP = /* @__PURE__ */ new Set(["label", "caption", "tag", "begin", "end", "hspace", "vspace", "color"]);
+const UPRIGHT = /* @__PURE__ */ new Set(["text", "textrm", "textup", "textnormal", "mathrm", "mbox", "operatorname"]);
+const SIZER = /^(?:left|right|middle|[bB]igg?[lrm]?)$/;
+function groupOwner(tokens, open, from) {
+  let k = open - 1;
+  while (k >= from && tokens[k].kind === "space") k -= 1;
+  if (k >= from && tokens[k].kind === "char" && tokens[k].text === "*") k -= 1;
+  return k >= from && tokens[k].kind === "command" ? k : void 0;
+}
+function tail(tokens, from, to) {
+  let j = to - 1;
+  while (j >= from) {
+    const token = tokens[j];
+    if (token.kind === "space") {
+      j -= 1;
+      continue;
+    }
+    if (token.kind === "command" && INVISIBLE.has(token.text)) {
+      j -= 1;
+      continue;
+    }
+    if (token.kind === "char" && token.text === ".") {
+      const before = tokens[j - 1];
+      if (j - 1 >= from && before?.kind === "command" && SIZER.test(before.text)) {
+        j -= 2;
+        continue;
+      }
+    }
+    if (token.kind === "char" && token.text === "]") {
+      let open = j - 1;
+      while (open >= from && !(tokens[open].kind === "char" && tokens[open].text === "[")) open -= 1;
+      const breakToken = tokens[open - 1];
+      if (open - 1 >= from && breakToken?.kind === "command" && breakToken.text === "\\") {
+        j = open - 2;
+        continue;
+      }
+      return "clean";
+    }
+    if (token.kind === "close") {
+      if (token.match < from) return "clean";
+      const owner = groupOwner(tokens, token.match, from);
+      if (owner !== void 0 && SKIPPED_GROUP.has(tokens[owner].text)) {
+        j = owner - 1;
+        continue;
+      }
+      const inner = tail(tokens, token.match + 1, j);
+      if (inner !== "empty") return inner;
+      j = token.match - 1;
+      continue;
+    }
+    if (token.kind === "char" && MARKS.has(token.text)) return { mark: j };
+    return "clean";
+  }
+  return "empty";
+}
+function classify(tokens, j, rowEnd, allowed) {
+  const token = tokens[j];
+  const base = { index: token.start, mark: token.text, rowEnd };
+  if (token.text !== ".") return { ...base, kind: "sentence" };
+  const isChar = (k, pattern) => tokens[k]?.kind === "char" && pattern.test(tokens[k].text);
+  if (isChar(j - 1, /^\.$/)) return { ...base, kind: "ellipsis" };
+  if (isChar(j - 1, /^\d$/)) {
+    let k = j - 1;
+    while (isChar(k - 1, /^\d$/)) k -= 1;
+    if (!isChar(k - 1, /^[_^]$/)) return { ...base, kind: "decimal" };
+  }
+  const owner = token.parent >= 0 ? groupOwner(tokens, token.parent, 0) : void 0;
+  if (owner !== void 0 && UPRIGHT.has(tokens[owner].text)) {
+    let k = j;
+    while (isChar(k - 1, /^[A-Za-z.]$/)) k -= 1;
+    const word = tokens.slice(k, j + 1).map((t) => t.text).join("");
+    if (/[A-Za-z]/.test(word)) {
+      if (allowed.has(word)) return void 0;
+      return { ...base, kind: "abbreviation", word };
+    }
+  }
+  return { ...base, kind: "sentence" };
+}
+function allowedAbbreviations(options) {
+  const deny = new Set(options.deny ?? []);
+  return /* @__PURE__ */ new Set([
+    ...MATH_END_ABBREVIATIONS.filter((word) => !deny.has(word)),
+    ...options.allow ?? []
+  ]);
+}
+function findings(latex, allowed) {
+  const tokens = tokenize(latex);
+  const byMark = /* @__PURE__ */ new Map();
+  const record = (result, rowEnd) => {
+    if (typeof result !== "object" || byMark.has(result.mark)) return;
+    const finding = classify(tokens, result.mark, rowEnd, allowed);
+    if (finding) byMark.set(result.mark, finding);
+  };
+  tokens.forEach((token, k) => {
+    if (token.kind === "command" && token.text === "\\") record(tail(tokens, token.parent + 1, k), true);
+  });
+  record(tail(tokens, 0, tokens.length), false);
+  return [...byMark.values()].sort((left, right) => left.index - right.index);
+}
+function trailingPunctuation(latex, options = {}) {
+  return findings(latex, allowedAbbreviations(options));
+}
+const SEE = "See docs/authoring/notation.md#n12.";
+function messageFor(finding, snippet) {
+  const where = finding.rowEnd ? "ends a row of the math (before `\\\\`)" : "ends the math";
+  switch (finding.kind) {
+    case "decimal":
+      return `"${snippet}" ${where} with a trailing decimal point, which cannot be told apart from the sentence's full stop. Drop the point, or write the digits that state the precision (\`5.0\`); keep a full stop outside the math. ${SEE}`;
+    case "ellipsis":
+      return `"${snippet}" ${where} with a typed "...". Write \`\\ldots\`, and keep a full stop outside the math. ${SEE}`;
+    case "abbreviation":
+      return `"${snippet}" ${where} with "${finding.word}". If that abbreviation is notation (like \`\\text{h.c.}\`), add it to \`rules.N12.allow\`; if the "." is the sentence's full stop, move it after the closing \`$\`. ${SEE}`;
+    case "sentence":
+      return finding.rowEnd ? `"${snippet}" ${where} with "${finding.mark}" \u2014 the sentence's own punctuation. Drop it; the row break already separates the lines. ${SEE}` : `"${snippet}" ${where} with "${finding.mark}" \u2014 the sentence's own punctuation. Move it after the closing \`$\` (inline math) or drop it (display math). ${SEE}`;
+  }
+}
+function snippetOf(latex, index) {
+  const from = Math.max(0, index - 24);
+  const text = latex.slice(from, index + 1).replace(/\s+/g, " ").trimStart();
+  return from > 0 ? `\u2026${text}` : text;
+}
+function gateMathPunctuation(lessons, options = {}) {
+  const allowed = allowedAbbreviations(options);
+  const diagnostics = [];
+  for (const lesson of lessons) {
+    for (const span of mathSpans(lesson.body)) {
+      const equation = equationLinkFor(lesson.lessonId, span.latex);
+      for (const finding of findings(span.latex, allowed)) {
+        const at = span.offset + finding.index;
+        const snippet = snippetOf(span.latex, finding.index);
+        diagnostics.push({
+          context: "body",
+          code: "math-trailing-punctuation",
+          severity: "error",
+          file: lesson.source.file,
+          line: lessonLine(lesson, at),
+          column: at - lesson.body.lastIndexOf("\n", at - 1),
+          token: snippet,
+          ...equation === void 0 ? {} : { equation },
+          message: messageFor(finding, snippet)
+        });
+      }
+    }
+  }
+  return diagnostics;
+}
+function gateMathPunctuationInAssessments(assessments, options = {}) {
+  const allowed = allowedAbbreviations(options);
+  const diagnostics = [];
+  for (const assessment of assessments) {
+    for (const item of assessment.items ?? []) {
+      for (const field of [item.prompt, item.explanation]) {
+        if (typeof field !== "string") continue;
+        for (const span of mathSpans(field)) {
+          for (const finding of findings(span.latex, allowed)) {
+            const snippet = snippetOf(span.latex, finding.index);
+            diagnostics.push({
+              context: "assessment",
+              code: "math-trailing-punctuation",
+              severity: "error",
+              file: `${assessment.id} (${item.id ?? "?"})`,
+              token: snippet,
+              message: messageFor(finding, snippet)
+            });
+          }
+        }
+      }
+    }
+  }
+  return diagnostics;
+}
+export {
+  MATH_END_ABBREVIATIONS,
+  gateMathPunctuation,
+  gateMathPunctuationInAssessments,
+  trailingPunctuation
+};

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

@@ -15,7 +15,7 @@ interface EquationLink {
     readonly href: string;
 }
 interface MathGateDiagnostic {
-    readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation' | 'structure';
+    readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation' | 'structure' | 'course';
     /**
      * Body / component-slot math blocks the build (the render path needs every
      * glyph resolved for the KaTeX trust callback). `formula` joined it at D15:
@@ -34,13 +34,18 @@ interface MathGateDiagnostic {
      * `gate-abbreviations.ts`) is the same "ships straight as an error" story
      * for a different shape of plain-text token — an unexplained acronym or
      * dotted abbreviation, rather than a mis-typed quantity/unit. `structure`
-     * (S1, `gate-heading-length.ts`) is unrelated to notation — it caps how
-     * long a heading or a keyed float's title may run — but reuses this same
+     * (S1, `gate-heading-length.ts`; S2, `gate-part-pages.ts`) is unrelated to
+     * notation — it caps how long a heading or a keyed float's title may run,
+     * and requires a part page's bridge and scope paragraphs — but reuses this same
      * diagnostic shape and the one `manifest.diagnostics.math` array rather
-     * than adding a second array the CLI has to know about.
+     * than adding a second array the CLI has to know about. `course`
+     * (`gate-course-rules.ts`) is a rule the *course* wrote in `courseRules`, not
+     * one the engine ships; its severity is the course's choice, so it is the one
+     * context whose severity is not fixed here.
      */
     readonly severity: 'error' | 'warning';
-    readonly code?: string;
+    /** Owned by exactly one rule or invariant in `src/rules/catalog.ts`. */
+    readonly code: string;
     readonly file: string;
     readonly line?: number;
     readonly column?: number;
@@ -62,6 +67,15 @@ interface LessonAssessmentLink {
     readonly lessonId: string;
     readonly assessmentIds: readonly string[];
 }
+interface MathSpan {
+    readonly latex: string;
+    readonly line: number;
+    readonly column: number;
+    /** Index of `latex` in the text it was cut from. */
+    readonly offset: number;
+}
+/** Every `$$…$$` then `$…$` span in `body`, outside code, with its position. */
+declare function mathSpans(body: string): MathSpan[];
 type ScopeEntry = {
     key: string;
     notation: string;
@@ -80,6 +94,8 @@ declare function pageScope(lesson: NotationLessonInput, sharedByKey: ReadonlyMap
  * reset before use — a stale one would skip the first label of the next span.
  */
 declare function equationLinkFor(lessonId: string, latex: string): EquationLink | undefined;
+/** Decorations a lesson suspends (`notation.suspend`, rule N22), by name. */
+declare function suspendedOperators(lesson: NotationLessonInput): string[];
 /**
  * Resolve every rendered-math context against the page glyph table. Returns one
  * diagnostic per unresolved token; an empty array means the gate passed.
@@ -90,4 +106,4 @@ declare function gateContentMath(input: {
     readonly lessonAssessments: readonly LessonAssessmentLink[];
 }): MathGateDiagnostic[];
 
-export { type EquationLink, type MathGateDiagnostic, type ScopeEntry, equationLinkFor, gateContentMath, pageScope };
+export { type EquationLink, type MathGateDiagnostic, type MathSpan, type ScopeEntry, equationLinkFor, gateContentMath, mathSpans, pageScope, suspendedOperators };

package/dist/reference/gate-math.js

@@ -12,7 +12,9 @@ const SEVERITY = {
   assessment: "error",
   prose: "error",
   abbreviation: "error",
-  structure: "error"
+  structure: "error",
+  // Never read: `gateCourseRules` sets the severity the course chose.
+  course: "error"
 };
 const TERM_KEY = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
 const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
@@ -38,7 +40,8 @@ function mathSpans(body) {
       spans.push({
         latex,
         line: lineOf(body, latexOffset),
-        column: latexOffset - lastNewline
+        column: latexOffset - lastNewline,
+        offset: latexOffset
       });
     }
   }
@@ -71,7 +74,10 @@ function equationLinkFor(lessonId, latex) {
   const slug = lessonId.replace(/\./g, "/");
   return { key, href: `/${slug}/#${equationAnchorId({ key })}` };
 }
-function resolveInto(latex, scope, context, file, line, column, fix, out, equation) {
+function suspendedOperators(lesson) {
+  return (lesson.suspended ?? []).map((item) => item.operator);
+}
+function resolveInto(latex, scope, context, file, line, column, fix, out, equation, suspended = []) {
   const at = equation === void 0 ? {} : { equation };
   for (const diagnostic of lintDelimiterSizes(latex)) {
     const locatedLine = line === void 0 ? void 0 : line + diagnostic.line - 1;
@@ -89,10 +95,15 @@ function resolveInto(latex, scope, context, file, line, column, fix, out, equati
   }
   let result;
   try {
-    result = resolveMathGlyphs(stripEquationLabels(latex), [...scope]);
+    result = resolveMathGlyphs(stripEquationLabels(latex), [...scope], {
+      suspended
+    });
   } catch (error) {
     out.push({
       context,
+      // The resolver's own code (`unparenthesized-function`, `invalid-latex`,
+      // …) is what the rule catalog keys on; anything else is a KaTeX crash.
+      code: error instanceof GlyphResolutionError && typeof error.code === "string" ? error.code : "math-compile-error",
       severity: SEVERITY[context],
       file,
       line,
@@ -100,15 +111,31 @@ function resolveInto(latex, scope, context, file, line, column, fix, out, equati
     });
     return;
   }
-  for (const { token } of result.unresolved) {
+  for (const item of result.unresolved) {
+    const { token } = item;
+    if ("suspended" in item && typeof item.suspended === "string") {
+      out.push({
+        context,
+        code: "suspended-operator-unresolved",
+        severity: SEVERITY[context],
+        file,
+        line,
+        token,
+        ...at,
+        message: `On this page ${JSON.stringify(item.suspended)} is suspended (notation.suspend), so ${JSON.stringify(token)} is not ${JSON.stringify(item.suspended)} applied to a symbol: it needs its own notation entry (latex: ${token}) or an \\explain{key}{${token}} wrap.`
+      });
+      continue;
+    }
+    const fontHint = "font" in item && typeof item.font === "string" ? ` ${token} is a different symbol from the plain letter: give it its own entry (latex: ${token}) or wrap it in \\explain{key}{${token}}.` : "";
     out.push({
       context,
+      code: "unresolved-glyph",
       severity: SEVERITY[context],
       file,
       line,
       token,
       ...at,
-      message: `Unresolved notation ${JSON.stringify(token)} in ${context} math. ${fix}`
+      message: `Unresolved notation ${JSON.stringify(token)} in ${context} math.${fontHint} ${fix}`
     });
   }
 }
@@ -132,6 +159,9 @@ function reportUnknownScopeKeys(definition, cardKeys, file, out) {
   )) {
     out.push({
       context: "formula",
+      // Same failure the resolver reports for a body `\explain{key}` that
+      // names nothing — one code, one owner (`notation-references`).
+      code: "unknown-explicit-key",
       severity: SEVERITY.formula,
       file,
       token: key,
@@ -172,6 +202,7 @@ function gateContentMath(input) {
   for (const lesson of notationInput.lessons) {
     const scope = pageScope(lesson, sharedByKey);
     const file = lesson.source.file;
+    const suspended = suspendedOperators(lesson);
     const bodyOffset = (lesson.bodyLine ?? 1) - 1;
     for (const span of mathSpans(lesson.body)) {
       resolveInto(
@@ -183,7 +214,8 @@ function gateContentMath(input) {
         span.column,
         BODY_FIX,
         diagnostics,
-        equationLinkFor(lesson.lessonId, span.latex)
+        equationLinkFor(lesson.lessonId, span.latex),
+        suspended
       );
     }
     for (const definition of lesson.localDefinitions) {
@@ -263,5 +295,7 @@ function gateContentMath(input) {
 export {
   equationLinkFor,
   gateContentMath,
-  pageScope
+  mathSpans,
+  pageScope,
+  suspendedOperators
 };

package/dist/reference/gate-part-pages.d.ts

@@ -0,0 +1,50 @@
+import { N as NormalizedPartPages } from '../course-config-Dsnri9Tk.js';
+import { MathGateDiagnostic } from './gate-math.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.js';
+import './types.js';
+
+/**
+ * The part-page gate (rule S2): a part's overview page
+ * (`content/docs/<dir>/index.mdx`) states, in two authored paragraphs, how
+ * the course got here and where this part goes —
+ *
+ * - `<PartBridge>` — how the earlier parts lead into this one. Required on
+ *   every part after the first; optional on the first, which has no earlier
+ *   part to link from.
+ * - `<PartScope>` — what this part itself covers. Required on every part page.
+ *
+ * Each must appear once, hold exactly one paragraph, and fall inside the
+ * course's rule-S2 word range (`rules.S2.*`, see `partPageLimits`); the bridge comes
+ * first. What a paragraph *says* is Review-only — the gate checks that the
+ * slot is there and sized, not that its prose is about the right thing. See
+ * docs/authoring/structure-rules.md#s2.
+ *
+ * A part without an overview page is not in scope: overview pages stay
+ * opt-in, and this gate only shapes the ones a course authors. Ships straight
+ * as an error, same as S1.
+ */
+
+/** One part overview page, as the manifest compiler loads it. */
+interface PartPageInput {
+    readonly dir: string;
+    /** 1-based position in `courseConfig.parts`. */
+    readonly ordinal: number;
+    readonly file: string;
+    readonly body: string;
+    readonly bodyLine: number;
+}
+/**
+ * Words a reader reads in a paragraph of MDX prose. A math span, a `[[key]]`
+ * reference, or a link each count by what they render as: one token for the
+ * first two, the link text for the third. Citations and markup count nothing.
+ */
+declare function proseWordCount(markdown: string): number;
+/**
+ * Check every part overview page for its S2 paragraphs. Returns one
+ * `MathGateDiagnostic` (context `'structure'`, code `part-page-paragraph`,
+ * always an error) per finding.
+ */
+declare function gatePartPages(pages: readonly PartPageInput[], limits: NormalizedPartPages): MathGateDiagnostic[];
+
+export { type PartPageInput, gatePartPages, proseWordCount };

package/dist/reference/gate-part-pages.js

@@ -0,0 +1,118 @@
+import { stripFencedCode } from "./equations.mjs";
+import { lessonLine } from "./gate-prose-notation.js";
+const TAG_BY_SLOT = {
+  bridge: "PartBridge",
+  scope: "PartScope"
+};
+const SUBJECT_BY_SLOT = {
+  bridge: "how the earlier parts lead into this one",
+  scope: "what this part covers"
+};
+function scannable(body) {
+  return stripFencedCode(body).replace(
+    /\{\/\*[\s\S]*?\*\/\}/g,
+    (comment) => comment.replace(/[^\n]/g, " ")
+  );
+}
+function occurrencesOf(text, tag) {
+  const pattern = new RegExp(
+    `<${tag}\\b[^>]*?(?:\\/>|>([\\s\\S]*?)<\\/${tag}\\s*>)`,
+    "g"
+  );
+  return [...text.matchAll(pattern)].map((match) => ({
+    index: match.index ?? 0,
+    content: match[1]
+  }));
+}
+function paragraphsOf(content) {
+  return content.trim().split(/\n[ \t]*\n/).filter((block) => block.trim().length > 0);
+}
+function proseWordCount(markdown) {
+  return markdown.replace(/\$\$[\s\S]*?\$\$/g, " math ").replace(/\$[^$\n]+\$/g, " math ").replace(/\[@[^\]]*\]/g, " ").replace(/\[\[[^\][]+\]\]/g, " term ").replace(/!?\[([^\]]*)\]\([^)]*\)/g, " $1 ").replace(/<\/?[A-Za-z][^>]*>/g, " ").split(/\s+/).filter((token) => /[\p{L}\p{N}]/u.test(token)).length;
+}
+function slotFindings(page, text, slot, limits) {
+  const tag = TAG_BY_SLOT[slot];
+  const found = occurrencesOf(text, tag);
+  const required = slot === "scope" || page.ordinal > 1;
+  const out = [];
+  if (found.length === 0) {
+    if (required) {
+      out.push({
+        index: 0,
+        token: `<${tag}>`,
+        message: `Part ${page.ordinal} ("${page.dir}") has an overview page with no <${tag}> paragraph (rule S2). Add one paragraph on ${SUBJECT_BY_SLOT[slot]}, wrapped in <${tag}>\u2026</${tag}>.`
+      });
+    }
+    return out;
+  }
+  for (const extra of found.slice(1)) {
+    out.push({
+      index: extra.index,
+      token: `<${tag}>`,
+      message: `A part overview page carries one <${tag}> (rule S2); this is another. Merge the two into one paragraph.`
+    });
+  }
+  const [first] = found;
+  const paragraphs = paragraphsOf(first.content ?? "");
+  if (paragraphs.length === 0) {
+    out.push({
+      index: first.index,
+      token: `<${tag}>`,
+      message: `<${tag}> is empty (rule S2). Write one paragraph on ${SUBJECT_BY_SLOT[slot]} inside it.`
+    });
+    return out;
+  }
+  if (paragraphs.length > 1) {
+    out.push({
+      index: first.index,
+      token: `<${tag}>`,
+      message: `<${tag}> holds ${paragraphs.length} paragraphs; rule S2 allows one. Join them, or move the rest of the prose outside the slot.`
+    });
+    return out;
+  }
+  const { minWords, maxWords } = limits[slot];
+  const words = proseWordCount(paragraphs[0]);
+  if (words < minWords || words > maxWords) {
+    out.push({
+      index: first.index,
+      token: `<${tag}>`,
+      message: `<${tag}> is ${words} words; rule S2 wants ${minWords}\u2013${maxWords} (rules.S2.${slot}MinWords / ${slot}MaxWords in the course settings). ` + (words < minWords ? `Say more about ${SUBJECT_BY_SLOT[slot]}.` : "Cut it to the connections a reader needs before the chapter list.")
+    });
+  }
+  return out;
+}
+function gatePartPages(pages, limits) {
+  const diagnostics = [];
+  for (const page of pages) {
+    const text = scannable(page.body);
+    const findings = [
+      ...slotFindings(page, text, "bridge", limits),
+      ...slotFindings(page, text, "scope", limits)
+    ];
+    const [bridge] = occurrencesOf(text, TAG_BY_SLOT.bridge);
+    const [scope] = occurrencesOf(text, TAG_BY_SLOT.scope);
+    if (bridge && scope && bridge.index > scope.index) {
+      findings.push({
+        index: bridge.index,
+        token: "<PartBridge>",
+        message: "<PartBridge> comes after <PartScope> (rule S2). Move it first: the reader needs the link from the earlier parts before this part's own scope."
+      });
+    }
+    for (const finding of findings.sort((a, b) => a.index - b.index)) {
+      diagnostics.push({
+        context: "structure",
+        severity: "error",
+        code: "part-page-paragraph",
+        file: page.file,
+        line: lessonLine(page, finding.index),
+        token: finding.token,
+        message: finding.message
+      });
+    }
+  }
+  return diagnostics;
+}
+export {
+  gatePartPages,
+  proseWordCount
+};

package/dist/reference/gate-prose-notation.d.ts

@@ -6,7 +6,8 @@ import { NotationLessonInput } from './types.js';
  * completeness gate (`gate-math.ts`). Where that gate asks "does every glyph
  * *inside* `$…$` resolve", this one asks the complementary question: "is
  * anything that reads as math sitting *outside* `$…$` in the first place" —
- * a unit abbreviation, a division of two variable-like symbols, an escaped
+ * a unit abbreviation, a unit spelled out as a word next to a number or
+ * `per` (`unit-words.ts`), a division of two variable-like symbols, an escaped
  * absolute-value bar, a hand-typed sub/superscript. Both gates share one
  * `MathGateDiagnostic` shape and one output array (`manifest.diagnostics.math`)
  * so the CLI needs no separate wiring.
@@ -31,12 +32,13 @@ interface AssessmentLike {
     readonly items?: readonly AssessmentItemLike[];
 }
 /**
- * Blank code, math, reference, and JSX-tag spans so offsets don't shift.
- * Exported so `gate-abbreviations.ts` (N14) scans exactly the same "is this
- * really prose" surface as N9, instead of drifting with a second copy of
- * these regexes.
+ * `keepMath` leaves `$…$` / `$$…$$` in place (everything else still blanked,
+ * offsets unchanged) — for a check that needs to see what a math span sits
+ * next to, such as `$x = 3$ meters`.
  */
-declare function proseOnly(body: string): string;
+declare function proseOnly(body: string, options?: {
+    readonly keepMath?: boolean;
+}): string;
 /** Exported for the same reason as {@link proseOnly}. */
 declare function lineOf(text: string, index: number): number;
 /**
@@ -50,12 +52,20 @@ declare function lessonLine(lesson: {
     readonly body: string;
     readonly bodyLine?: number;
 }, index: number): number;
+/** Rule N9's settings the gate reads (`rules.N9` in the course settings). */
+interface ProseNotationOptions {
+    /** Unit words this course lets prose spell out (`rules.N9.allow`), singular or plural. */
+    readonly allowSpelledUnits?: readonly string[];
+}
 /**
  * Scan every lesson body for plain-text math notation outside `$…$`. Returns
- * one `MathGateDiagnostic` (context `'prose'`, always an error — N9 has no
- * escape hatch) per finding.
+ * one `MathGateDiagnostic` (context `'prose'`, always an error) per finding:
+ * code `spelled-unit` for a unit written as a word ("2 meters per second
+ * squared", "30 degrees"), `prose-notation` for everything else. A place is
+ * excused with a waiver (`{/* explico-allow N9: reason *\/}`), applied by the
+ * manifest.
  */
-declare function gateProseNotation(lessons: readonly NotationLessonInput[]): MathGateDiagnostic[];
+declare function gateProseNotation(lessons: readonly NotationLessonInput[], options?: ProseNotationOptions): MathGateDiagnostic[];
 /**
  * Scan every assessment `prompt` / `explanation` for the same plain-text
  * notation N9 forbids in a lesson body — `AssessmentRunner` renders both
@@ -66,6 +76,6 @@ declare function gateProseNotation(lessons: readonly NotationLessonInput[]): Mat
  * same `"<assessmentId> (<itemId>)"` shape `gate-math.ts` already uses for
  * this context.
  */
-declare function gateProseNotationInAssessments(assessments: readonly AssessmentLike[]): MathGateDiagnostic[];
+declare function gateProseNotationInAssessments(assessments: readonly AssessmentLike[], options?: ProseNotationOptions): MathGateDiagnostic[];
 
-export { gateProseNotation, gateProseNotationInAssessments, lessonLine, lineOf, proseOnly };
+export { type ProseNotationOptions, gateProseNotation, gateProseNotationInAssessments, lessonLine, lineOf, proseOnly };