explico 0.12.0 → 0.13.1

package/src/reference/base-abbreviations.mjs

@@ -11,8 +11,8 @@
  * `content/abbreviations/*.md` table, not here. This baseline only holds
  * abbreviations so common in ordinary English/academic writing that spelling
  * them out on every course would be noise, not help. A course adds a real
- * one via `abbreviations.allow` in `course.config.ts`, the same shape as
- * `operators.allow` / `romanLabels.allow`.
+ * one via `rules.N14.allow` in its course config, the same shape as
+ * `rules.N8.allow` / `rules.N10.allow`.
  */
 export const BASE_ABBREVIATIONS = Object.freeze(
   new Set([

package/src/reference/base-operators.mjs

@@ -21,8 +21,8 @@
  *
  * A domain operator (`Var`, `Cov`, `Corr`, `sgn`, `erf`, `Tr`, `argmax`, …) is
  * written `\operatorname{…}` and is NOT here: it earns a card, a
- * `notation.local` entry, or an explicit line in `course.config.ts`
- * (`operators.allow`).
+ * `notation.local` entry, or an explicit line in the course config
+ * (`rules.N8.allow`).
  *
  * Entries are the KaTeX command without its backslash (`exp`, not `\exp`) for
  * `op` nodes, and the verbatim body for `\operatorname{…}` nodes (`Var`).

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

@@ -15,9 +15,10 @@
  * always a course-specific named quantity (`KE`, `PV`, `Var`-as-a-label) that
  * genuinely benefits from a hover card, so the shipped baseline holds only
  * the qualifiers that function like an operator's extremum subscript
- * (`x_{\mathrm{opt}}`) rather than naming a quantity of their own. A course
- * adds a real one via `romanLabels.allow` in `course.config.ts`, the same
- * shape as `operators.allow`.
+ * (`x_{\mathrm{opt}}`) rather than naming a quantity of their own. That
+ * clears rule N10 only: the indexed symbol still needs a card (rule N23).
+ * A course adds a real one via `rules.N10.allow` in its course config, the
+ * same shape as `rules.N8.allow`.
  */
 export const BASE_ROMAN_LABELS = Object.freeze(new Set(['opt']));
 

package/src/reference/citation-format.mjs

@@ -131,3 +131,77 @@ export function formatSourceLabel(record) {
     .filter(Boolean)
     .join(', ');
 }
+
+/**
+ * One `[@…]` bracket: `[@id]`, `[@id; locator]`, or several citations as
+ * Pandoc writes them, `[@a; @b; p. 7]`. Group 1 is the first id, group 2 the
+ * rest after the first `;`, read by {@link bracketCitations}.
+ */
+export const CITATION_BRACKET = /\[@([a-z0-9][a-z0-9.-]*)(?:;[ \t\r\n]*([^\]]*))?\]/g;
+
+/**
+ * The citations one bracket holds, in order, as `{ id, locator }`. A
+ * `;`-separated part that is only `@id` starts another citation (Pandoc's
+ * `[@a; @b]`); any other part belongs to the locator of the citation before
+ * it, so a locator may itself contain `;` (`[@a; §1.2; eq. 3]`).
+ *
+ * @param {string} firstId
+ * @param {string | undefined} rest
+ * @returns {{ id: string, locator: string }[]}
+ */
+export function bracketCitations(firstId, rest) {
+  const citations = [{ id: String(firstId).trim(), parts: [] }];
+  for (const part of String(rest ?? '').split(';')) {
+    const next = /^\s*@([a-z0-9][a-z0-9.-]*)\s*$/.exec(part);
+    if (next) citations.push({ id: next[1], parts: [] });
+    else if (part.trim()) citations[citations.length - 1].parts.push(part);
+  }
+  return citations.map(({ id, parts }) => ({
+    id,
+    locator: parts.join(';').replace(/\s+/g, ' ').trim(),
+  }));
+}
+
+/** Every source id a text cites, `[@a; @b]` included. */
+export function citedIds(text) {
+  const ids = new Set();
+  for (const match of String(text).matchAll(CITATION_BRACKET)) {
+    for (const { id } of bracketCitations(match[1] ?? '', match[2])) ids.add(id);
+  }
+  return ids;
+}
+
+/**
+ * A Markdown link whose text holds a citation, `[as measured in [@id]](url)`:
+ * remark-citation leaves link text alone (a link cannot hold the marker's
+ * link), so the citation would print as typed. Group 1 is the link text.
+ */
+const LINK_WITH_CITATION = /\[((?:[^[\]\n]|\[[^[\]\n]*\])*?\[@[^\]\n]*\](?:[^[\]\n]|\[[^[\]\n]*\])*)\]\(/g;
+
+/**
+ * Each citation written inside a link's text, as `{ index, text }`: the
+ * offset of its `[@` in `text`, and the citation as written.
+ */
+export function citationsInLinks(text) {
+  const found = [];
+  for (const link of String(text).matchAll(LINK_WITH_CITATION)) {
+    const start = (link.index ?? 0) + 1;
+    for (const citation of (link[1] ?? '').matchAll(/\[@[^\]\n]*\]/g)) {
+      found.push({ index: start + (citation.index ?? 0), text: citation[0] });
+    }
+  }
+  return found;
+}
+
+/**
+ * `text` with every citation inside a link's text blanked, offsets kept: what
+ * the page cites, for a scan that counts a lesson's sources.
+ */
+export function withoutLinkCitations(text) {
+  let out = String(text);
+  for (const { index, text: citation } of citationsInLinks(out)) {
+    out = out.slice(0, index) + citation.replace(/[^\n]/g, ' ') + out.slice(index + citation.length);
+  }
+  return out;
+}
+

package/src/reference/consistency.ts

@@ -12,9 +12,7 @@
  *   (a) glyph-unique-in-corpus       one rendered glyph → one meaning corpus-wide
  *   (b) notation-units / units-vocab  every entry has units or `dimensionless`,
  *                                     unit strings drawn from a controlled vocab
- *   (c) convention-single-definition  a sign / cash-flow-perspective convention a
- *                                     lesson uses resolves to one declaration
- *   (f) weak-local                   a `notation.local` symbol used only in its
+ *   (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
  *   (h) operator-explained           a named operator a lesson uses is on the
@@ -39,18 +37,17 @@
 
 import type {
   CourseAccents,
-  CourseConventions,
   CourseOperators,
   CourseRomanLabels,
 } from '../compiler/course-config';
-import type { CurriculumCatalog } from '../curriculum/validation';
 import type { NotationSpec } from '../compiler/collections';
 import type { LintIgnore } from './lint-ignore';
 import { effectiveAccentAllowlist } from './base-accents.mjs';
 import { effectiveOperatorAllowlist } from './base-operators.mjs';
 import { effectiveRomanLabelAllowlist } from './base-roman-labels.mjs';
 import { stripEquationLabels } from './equations.mjs';
-import { pageScope } from './gate-math';
+import { pageScope, scopeEntry, type ScopeEntry } from './gate-math';
+import { isIndexEntryLatex } from '../compiler/content-schemas';
 import {
   collectDecorations,
   collectOperators,
@@ -65,12 +62,12 @@ import type {
   NotationRegistry,
   NotationRegistryInput,
 } from './types';
+import { blankPropStrings } from './gate-prop-text';
 
 export type ConsistencyCode =
   | 'glyph-unique-in-corpus'
   | 'notation-units'
   | 'units-vocab'
-  | 'convention-single-definition'
   | 'weak-local'
   | 'notation-source-locator'
   | 'gloss-wants-promoting'
@@ -79,6 +76,7 @@ export type ConsistencyCode =
   | 'operator-explained'
   | 'roman-label-explained'
   | 'accent-explained'
+  | 'accent-swallowed'
   | 'operator-suspended'
   | 'operator-suspension-reason'
   | 'operator-shadowed';
@@ -100,10 +98,7 @@ export interface ConsistencyInput {
   readonly registry: NotationRegistry;
   readonly notationInput: NotationRegistryInput;
   readonly specs: readonly NotationSpec[];
-  readonly catalog: CurriculumCatalog;
   readonly lintIgnore: LintIgnore;
-  /** Convention keys this course anchors on (from `content/course.config.ts`). */
-  readonly conventions: CourseConventions;
   /** This course's edits to the named-operator baseline (rule N8). */
   readonly operators?: CourseOperators;
   /** This course's edits to the roman-label baseline (rule N10). */
@@ -112,9 +107,6 @@ export interface ConsistencyInput {
   readonly accents?: CourseAccents;
 }
 
-const CONVENTION_RE =
-  /\bsign convention\b|\bcash-flow perspective\b|\bholder(?:'s)?(?:\s+\w+){0,2}\s+perspective\b|\bfrom (?:a|one|the|its)(?:\s+\w+){0,3}\s+perspective\b|\breverses? every sign\b|\bpositive (?:means|amounts?)\b/i;
-
 // --- shared text helpers ------------------------------------------------
 
 function stripCode(text: string): string {
@@ -128,13 +120,14 @@ interface MathSpan {
 }
 
 /**
- * Every `$$…$$` then `$…$` span in `body`, outside code. A `\label{eq:…}`
+ * Every `$$…$$` then `$…$` span in `body`, outside code and quoted JSX props
+ * (plain text; invariant `prop-text`). A `\label{eq:…}`
  * (D7) is stripped: it is an identity marker KaTeX cannot parse, and the
  * scans below treat an unparseable span as having nothing in it — so left in,
  * every labelled display equation was invisible to rules N8, N10 and N22.
  */
 function mathSpans(body: string): MathSpan[] {
-  const searchable = stripCode(body);
+  const searchable = stripCode(blankPropStrings(body));
   const spans: MathSpan[] = [];
   for (const match of searchable.matchAll(/\$\$([\s\S]+?)\$\$/g)) {
     spans.push({ latex: stripEquationLabels(match[1] ?? '') });
@@ -217,6 +210,9 @@ function checkNotationUnits(
   out: ConsistencyDiagnostic[],
 ): void {
   for (const spec of input.specs) {
+    // An index entry (`{}_0`, rule N23) names a subscript, which has no
+    // unit; its derived cards take the indexed symbol's.
+    if (isIndexEntryLatex(spec.latex)) continue;
     if (spec.units === undefined && !spec.dimensionless) {
       if (input.lintIgnore.matches('notation-units', spec.key)) continue;
       out.push({
@@ -244,42 +240,6 @@ function checkNotationUnits(
   }
 }
 
-function checkConventionSingleDefinition(
-  input: ConsistencyInput,
-  out: ConsistencyDiagnostic[],
-): void {
-  const lessonById = new Map(
-    input.catalog.lessons.map((lesson) => [lesson.id, lesson]),
-  );
-  for (const lesson of input.notationInput.lessons) {
-    const body = lesson.body;
-    if (!CONVENTION_RE.test(body)) continue;
-    const meta = lessonById.get(lesson.lessonId);
-    const { signConventionKey, cashFlowPerspectiveCompetency } =
-      input.conventions;
-    const anchoredByCompetency = [
-      ...(meta?.teaches ?? []),
-      ...(meta?.requires ?? []),
-    ].includes(cashFlowPerspectiveCompetency);
-    const anchoredByTerm = new RegExp(
-      `\\[\\[\\s*${signConventionKey}\\s*\\]\\]`,
-    ).test(body);
-    if (anchoredByCompetency || anchoredByTerm) continue;
-    if (
-      input.lintIgnore.matches('convention-single-definition', lesson.lessonId)
-    ) {
-      continue;
-    }
-    out.push({
-      code: 'convention-single-definition',
-      severity: 'warning',
-      lessonId: lesson.lessonId,
-      file: lesson.source.file,
-      message: `${lesson.lessonId} states a sign / cash-flow-perspective convention in prose but does not resolve it to a single declaration ([[${signConventionKey}]] or ${cashFlowPerspectiveCompetency})`,
-    });
-  }
-}
-
 function checkWeakLocal(
   input: ConsistencyInput,
   out: ConsistencyDiagnostic[],
@@ -471,7 +431,7 @@ function checkGlossNameShape(
 
 /**
  * A named operator a lesson uses is either universal — on the shipped
- * `BASE_OPERATORS` baseline plus this course's `operators.allow`, minus its
+ * `BASE_OPERATORS` baseline plus this course's `rules.N8.allow`, minus its
  * `operators.deny` — or it is explained: a notation card or `notation.local`
  * entry the lesson binds with `[[key]]` whose `latex` is that operator, so the
  * reader can hover it. Anything else (`\operatorname{Var}` with no entry, or a
@@ -530,7 +490,7 @@ function checkOperatorExplained(
           lessonId: lesson.lessonId,
           file: lesson.source.file,
           glyph: operator.name,
-          message: `${lesson.lessonId}: operator ${JSON.stringify(display)} is neither on the course operator allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(display)}) introduced with [[key]], or add ${JSON.stringify(operator.name)} to operators.allow in course.config.ts`,
+          message: `${lesson.lessonId}: operator ${JSON.stringify(display)} is neither on the course operator allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(display)}) introduced with [[key]], or add ${JSON.stringify(operator.name)} to rules.N8.allow in the course config (course.config.ts, or the course.settings.json it reads)`,
         });
       }
     }
@@ -590,20 +550,18 @@ function checkRomanLabelExplained(
           lessonId: lesson.lessonId,
           file: lesson.source.file,
           glyph: label.name,
-          message: `${lesson.lessonId}: roman label ${JSON.stringify(`\\mathrm{${label.name}}`)} is neither on the course roman-label allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(`\\mathrm{${label.name}}`)}) introduced with [[key]], or add ${JSON.stringify(label.name)} to romanLabels.allow in course.config.ts`,
+          message: `${lesson.lessonId}: roman label ${JSON.stringify(`\\mathrm{${label.name}}`)} is neither on the course roman-label allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(`\\mathrm{${label.name}}`)}) introduced with [[key]], or add ${JSON.stringify(label.name)} to rules.N10.allow in the course config (course.config.ts, or the course.settings.json it reads)`,
         });
       }
     }
   }
 }
 
-function sharedScopeByKey(
-  input: ConsistencyInput,
-): Map<string, { key: string; notation: string }> {
+function sharedScopeByKey(input: ConsistencyInput): Map<string, ScopeEntry> {
   return new Map(
     input.notationInput.sharedDefinitions.map((definition) => [
       definition.key,
-      { key: definition.key, notation: definition.notation },
+      scopeEntry(definition),
     ]),
   );
 }
@@ -633,11 +591,40 @@ function checkAccentExplained(
     for (const span of mathSpans(lesson.body)) {
       let decorations;
       try {
-        ({ decorations } = resolveMathGlyphs(span.latex, scope, { suspended }));
+        ({ decorations } = resolveMathGlyphs(span.latex, scope, {
+          suspended,
+          derive: true,
+        }));
       } catch {
         continue;
       }
       for (const decoration of decorations) {
+        // An author's `\explain{key}{\hat{\beta}}` counts as the whole form
+        // only when `key`'s own `latex` carries the decoration: the `beta`
+        // card says nothing about a hat (the twin of rule N23's
+        // `index-swallowed`).
+        if (decoration.wholeForm !== null && decoration.wholeFormExplicit) {
+          const notation =
+            scope.find((entry) => entry.key === decoration.wholeForm)?.notation ?? '';
+          const carries = collectDecorations(notation).some(
+            (item) => item.name === decoration.name,
+          );
+          const id = `swallowed:${decoration.token}`;
+          if (!carries && !reported.has(id)) {
+            reported.add(id);
+            if (!input.lintIgnore.matches('accent-swallowed', decoration.name)) {
+              out.push({
+                code: 'accent-swallowed',
+                severity: 'warning',
+                lessonId: lesson.lessonId,
+                file: lesson.source.file,
+                glyph: decoration.name,
+                message: `${lesson.lessonId}: \\explain{${decoration.wholeForm}}{${decoration.token}} wraps the decoration ${JSON.stringify(decoration.name)} in ${decoration.wholeForm}, whose latex (${notation}) has none, so its card cannot explain it; wrap only the symbol under it and give the decoration an operator entry (latex ${JSON.stringify(operatorEntryLatex(decoration.name))}), or name an entry for the decorated form (latex ${JSON.stringify(decoration.token)})`,
+              });
+            }
+          }
+          continue;
+        }
         if (decoration.wholeForm !== null || decoration.operator !== null) continue;
         // A suspended decoration never composes; the gate fails it instead.
         if (suspended.includes(decoration.name)) continue;
@@ -737,7 +724,6 @@ const CHECKS: ((
 ) => void)[] = [
   checkGlyphUniqueness,
   checkNotationUnits,
-  checkConventionSingleDefinition,
   checkWeakLocal,
   checkNotationSourceLocator,
   checkGlossWantsPromoting,
@@ -777,7 +763,6 @@ export function consistencyCounts(
     'glyph-unique-in-corpus': 0,
     'notation-units': 0,
     'units-vocab': 0,
-    'convention-single-definition': 0,
     'weak-local': 0,
     'notation-source-locator': 0,
     'gloss-wants-promoting': 0,
@@ -786,6 +771,7 @@ export function consistencyCounts(
     'operator-explained': 0,
     'roman-label-explained': 0,
     'accent-explained': 0,
+    'accent-swallowed': 0,
     'operator-suspended': 0,
     'operator-suspension-reason': 0,
     'operator-shadowed': 0,

package/src/reference/curriculum-alignment.ts

@@ -6,24 +6,16 @@ import type {
   NotationRegistry,
 } from './types';
 
-interface EditorialCompetency {
-  readonly id: string;
-  readonly editorialStatus?: 'draft' | 'in-review' | 'reviewed';
-}
-
 export function validateNotationAlignment(
   registry: NotationRegistry,
   catalog: CurriculumCatalog,
 ): readonly NotationDiagnostic[] {
   const diagnostics: NotationDiagnostic[] = [];
   const competencies = new Map(
-    (catalog.competencies as readonly EditorialCompetency[]).map((entry) => [
-      entry.id,
-      entry,
-    ]),
+    catalog.competencies.map((entry) => [entry.id, entry]),
   );
   const lessons = new Map(catalog.lessons.map((entry) => [entry.id, entry]));
-  const sources = new Map(catalog.sources.map((entry) => [entry.id, entry]));
+  const sources = new Set(catalog.sources.map((entry) => entry.id));
   const trackPositions = buildTrackPositions(catalog, diagnostics);
 
   for (const definition of registry.definitions) {
@@ -82,20 +74,6 @@ export function validateNotationAlignment(
       trackPositions,
       diagnostics,
     );
-
-    if (
-      definition.status === 'reviewed' &&
-      (lesson.status !== 'reviewed' ||
-        competency?.editorialStatus !== 'reviewed')
-    ) {
-      diagnostics.push(
-        error(
-          'alignment-review-state',
-          `${definition.id} is reviewed while its owning lesson or competency is not reviewed`,
-          definition,
-        ),
-      );
-    }
   }
 
   return diagnostics.sort(compareDiagnostics);
@@ -177,15 +155,11 @@ function validateIntroductionOrder(
 
 function validateSources(
   definition: NotationDefinitionRecord,
-  sources: ReadonlyMap<
-    string,
-    { readonly editorialStatus: 'draft' | 'in-review' | 'reviewed' }
-  >,
+  sources: ReadonlySet<string>,
   diagnostics: NotationDiagnostic[],
 ): void {
   for (const sourceId of definition.sources) {
-    const source = sources.get(sourceId);
-    if (!source) {
+    if (!sources.has(sourceId)) {
       diagnostics.push(
         error(
           'alignment-unavailable',
@@ -193,17 +167,6 @@ function validateSources(
           definition,
         ),
       );
-    } else if (
-      definition.status === 'reviewed' &&
-      source.editorialStatus !== 'reviewed'
-    ) {
-      diagnostics.push(
-        error(
-          'alignment-review-state',
-          `${definition.id} is reviewed while source ${sourceId} is ${source.editorialStatus}`,
-          definition,
-        ),
-      );
     }
   }
 }

package/src/reference/derived-entries.ts

@@ -0,0 +1,68 @@
+/**
+ * Derived cards (rule N23) as the page payload carries them: each derived
+ * card a page's math uses, composed from its base and index entries by
+ * `derived-notation.mjs`, with the glyph table its formula resolves against.
+ * The manifest builds the ones lesson-body and assessment math use; the page
+ * payload (`page-notation.ts`) builds the ones a lab or a diagram registers
+ * while it renders, the same way.
+ */
+import type { ManifestDerivedNotation } from '../compiler/manifest';
+import { composeDerivedEntry } from './derived-notation.mjs';
+import { scopeEntry } from './gate-math';
+import { formulaExplainKeys, type GlyphScopeEntry } from './gloss';
+import { baseSymbolLatex, derivedNotationLatex } from './math-glyphs.mjs';
+import type { DerivedUse, NotationDefinitionRecord } from './types';
+
+/**
+ * The derived cards for `uses`, sorted by key. `records` holds the page's
+ * entries by key, local ones winning; a use whose base or index entry is not
+ * there is skipped. A card's formula resolves against the derived symbol,
+ * the index entry's glosses, the base, and the cards the formula names.
+ */
+export function derivedNotationEntries(
+  uses: readonly DerivedUse[],
+  records: ReadonlyMap<string, NotationDefinitionRecord>,
+  cardsByKey: ReadonlyMap<string, GlyphScopeEntry>,
+): ManifestDerivedNotation[] {
+  const derived = new Map<string, ManifestDerivedNotation>();
+  for (const use of uses) {
+    if (derived.has(use.key)) continue;
+    const base = records.get(use.base);
+    const index = records.get(use.index);
+    if (!base || !index) continue;
+    const notation = derivedNotationLatex(base.notation, index.notation);
+    const entry = composeDerivedEntry({
+      key: use.key,
+      notation,
+      baseLatex: baseSymbolLatex(base.notation),
+      base,
+      index: {
+        ...index,
+        ...(index.formulaTemplate === undefined ? {} : { formula: index.formulaTemplate }),
+      },
+    });
+    const formulaScope: GlyphScopeEntry[] = [
+      { key: use.key, notation },
+      ...index.glosses.map((gloss) => ({ key: gloss.key, notation: gloss.notation })),
+      scopeEntry(base),
+    ];
+    for (const key of formulaExplainKeys(entry.formula ?? '')) {
+      if (formulaScope.some((row) => row.key === key)) continue;
+      const card = records.get(key) ?? cardsByKey.get(key);
+      if (card) formulaScope.push(scopeEntry(card));
+    }
+    derived.set(use.key, {
+      key: entry.key,
+      base: entry.base,
+      index: entry.index,
+      notation: entry.notation,
+      label: entry.label,
+      summary: entry.summary,
+      glosses: [...index.glosses],
+      formulaScope,
+      ...(entry.units === undefined ? {} : { units: entry.units }),
+      ...(entry.formula === undefined ? {} : { formula: entry.formula }),
+    });
+  }
+  return [...derived.values()].sort((left, right) => left.key.localeCompare(right.key));
+}

package/src/reference/derived-notation.mjs

@@ -0,0 +1,121 @@
+/**
+ * Derived notation entries (rule N23): the card for a symbol with a subscript
+ * that an **index entry** explains — `\mathbf{v}_0` from the base entry
+ * `velocity-vector` (`\mathbf{v}`) and the index entry `motion.initial`
+ * (`{}_0`, "Initial value").
+ *
+ * The resolver writes one `\explain` around the whole indexed symbol, with
+ * the key `derivedNotationKey(base, index)` (`math-glyphs.mjs`); the build
+ * materializes the entry from the two, here, so that everything downstream
+ * treats it as one more card. What the reader sees first is about the
+ * indexed symbol; the base's own card is one level deeper, through the base
+ * symbol on the card's formula line:
+ *
+ * | Field   | From                                        |
+ * | ------- | ------------------------------------------- |
+ * | symbol  | the base's symbol plus the index            |
+ * | title   | the index entry's `reads`, the base's label |
+ * | summary | the index entry's `meaning`, never the base's |
+ * | formula | the index entry's `formula`, `{base}` bound |
+ * | units   | the base entry                              |
+ *
+ * Plain JavaScript with no parser, so the remark pass and the manifest share
+ * it; `derivedNotationLatex` in `math-glyphs.mjs` builds the symbol.
+ */
+
+/** The indexed symbol, in an index entry's `reads` and `formula`. */
+export const BASE_PLACEHOLDER = '{base}';
+
+/**
+ * A label as it reads inside a sentence: its first letter lowercased unless
+ * the first word is an acronym (`OLS estimate`) — the same rule
+ * `composeHeaderLabel` applies to an operator's operand.
+ *
+ * @param {string} label
+ * @returns {string}
+ */
+export function inSentence(label) {
+  const [first = ''] = label.split(/\s+/u);
+  if (first.length > 1 && first === first.toUpperCase()) return label;
+  return label.charAt(0).toLowerCase() + label.slice(1);
+}
+
+/**
+ * A derived card's title: the index entry's `reads` with `{base}` replaced by
+ * the base's label (lowercased in mid-sentence), or `"<index label> of
+ * <base label>"` when the index entry gives no `reads`.
+ *
+ * @param {{ label: string, reads?: string }} index
+ * @param {string} baseLabel
+ * @returns {string}
+ */
+export function derivedLabel(index, baseLabel) {
+  const reads = index.reads ?? `${index.label} of ${BASE_PLACEHOLDER}`;
+  const at = reads.indexOf(BASE_PLACEHOLDER);
+  const filled = reads
+    .split(BASE_PLACEHOLDER)
+    .join(at === 0 ? baseLabel : inSentence(baseLabel));
+  // `{base}` first in a later position, or a `reads` that starts lowercase.
+  return filled.charAt(0).toUpperCase() + filled.slice(1);
+}
+
+/**
+ * An index entry's formula with `{base}` bound: to the base symbol under its
+ * own `\explain`, for a derived card, so the reader opens the base's card
+ * from it.
+ *
+ * @param {string} formula
+ * @param {string} baseKey
+ * @param {string} baseLatex
+ * @returns {string}
+ */
+export function derivedFormula(formula, baseKey, baseLatex) {
+  return formula.split(BASE_PLACEHOLDER).join(`\\explain{${baseKey}}{${baseLatex}}`);
+}
+
+/**
+ * An index entry's own formula, shown on the index entry's card and checked
+ * by the formula gate: `{base}` becomes a placeholder square bound to the
+ * entry itself, as an operator entry is shown over a square.
+ *
+ * @param {string} formula
+ * @param {string} ownKey
+ * @returns {string}
+ */
+export function indexEntryFormula(formula, ownKey) {
+  return formula.split(BASE_PLACEHOLDER).join(`\\explain{${ownKey}}{\\square}`);
+}
+
+/**
+ * @typedef {object} DerivedSource
+ * @property {string} key
+ * @property {string} notation
+ * @property {string} label
+ * @property {string} [summary]
+ * @property {string} [units]
+ * @property {string} [reads]
+ * @property {string} [formula]
+ * @property {readonly { key: string, notation: string, label: string, units?: string, ownerKey: string }[]} [glosses]
+ */
+
+/**
+ * The derived entry for one (base, index) pair. `notation` is the indexed
+ * symbol, from `derivedNotationLatex`.
+ *
+ * @param {{ key: string, notation: string, baseLatex: string, base: DerivedSource, index: DerivedSource }} input
+ */
+export function composeDerivedEntry({ key, notation, baseLatex, base, index }) {
+  return {
+    key,
+    notation,
+    base: base.key,
+    index: index.key,
+    label: derivedLabel(index, base.label),
+    summary: index.summary ?? '',
+    glosses: [...(index.glosses ?? [])],
+    ...(base.units === undefined ? {} : { units: base.units }),
+    ...(index.formula === undefined
+      ? {}
+      : { formula: derivedFormula(index.formula, base.key, baseLatex) }),
+  };
+}