explico 0.1.1 → 0.3.0

package/dist/reference/equations.mjs

@@ -1,22 +1,28 @@
 /**
- * Equation identity (Step D7) — shared, framework-free helpers.
+ * Equation identity (Step D7, extended F3) — shared, framework-free helpers.
  *
- * An author marks a display equation by putting a trailing `\label{eq:<key>}`
- * inside its `$$…$$` block (inside math, so the `:` is safe and the form
- * matches amsmath). The compiler assigns the *visible* number from appearance
- * order, scoped to the enclosing `##` section (`(2.4)` = fourth keyed equation
- * under the second section). The number is never authored; unkeyed display
- * equations render clean and stay un-referenceable. Prose refers to an
- * equation with the reserved `eq-` prefix (a bare `:` in `[[…]]` prose would
- * be eaten by `remark-directive`):
+ * Every display equation (`$$…$$`) in a lesson is numbered and given an `id`
+ * from appearance order. When the caller supplies a `chapter` (the lesson's
+ * ordinal position in the course), the number is `‹chapter›.‹n›` — `n` counts
+ * every display equation in the lesson and `##` headings do not affect it
+ * (`(2.4)` = fourth display equation of the second lesson). With no `chapter`
+ * the number falls back to the `##`-section scheme `‹section›.‹indexInSection›`
+ * (used by hand-built test trees and non-lesson pages). An author additionally
+ * marks an equation with a trailing `\label{eq:<key>}` inside its `$$…$$`
+ * block (inside math, so the `:` is safe and the form matches amsmath) when
+ * they want a *stable* anchor that survives edits and cross-page references:
  *
  *   [[eq-discount-factor-def]]           same page  → "(2.4)" linked to #eq-…
  *   [[foundations/present-value#eq-pv]]  cross page → number from the manifest
  *
+ * An unkeyed equation still gets a positional anchor (`#eq-2-4`) so it can be
+ * deep-linked, but only a keyed equation is referenceable by name.
+ *
  * `scanEquationLabels` (raw Markdown) and `collectEquationLabels` (mdast tree)
  * MUST agree — `tests/notation/equations.test.ts` checks that on the real
  * corpus. Both are here so `manifest.ts` and `remark-notation.mjs` share one
- * numbering algorithm.
+ * numbering algorithm. `collectDisplayEquations` is the superset the render
+ * path uses to number and anchor every display equation, keyed or not.
  */
 
 /** `eq:` key grammar — the notation-key shape without the dotted namespaces. */
@@ -51,25 +57,68 @@ export function stripEquationLabels(latex) {
     .trim();
 }
 
-/** The visible number for the `index`-th keyed equation under `section`. */
+/** The visible number for the `index`-th display equation under `section`. */
 function equationNumber(section, index) {
   return section > 0 ? `${section}.${index}` : String(index);
 }
 
-function stripFencedCode(markdown) {
+/**
+ * The visible number for one display equation. With `chapter` (the lesson's
+ * course ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings
+ * are ignored; without it, the legacy `##`-section scheme.
+ */
+export function displayEquationNumber({
+  chapter,
+  section,
+  indexInSection,
+  indexInLesson,
+}) {
+  return chapter == null
+    ? equationNumber(section, indexInSection)
+    : `${chapter}.${indexInLesson}`;
+}
+
+/** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
+export function equationAnchorId({ key, number }) {
+  return key ? `eq-${key}` : `eq-${String(number).replace(/\./g, '-')}`;
+}
+
+export function stripFencedCode(markdown) {
   return String(markdown)
     .replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, ' '))
     .replace(/~~~[\s\S]*?~~~/g, (block) => block.replace(/[^\n]/g, ' '))
     .replace(/(^|[^`])`[^`\n]*`/g, (match) => match.replace(/[^\n]/g, ' '));
 }
 
+/**
+ * Blank the body of every block-level MDX component (`<Capitalised …> … </…>`)
+ * so a `$$…$$` used to illustrate a worked example inside `<CompactExample>`
+ * (or an `<Aside>`, etc.) is not counted as a lesson-body equation. The
+ * outermost match wins, so nested components are blanked in one pass;
+ * newlines are kept so line/section structure is unchanged.
+ *
+ * `keep`, when given, leaves a component of that name untouched instead of
+ * blanking it — `keyed-jsx-floats.mjs` uses this to blank every *other*
+ * component while still finding `<Table>`/`<Figure>` tags at the top level.
+ */
+export function stripJsxComponents(markdown, keep) {
+  return String(markdown).replace(
+    /<([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>/g,
+    (block, name) => (name === keep ? block : block.replace(/[^\n]/g, ' ')),
+  );
+}
+
 /**
  * Every keyed display equation in a Markdown body, in appearance order, with
- * its assigned number. `$$…$$` blocks only; `##` headings between them advance
- * the section counter.
+ * its assigned number. `$$…$$` blocks only. With `chapter` (the lesson's
+ * course ordinal) the number is `‹chapter›.‹n›`, `n` sequential over every
+ * display block in the lesson; without it, `##` headings advance a section
+ * counter and the number is `‹section›.‹indexInSection›`. Either way every
+ * display block advances the index, so a keyed equation's number reflects its
+ * position among *all* display equations, not only the keyed ones.
  */
-export function scanEquationLabels(markdown) {
-  const text = stripFencedCode(markdown);
+export function scanEquationLabels(markdown, chapter) {
+  const text = stripJsxComponents(stripFencedCode(markdown));
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const display = /\$\$([\s\S]+?)\$\$/g;
@@ -79,15 +128,18 @@ export function scanEquationLabels(markdown) {
   for (const match of text.matchAll(display)) {
     EQ_LABEL_PATTERN.lastIndex = 0;
     const label = EQ_LABEL_PATTERN.exec(match[1]);
-    if (label) {
-      tokens.push({ kind: 'equation', index: match.index, key: label[1] });
-    }
+    tokens.push({
+      kind: 'equation',
+      index: match.index,
+      key: label ? label[1] : null,
+    });
   }
   tokens.sort((a, b) => a.index - b.index);
 
   const labels = [];
   let section = 0;
   let indexInSection = 0;
+  let indexInLesson = 0;
   for (const token of tokens) {
     if (token.kind === 'section') {
       section += 1;
@@ -95,9 +147,16 @@ export function scanEquationLabels(markdown) {
       continue;
     }
     indexInSection += 1;
+    indexInLesson += 1;
+    if (token.key == null) continue;
     labels.push({
       key: token.key,
-      number: equationNumber(section, indexInSection),
+      number: displayEquationNumber({
+        chapter,
+        section,
+        indexInSection,
+        indexInLesson,
+      }),
       section,
       indexInSection,
     });
@@ -106,39 +165,57 @@ export function scanEquationLabels(markdown) {
 }
 
 /**
- * The mdast equivalent of `scanEquationLabels`: walk the tree in document
- * order, advancing the section counter on every depth-2 heading and emitting a
- * label for every `math` node whose source carries `\label{eq:…}`.
+ * The mdast equivalent of `scanEquationLabels` for *every* display equation:
+ * walk the tree in document order, advancing the section counter on every
+ * depth-2 heading and emitting a record for every `math` node. `key` is the
+ * `\label{eq:…}` payload when present, else `null`. `chapter` is threaded the
+ * same way as in `scanEquationLabels`.
  */
-export function collectEquationLabels(tree) {
-  const labels = [];
+export function collectDisplayEquations(tree, chapter) {
+  const equations = [];
   let section = 0;
   let indexInSection = 0;
+  let indexInLesson = 0;
 
-  const walk = (node) => {
-    if (!node || typeof node !== 'object') return;
+  // Only top-level blocks: a `$$…$$` nested in an MDX component (a
+  // `<CompactExample>` worked example, an `<Aside>`) is illustrative, not part
+  // of the lesson's equation sequence, and its container may be collapsed.
+  const children = Array.isArray(tree?.children) ? tree.children : [];
+  for (const node of children) {
+    if (!node || typeof node !== 'object') continue;
     if (node.type === 'heading' && node.depth === 2) {
       section += 1;
       indexInSection = 0;
-      return;
+      continue;
     }
     if (node.type === 'math') {
+      indexInSection += 1;
+      indexInLesson += 1;
       EQ_LABEL_PATTERN.lastIndex = 0;
       const label = EQ_LABEL_PATTERN.exec(String(node.value ?? ''));
-      if (label) {
-        indexInSection += 1;
-        labels.push({
-          key: label[1],
-          number: equationNumber(section, indexInSection),
+      equations.push({
+        key: label ? label[1] : null,
+        number: displayEquationNumber({
+          chapter,
           section,
           indexInSection,
-          node,
-        });
-      }
-      return;
+          indexInLesson,
+        }),
+        section,
+        indexInSection,
+        node,
+      });
     }
-    if (Array.isArray(node.children)) node.children.forEach(walk);
-  };
-  walk(tree);
-  return labels;
+  }
+  return equations;
+}
+
+/**
+ * The keyed subset of `collectDisplayEquations` — the tree-walk counterpart of
+ * `scanEquationLabels`. Numbers reflect position among all display equations.
+ */
+export function collectEquationLabels(tree, chapter) {
+  return collectDisplayEquations(tree, chapter).filter(
+    (equation) => equation.key != null,
+  );
 }

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

@@ -0,0 +1,21 @@
+import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } from './keyed-float-validate.js';
+
+/** `validateKeyedFloats` for `<Figure>` — see `keyed-float-validate.ts`. */
+
+type FigureDiagnosticCode = 'fig-invalid-key' | 'fig-duplicate-key' | 'fig-ref-resolves' | 'fig-key-unused';
+interface FigureDiagnostic {
+    readonly code: FigureDiagnosticCode;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+    readonly key?: string;
+}
+type FigureLabelRecord = KeyedFloatLabelRecord;
+type FigureLessonInput = KeyedFloatLessonInput;
+interface FigureValidation extends KeyedFloatValidation {
+    readonly diagnostics: readonly FigureDiagnostic[];
+}
+declare function validateFigures(lessons: readonly FigureLessonInput[]): FigureValidation;
+
+export { type FigureDiagnostic, type FigureDiagnosticCode, type FigureLabelRecord, type FigureLessonInput, type FigureValidation, validateFigures };

package/dist/reference/figures-validate.js

@@ -0,0 +1,13 @@
+import {
+  validateKeyedFloats
+} from "./keyed-float-validate.js";
+function validateFigures(lessons) {
+  return validateKeyedFloats(lessons, {
+    tagName: "Figure",
+    prefix: "fig",
+    noun: "figure"
+  });
+}
+export {
+  validateFigures
+};

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

@@ -4,10 +4,11 @@ interface MathGateDiagnostic {
     readonly context: 'body' | 'formula' | 'assessment';
     /**
      * Body / component-slot math blocks the build (the render path needs every
-     * glyph resolved for the KaTeX trust callback). `formula` and `assessment`
-     * math enter as warnings (Tier 3) and are promoted once existing content is
-     * brought into line — they surface pre-existing ambiguities that are a
-     * separate reviewed content pass (D6/D13/D14), not a D3 codemod.
+     * glyph resolved for the KaTeX trust callback). `formula` joined it at D15:
+     * a formula's glyphs are now rendered live and explorable, so an unresolved
+     * one is a hole the reader can see, and the corpus was brought to zero when
+     * the tier was promoted. `assessment` math stays a Tier-3 warning until its
+     * own reviewed content pass (D6/D13/D14).
      */
     readonly severity: 'error' | 'warning';
     readonly file: string;

package/dist/reference/gate-math.js

@@ -1,8 +1,9 @@
 import { resolveMathGlyphs, GlyphResolutionError } from "./math-glyphs.mjs";
 import { stripEquationLabels } from "./equations.mjs";
+import { formulaGlyphScope, unknownFormulaScopeKeys } from "./gloss.js";
 const SEVERITY = {
   body: "error",
-  formula: "warning",
+  formula: "error",
   assessment: "warning"
 };
 const TERM_KEY = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
@@ -75,6 +76,33 @@ function resolveInto(latex, scope, context, file, line, fix, out) {
   }
 }
 const BODY_FIX = "Introduce the symbol with [[key]], define it in notation.local, or wrap it in \\explain{key}{latex}.";
+function dedupeScope(scope) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const entry of scope) {
+    if (seen.has(entry.key)) continue;
+    seen.add(entry.key);
+    out.push(entry);
+  }
+  return out;
+}
+function reportUnknownScopeKeys(definition, cardKeys, file, out) {
+  const glossKeys = new Set(definition.glosses.map((gloss) => gloss.key));
+  for (const key of unknownFormulaScopeKeys(
+    definition.formula,
+    glossKeys,
+    cardKeys
+  )) {
+    out.push({
+      context: "formula",
+      severity: SEVERITY.formula,
+      file,
+      token: key,
+      message: `${definition.key} formula names unknown notation key ${JSON.stringify(key)}. Name an existing card, or declare the symbol under glosses: on this entry.`
+    });
+  }
+}
+const SHARED_FORMULA_FIX = "Every symbol in a notation entry formula must resolve to the entry itself, one of its glosses:, a card the formula names with \\explain{key}{latex}, or the base library.";
 const FORMULA_FIX = "Every right-hand-side variable of a notation.local formula must resolve to the entry key, another page symbol, or the base library.";
 const ASSESSMENT_FIX = "Introduce the symbol in the owning lesson's prose with [[key]], or wrap it in \\explain{key}{latex}.";
 function gateContentMath(input) {
@@ -85,6 +113,18 @@ function gateContentMath(input) {
       definition
     ])
   );
+  const sharedCards = new Map(
+    notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      { key: definition.key, notation: definition.notation }
+    ])
+  );
+  const cardKeys = /* @__PURE__ */ new Set([
+    ...sharedCards.keys(),
+    ...notationInput.lessons.flatMap(
+      (lesson) => lesson.localDefinitions.map((definition) => definition.key)
+    )
+  ]);
   const lessonById = new Map(
     notationInput.lessons.map((lesson) => [lesson.lessonId, lesson])
   );
@@ -110,15 +150,46 @@ function gateContentMath(input) {
       if (!definition.formula) continue;
       resolveInto(
         definition.formula,
-        scope,
+        dedupeScope([
+          ...scope,
+          ...definition.glosses.map((gloss) => ({
+            key: gloss.key,
+            notation: gloss.notation
+          }))
+        ]),
         "formula",
         file,
         void 0,
         FORMULA_FIX,
         diagnostics
       );
+      reportUnknownScopeKeys(definition, cardKeys, file, diagnostics);
     }
   }
+  for (const definition of notationInput.sharedDefinitions) {
+    if (!definition.formula) continue;
+    resolveInto(
+      definition.formula,
+      formulaGlyphScope({
+        key: definition.key,
+        notation: definition.notation,
+        formula: definition.formula,
+        glosses: definition.glosses,
+        cardsByKey: sharedCards
+      }),
+      "formula",
+      definition.source.file,
+      void 0,
+      SHARED_FORMULA_FIX,
+      diagnostics
+    );
+    reportUnknownScopeKeys(
+      definition,
+      cardKeys,
+      definition.source.file,
+      diagnostics
+    );
+  }
   for (const link of lessonAssessments) {
     const lesson = lessonById.get(link.lessonId);
     if (!lesson) continue;

package/dist/reference/gloss.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Glosses and formula scope (D15) — the second tier of the notation
+ * vocabulary.
+ *
+ * A **card** is a `content/notation/*.md` entry (or a `notation.local` entry):
+ * symbol, name, description, units, sources, curriculum alignment, review
+ * state. It gets a glossary card and is a node in the curriculum graph.
+ *
+ * A **gloss** is declared on a card, in that card's `glosses:` frontmatter,
+ * and carries a symbol, a name, and optionally a bare units string. It exists
+ * for one reason: so a card's rigorous `formula` can name its own letters
+ * without each letter having to become a card. A gloss has no description, no
+ * sources, no alignment, no review state, and no glossary card — and, the
+ * point of the whole tier, **it creates no curriculum edge**. A card that
+ * dragged its formula's letters into the registry would drag them into the
+ * lesson bundle of every lesson that uses it, and a foundations lesson would
+ * fail `alignment-introduction` on a symbol introduced six lessons later.
+ *
+ * The editorial convention (not enforced here): a card's formula may introduce
+ * glosses; glosses terminate — they have no formula of their own. A symbol
+ * that later needs a real definition is **promoted**: delete the gloss line,
+ * add `content/notation/<key>.md`. Because a formula spells LaTeX and never a
+ * key, nothing else in the corpus changes.
+ */
+interface NotationGlossInput {
+    readonly latex: string;
+    readonly name: string;
+    readonly units?: string;
+}
+/** A gloss with its derived key and display label. */
+interface ResolvedGloss {
+    /** `<card key>.<slug(name)>` — derived, never authored. */
+    readonly key: string;
+    readonly notation: string;
+    readonly label: string;
+    readonly units?: string;
+    /** The card that declares it. */
+    readonly ownerKey: string;
+}
+/** One `{key, notation}` row of the flat table `resolveMathGlyphs` consumes. */
+interface GlyphScopeEntry {
+    readonly key: string;
+    readonly notation: string;
+}
+/**
+ * The key segment derived from a gloss name: lower-cased, runs of anything
+ * that is not a letter or digit collapsed to a single `-`. Returns `undefined`
+ * when the name has no usable characters, so the schema can reject it rather
+ * than the loader minting an invalid key.
+ */
+declare function glossKeySegment(name: string): string | undefined;
+/**
+ * Derive a gloss's key. Dotted onto the owning card's key, so a gloss is
+ * entry-scoped by construction: two cards may each gloss `T`, and a gloss can
+ * never be confused with a card in the flat registry.
+ */
+declare function glossKey(ownerKey: string, name: string): string;
+/** Resolve a card's authored `glosses:` list into keyed, labelled entries. */
+declare function resolveGlosses(ownerKey: string, glosses: readonly NotationGlossInput[]): ResolvedGloss[];
+declare function formulaExplainKeys(formula: string): string[];
+/**
+ * The glyph table a card's `formula` resolves against:
+ *
+ *     {the card itself} ∪ {its glosses} ∪ {cards its formula names} ∪ base library
+ *
+ * Narrower than the registry-wide table a card's *body* math still uses, and
+ * narrower than a lesson page's scope. A card named with `\explain{key}` in
+ * the formula joins the table for glyph resolution **only**: its existence is
+ * checked, but it deliberately becomes no reference edge, because a
+ * definitional letter is not a curriculum prerequisite. See the module note.
+ */
+declare function formulaGlyphScope(input: {
+    readonly key: string;
+    readonly notation: string;
+    readonly formula?: string;
+    readonly glosses: readonly ResolvedGloss[];
+    /** Every card by key — shared entries, plus page-local ones for a lesson. */
+    readonly cardsByKey: ReadonlyMap<string, GlyphScopeEntry>;
+}): GlyphScopeEntry[];
+/**
+ * Keys named by a formula that no card defines. The build reports these — an
+ * `\explain{…}` pointing at nothing is an authoring mistake, not a silent
+ * fallback to an unresolved glyph.
+ */
+declare function unknownFormulaScopeKeys(formula: string | undefined, glossKeys: ReadonlySet<string>, cardKeys: ReadonlySet<string>): string[];
+
+export { type GlyphScopeEntry, type NotationGlossInput, type ResolvedGloss, formulaExplainKeys, formulaGlyphScope, glossKey, glossKeySegment, resolveGlosses, unknownFormulaScopeKeys };

package/dist/reference/gloss.js

@@ -0,0 +1,59 @@
+function glossKeySegment(name) {
+  const segment = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return segment.length > 0 ? segment : void 0;
+}
+function glossKey(ownerKey, name) {
+  const segment = glossKeySegment(name);
+  if (segment === void 0) {
+    throw new Error(
+      `Gloss name ${JSON.stringify(name)} on ${ownerKey} yields no key segment.`
+    );
+  }
+  return `${ownerKey}.${segment}`;
+}
+function resolveGlosses(ownerKey, glosses) {
+  return glosses.map((gloss) => ({
+    key: glossKey(ownerKey, gloss.name),
+    notation: gloss.latex,
+    label: gloss.name,
+    ownerKey,
+    ...gloss.units === void 0 ? {} : { units: gloss.units }
+  }));
+}
+const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
+function formulaExplainKeys(formula) {
+  EXPLAIN_KEY.lastIndex = 0;
+  return [...formula.matchAll(EXPLAIN_KEY)].map((match) => match[1] ?? "");
+}
+function formulaGlyphScope(input) {
+  const scope = [
+    { key: input.key, notation: input.notation }
+  ];
+  const seen = /* @__PURE__ */ new Set([input.key]);
+  for (const gloss of input.glosses) {
+    if (seen.has(gloss.key)) continue;
+    seen.add(gloss.key);
+    scope.push({ key: gloss.key, notation: gloss.notation });
+  }
+  for (const key of formulaExplainKeys(input.formula ?? "")) {
+    if (seen.has(key)) continue;
+    const card = input.cardsByKey.get(key);
+    if (!card) continue;
+    seen.add(key);
+    scope.push({ key: card.key, notation: card.notation });
+  }
+  return scope;
+}
+function unknownFormulaScopeKeys(formula, glossKeys, cardKeys) {
+  return formulaExplainKeys(formula ?? "").filter(
+    (key) => !cardKeys.has(key) && !glossKeys.has(key)
+  );
+}
+export {
+  formulaExplainKeys,
+  formulaGlyphScope,
+  glossKey,
+  glossKeySegment,
+  resolveGlosses,
+  unknownFormulaScopeKeys
+};

package/dist/reference/keyed-float-validate.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Keyed-float validation for `<Table>`/`<Figure>`, run inside
+ * `compileManifest()` — the same three checks `equations-validate.ts` runs
+ * for equations, parameterized over the float kind so the logic exists once:
+ *
+ * - `<prefix>-invalid-key` (error): an `id` must match the key grammar.
+ * - `<prefix>-duplicate-key` (error): an `id` is unique per lesson.
+ * - `<prefix>-ref-resolves` (error): every `[[<prefix>-key]]` /
+ *   `[[slug#<prefix>-key]]` points at a `<Table>`/`<Figure>` with that `id`.
+ * - `<prefix>-key-unused` (warning): a keyed float never referenced.
+ *
+ * `tables-validate.ts` and `figures-validate.ts` are thin wrappers over this
+ * so callers import `validateTables` / `validateFigures` with their own
+ * narrow diagnostic-code types, while `equations-validate.ts` stays
+ * untouched — equations predate this and keep their own dedicated path.
+ */
+interface KeyedFloatKind {
+    /** The MDX component tag, e.g. `Table` or `Figure`. */
+    readonly tagName: string;
+    /** The `[[<prefix>-key]]` reference prefix, e.g. `tab` or `fig`. */
+    readonly prefix: string;
+    /** Lowercase noun used in diagnostic messages, e.g. `table` or `figure`. */
+    readonly noun: string;
+}
+interface KeyedFloatLabelRecord {
+    readonly key: string;
+    readonly number: string;
+    readonly lessonId: string;
+    readonly slug: string;
+    readonly section: number;
+    readonly indexInSection: number;
+}
+interface KeyedFloatRefRecord {
+    readonly key: string;
+    readonly lessonId: string;
+    /** Target lesson slug for a cross-page reference; `undefined` = same page. */
+    readonly targetSlug?: string;
+}
+interface KeyedFloatDiagnostic {
+    readonly code: string;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+    readonly key?: string;
+}
+interface KeyedFloatValidation {
+    /** Every keyed float, sorted by lesson then appearance. */
+    readonly labels: readonly KeyedFloatLabelRecord[];
+    /** `slug -> { key -> number }` — the render path's cross-page lookup table. */
+    readonly numbersBySlug: Record<string, Record<string, string>>;
+    readonly diagnostics: readonly KeyedFloatDiagnostic[];
+}
+interface KeyedFloatLessonInput {
+    readonly lessonId: string;
+    readonly slug: string;
+    readonly file: string;
+    readonly body: string;
+    /**
+     * The lesson's 1-based ordinal in the course. When set, floats are numbered
+     * `‹chapter›.‹n›`; when omitted, the legacy `##`-section scheme.
+     */
+    readonly chapter?: number;
+}
+declare function validateKeyedFloats(lessons: readonly KeyedFloatLessonInput[], kind: KeyedFloatKind): KeyedFloatValidation;
+
+export { type KeyedFloatDiagnostic, type KeyedFloatKind, type KeyedFloatLabelRecord, type KeyedFloatLessonInput, type KeyedFloatRefRecord, type KeyedFloatValidation, validateKeyedFloats };