@crossworks/content-core 0.230.43

package/src/formula-dimensions.ts

@@ -0,0 +1,231 @@
+/**
+ * Dimensional analysis for a FormulaSpec — the reason mathjs is in this repo.
+ *
+ * Until now `unit` was a string carried for display. This turns it into a
+ * constraint: evaluate each expression with unit-bearing quantities and check
+ * the result's dimension against the declared one. A dropped term inside a
+ * `sqrt`, a mislabelled constant, a gauge/absolute mix-up — all change the
+ * result's dimension, and all are otherwise invisible until someone
+ * recomputes by hand.
+ *
+ * The motivating case is real: `g_c` was recorded as `ft/s2` when it is the
+ * gravitational conversion constant `lbm ft/(lbf s^2)`. Numerically identical
+ * in USC, so every test passed and every number was right — and any SI port
+ * would have been silently out by a factor of 3.13. This check rejects it.
+ *
+ * Reported SEPARATELY from `parseFormulaSpec`, like `checkLookupCoverage`:
+ * units are optional, older specs carry prose, and an unlabelled spec is
+ * incomplete rather than invalid.
+ */
+import { create, all, type FactoryFunctionMap, type MathJsInstance } from 'mathjs';
+import type { FormulaSpec, SpecVariable } from './formula-spec';
+
+const ALL_FACTORIES = all as FactoryFunctionMap;
+
+let instance: {
+  math: MathJsInstance;
+  compile: (e: string) => { evaluate: (s: Record<string, unknown>) => unknown };
+} | null = null;
+
+function engine() {
+  if (!instance) {
+    const math = create(ALL_FACTORIES, { predictable: false });
+    // The uppercase vocabulary, bound to mathjs's OWN unit-aware functions.
+    // Deliberately not the same implementations as the table engine, which
+    // uses Math.sqrt so that an out-of-domain input yields NaN and renders a
+    // blank cell. Here `sqrt` must understand units — sqrt(lb^2/s^2) is lb/s,
+    // and that is the whole point.
+    math.import(
+      {
+        SQRT: math.sqrt,
+        ABS: math.abs,
+        MIN: math.min,
+        MAX: math.max,
+        SUM: math.add,
+        ROUND: (x: unknown) => x, // rounding cannot change a dimension
+        FLOOR: (x: unknown) => x,
+        CEIL: (x: unknown) => x,
+        POW: math.pow,
+        LN: math.log,
+        LOG10: math.log10,
+        EXP: math.exp,
+        IF: (_c: unknown, a: unknown) => a, // both branches must share a dimension
+        PI: Math.PI,
+        E: Math.E,
+      },
+      { override: true },
+    );
+    const compile = math.compile.bind(math) as (e: string) => {
+      evaluate: (s: Record<string, unknown>) => unknown;
+    };
+    instance = { math, compile };
+  }
+  return instance;
+}
+
+/**
+ * Normalise a human-written unit into something mathjs parses.
+ *
+ * Specs are transcribed from printed tables, where units are written for
+ * people: `lbm-ft/(lbf-s2)`, `lb/ft3`, `lbf/in2 (abs)`. Rejecting those would
+ * mean retyping every spec in mathjs syntax, so the common conventions are
+ * translated instead — hyphen-as-multiply, implicit exponents, and the
+ * parenthetical qualifiers (abs/g/gauge) that carry a pressure BASIS rather
+ * than a dimension.
+ */
+export function normaliseUnit(raw: string): string | null {
+  let u = raw.trim();
+  if (!u) return null;
+  // Drop trailing qualifiers: "lbf/in2 (abs)" → "lbf/in2". The basis matters
+  // enormously (see the gauge/absolute finding) but it is not a dimension, so
+  // it cannot be expressed here — that is what two distinct symbols are for.
+  u = u.replace(/\s*\((?:abs|absolute|g|gauge|a)\)\s*$/i, '').trim();
+  if (!u || u === '-' || /^unitless$/i.test(u)) return null;
+  // Hyphen between unit tokens means multiply: "lbm-ft" → "lbm ft".
+  u = u.replace(/(?<=[A-Za-z0-9)])-(?=[A-Za-z])/g, ' ');
+  // Implicit exponent: "ft3" → "ft^3", "in2" → "in^2", "s2" → "s^2".
+  u = u.replace(/([A-Za-z])(\d+)(?![\d^])/g, '$1^$2');
+  // Common spellings mathjs does not use.
+  u = u.replace(/\bsec\b/g, 's').replace(/\bmol\b/g, 'mol');
+  // Rankine is `degR`; a bare "R" would parse as roentgen.
+  u = u.replace(/^°?R$/, 'degR').replace(/·/g, ' ');
+  return u;
+}
+
+/** A quantity of 1 in the given unit, or null if it isn't parseable. */
+function unitQuantity(math: MathJsInstance, raw: string | null | undefined): unknown | null {
+  if (!raw) return null;
+  const norm = normaliseUnit(raw);
+  if (!norm) return null;
+  try {
+    return math.evaluate(`1 ${norm}`);
+  } catch {
+    return null;
+  }
+}
+
+export interface DimensionIssue {
+  /** Expression (or derived-variable) id the problem belongs to. */
+  id: string;
+  kind: 'mismatch' | 'unparseable-unit' | 'inconsistent';
+  declared: string | null;
+  actual: string | null;
+  detail: string;
+}
+
+function refsOf(src: string): string[] {
+  const out: string[] = [];
+  for (const m of src.matchAll(/\{([^}]*)\}/g)) {
+    const name = (m[1] ?? '').trim();
+    if (name && !out.includes(name)) out.push(name);
+  }
+  return out;
+}
+
+/**
+ * Check every expression that declares a result unit. Returns one issue per
+ * problem; an empty array means every declared unit is consistent with the
+ * arithmetic that produces it.
+ */
+export function checkDimensions(spec: FormulaSpec): DimensionIssue[] {
+  const issues: DimensionIssue[] = [];
+  const { math, compile } = engine();
+  const bySymbol = new Map<string, SpecVariable>();
+  for (const v of spec.variables) bySymbol.set(v.symbol, v);
+
+  // Surface a unit we cannot read ONCE per variable, rather than as a cascade
+  // of confusing mismatches downstream.
+  for (const v of spec.variables) {
+    if (!v.unit) continue;
+    const norm = normaliseUnit(v.unit);
+    if (norm && unitQuantity(math, v.unit) === null) {
+      issues.push({
+        id: v.symbol,
+        kind: 'unparseable-unit',
+        declared: v.unit,
+        actual: null,
+        detail: `could not interpret the unit '${v.unit}' (read as '${norm}') — dimensional checking skipped for anything using it`,
+      });
+    }
+  }
+
+  for (const expr of spec.expressions) {
+    if (!expr.unit) continue;
+    const expected = unitQuantity(math, expr.unit);
+    if (expected === null) {
+      issues.push({
+        id: expr.id,
+        kind: 'unparseable-unit',
+        declared: expr.unit,
+        actual: null,
+        detail: `could not interpret the declared result unit '${expr.unit}'`,
+      });
+      continue;
+    }
+
+    // Bind each reference to 1-of-its-unit. Magnitudes are irrelevant — only
+    // dimensions are under test — but a variable with no unit binds as a plain
+    // 1 so a partially-annotated spec still checks what it can.
+    const scope: Record<string, unknown> = {};
+    let code = expr.expression;
+    let skip = false;
+    refsOf(expr.expression).forEach((name, i) => {
+      const variable = bySymbol.get(name);
+      const q = unitQuantity(math, variable?.unit ?? null);
+      if (variable?.unit && q === null) skip = true;
+      scope[`__d${i}`] = q ?? 1;
+      code = code.split(`{${name}}`).join(`__d${i}`);
+    });
+    if (skip) continue; // already reported as unparseable above
+
+    let actual: unknown;
+    try {
+      actual = compile(code).evaluate(scope);
+    } catch (err) {
+      issues.push({
+        id: expr.id,
+        kind: 'inconsistent',
+        declared: expr.unit,
+        actual: null,
+        detail: `the expression is not dimensionally consistent: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      });
+      continue;
+    }
+
+    // `equalBase` is the real test: same dimension, regardless of magnitude or
+    // prefix. Comparing formatted strings would reject ft vs in.
+    try {
+      const a = actual as { equalBase?: (o: unknown) => boolean; toString: () => string };
+      const same =
+        typeof a?.equalBase === 'function'
+          ? a.equalBase(expected)
+          : // A dimensionless result vs a declared unit: only equal if the
+            // declared unit is itself dimensionless.
+            typeof actual === 'number' &&
+            typeof (expected as { equalBase?: unknown }).equalBase !== 'function';
+      if (!same) {
+        issues.push({
+          id: expr.id,
+          kind: 'mismatch',
+          declared: expr.unit,
+          actual: typeof actual === 'number' ? 'dimensionless' : String(a?.toString?.() ?? actual),
+          detail: `declares '${expr.unit}' but the arithmetic produces ${
+            typeof actual === 'number' ? 'a dimensionless value' : `'${a.toString()}'`
+          } — a term is missing, or a variable's unit is wrong`,
+        });
+      }
+    } catch (err) {
+      issues.push({
+        id: expr.id,
+        kind: 'inconsistent',
+        declared: expr.unit,
+        actual: null,
+        detail: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return issues;
+}

package/src/formula-eval.ts

@@ -0,0 +1,294 @@
+/**
+ * Evaluator for a FormulaSpec. Pure — no I/O, no DB, no clock.
+ *
+ * Two behaviours that deliberately differ from table formula columns:
+ *
+ * 1. IT FAILS LOUD. `evalFormula` returns null on any problem, which is right
+ *    for a spreadsheet cell: a broken formula renders blank and the user moves
+ *    on. It is wrong here. A blank release rate on a risk assessment looks like
+ *    a small number, and an unresolved symbol silently reading as zero is how a
+ *    calculation gets quietly wrong for a year. Every failure returns an
+ *    explicit error instead.
+ *
+ * 2. SYMBOLS ARE CASE-SENSITIVE. Table columns match case-insensitively, which
+ *    is friendly for `{qty}` vs `{Qty}`. Engineering notation does not have
+ *    that luxury — in the vapour equations `k` is the specific heat ratio and
+ *    `K` is a correction factor. A near-miss must be an error, not a guess.
+ *
+ * Every evaluation returns a trace: which branch was taken, which lookup row
+ * matched, what each symbol resolved to. An engineering number that cannot be
+ * explained is not worth much, and the trace is what lets a result be shown
+ * with its derivation rather than asserted.
+ */
+import { evalExpression, truthy, type EvalValue, type RefResolver } from './table-formula';
+import type { FormulaSpec, FormulaValue, SpecLookup } from './formula-spec';
+
+export type TraceStep =
+  | {
+      kind: 'symbol';
+      symbol: string;
+      value: FormulaValue;
+      from: 'input' | 'constant' | 'default' | 'derived' | 'produced';
+      expression?: string;
+    }
+  | { kind: 'expression'; id: string; expression: string; value: FormulaValue; equation?: string }
+  | { kind: 'branch'; id: string; when: string; chose: string; label?: string }
+  | {
+      kind: 'lookup';
+      id: string;
+      key: Record<string, FormulaValue>;
+      value: FormulaValue;
+      row?: Record<string, FormulaValue>;
+    };
+
+export type EvalResult =
+  | { ok: true; value: FormulaValue; trace: TraceStep[] }
+  | { ok: false; error: string; trace: TraceStep[] };
+
+class SpecError extends Error {}
+
+class SpecEvaluator {
+  private cache = new Map<string, EvalValue>();
+  private resolving = new Set<string>();
+  private resolvingTargets = new Set<string>();
+  readonly trace: TraceStep[] = [];
+  /** resultSymbol → ids of targets declaring it, for chaining. */
+  private producers = new Map<string, string[]>();
+
+  constructor(
+    private spec: FormulaSpec,
+    private inputs: Record<string, FormulaValue>,
+  ) {
+    const claim = (symbol: string | undefined, id: string) => {
+      if (!symbol) return;
+      this.producers.set(symbol, [...(this.producers.get(symbol) ?? []), id]);
+    };
+    for (const e of spec.expressions) claim(e.resultSymbol, e.id);
+    for (const p of spec.piecewise) claim(p.resultSymbol, p.id);
+    for (const l of spec.lookups) claim(l.resultSymbol, l.id);
+  }
+
+  private resolver: RefResolver = (name) => this.resolveSymbol(name);
+
+  private resolveSymbol(symbol: string): EvalValue {
+    if (this.cache.has(symbol)) return this.cache.get(symbol)!;
+    if (this.resolving.has(symbol)) {
+      throw new SpecError(
+        `circular reference resolving '${symbol}' (via ${[...this.resolving].join(' → ')})`,
+      );
+    }
+
+    // A supplied input always wins, so a caller can override a constant or
+    // short-circuit a chain by handing in a value computed elsewhere.
+    //
+    // But an EMPTY input is not a supplied one. `Object.hasOwn` alone would
+    // treat `{"Pgauge": null}` as provided, and `toNum(null)` is 0 — so a form
+    // with a blank field, or a JSON body carrying an explicit null, produced a
+    // release rate of exactly zero reported as success. That is precisely the
+    // silent-zero failure this module exists to prevent, so null / undefined /
+    // '' are treated as absent and fall through to the missing-input error.
+    if (Object.hasOwn(this.inputs, symbol)) {
+      const supplied = this.inputs[symbol];
+      const blank = supplied === null || supplied === undefined || supplied === '';
+      if (!blank) {
+        this.cache.set(symbol, supplied);
+        this.trace.push({ kind: 'symbol', symbol, value: supplied, from: 'input' });
+        return supplied;
+      }
+    }
+
+    const variable = this.spec.variables.find((v) => v.symbol === symbol);
+    if (variable) {
+      if (variable.role === 'constant') {
+        const value = (variable.value ?? null) as EvalValue;
+        this.cache.set(symbol, value);
+        this.trace.push({ kind: 'symbol', symbol, value, from: 'constant' });
+        return value;
+      }
+      if (variable.role === 'derived') {
+        this.resolving.add(symbol);
+        try {
+          const value = evalExpression(variable.expression!, this.resolver);
+          this.cache.set(symbol, value);
+          this.trace.push({
+            kind: 'symbol',
+            symbol,
+            value: value as FormulaValue,
+            from: 'derived',
+            expression: variable.expression,
+          });
+          return value;
+        } finally {
+          this.resolving.delete(symbol);
+        }
+      }
+      if (variable.role === 'input') {
+        if (variable.value !== undefined) {
+          const value = variable.value as EvalValue;
+          this.cache.set(symbol, value);
+          this.trace.push({ kind: 'symbol', symbol, value, from: 'default' });
+          return value;
+        }
+        throw new SpecError(`missing required input '${symbol}'${unitHint(variable.unit)}`);
+      }
+      // role 'output' falls through to chaining below.
+    }
+
+    const producedBy = this.producers.get(symbol) ?? [];
+    if (producedBy.length === 1) {
+      this.resolving.add(symbol);
+      try {
+        const value = this.evalTarget(producedBy[0]!);
+        this.cache.set(symbol, value as EvalValue);
+        this.trace.push({ kind: 'symbol', symbol, value, from: 'produced' });
+        return value as EvalValue;
+      } finally {
+        this.resolving.delete(symbol);
+      }
+    }
+    if (producedBy.length > 1) {
+      throw new SpecError(
+        `'${symbol}' is produced by more than one target (${producedBy.join(', ')}); ` +
+          `supply it as an input to say which`,
+      );
+    }
+    throw new SpecError(`unknown symbol '${symbol}'`);
+  }
+
+  evalTarget(id: string): FormulaValue {
+    // Targets recurse by id (a piecewise case names another target), but
+    // `resolving` only tracks SYMBOLS — so `p1 -> p1`, or a p1/p2 pair, blew
+    // the stack and returned thousands of junk trace steps with an error that
+    // said nothing useful. Guard the id edge with the same discipline.
+    if (this.resolvingTargets.has(id)) {
+      throw new SpecError(
+        `circular reference resolving target '${id}' (via ${[...this.resolvingTargets].join(' → ')})`,
+      );
+    }
+    this.resolvingTargets.add(id);
+    try {
+      return this.evalTargetInner(id);
+    } finally {
+      this.resolvingTargets.delete(id);
+    }
+  }
+
+  private evalTargetInner(id: string): FormulaValue {
+    const expression = this.spec.expressions.find((e) => e.id === id);
+    if (expression) {
+      const value = evalExpression(expression.expression, this.resolver) as FormulaValue;
+      this.trace.push({
+        kind: 'expression',
+        id,
+        expression: expression.expression,
+        value,
+        equation: expression.equation,
+      });
+      return value;
+    }
+
+    const piecewise = this.spec.piecewise.find((p) => p.id === id);
+    if (piecewise) {
+      for (const branch of piecewise.cases) {
+        if (truthy(evalExpression(branch.when, this.resolver))) {
+          this.trace.push({
+            kind: 'branch',
+            id,
+            when: branch.when,
+            chose: branch.use,
+            label: branch.label,
+          });
+          return this.evalTarget(branch.use);
+        }
+      }
+      if (piecewise.otherwise) {
+        this.trace.push({ kind: 'branch', id, when: 'otherwise', chose: piecewise.otherwise });
+        return this.evalTarget(piecewise.otherwise);
+      }
+      throw new SpecError(`no case matched in '${id}' and no otherwise branch is defined`);
+    }
+
+    const lookup = this.spec.lookups.find((l) => l.id === id);
+    if (lookup) return this.evalLookup(lookup);
+
+    throw new SpecError(`unknown target '${id}'`);
+  }
+
+  private evalLookup(lookup: SpecLookup): FormulaValue {
+    const key: Record<string, FormulaValue> = {};
+    for (const k of lookup.keys) key[k] = this.resolveSymbol(k) as FormulaValue;
+
+    const row = lookup.rows.find((r) => lookup.keys.every((k) => r[k] === key[k]));
+    if (!row) {
+      if (lookup.onMiss === 'null') {
+        this.trace.push({ kind: 'lookup', id: lookup.id, key, value: null });
+        return null;
+      }
+      const shown = lookup.keys.map((k) => `${k}=${String(key[k])}`).join(', ');
+      throw new SpecError(
+        `no row in '${lookup.id}' for ${shown} — the source table does not specify this combination`,
+      );
+    }
+    const value = row[lookup.result] ?? null;
+    this.trace.push({ kind: 'lookup', id: lookup.id, key, value, row });
+    return value;
+  }
+}
+
+function unitHint(unit: string | null | undefined): string {
+  return unit ? ` (${unit})` : '';
+}
+
+/**
+ * Coerce ONE text-field input into the value `evaluateSpec` should receive.
+ *
+ * This exists exactly once because three UIs (the owner evaluator, the editor,
+ * the public share calculator) each grew their own copy with subtly different
+ * numeric regexes — `'1e-5'` was a number in two of them and a string in the
+ * third. Arithmetic forgives that (`toNum` re-parses strings), but lookup keys
+ * match with STRICT equality, so a numeric key supplied as a string silently
+ * matches no row.
+ *
+ * Rules: blank → `undefined` (absent — mirrors the evaluator's blank-input
+ * treatment above); `true`/`false` → boolean; anything that reads as a finite
+ * number → number; everything else stays the string it was ('1/4 in', 'A',
+ * '1.2.3').
+ */
+export function parseInputText(raw: string): FormulaValue | undefined {
+  const t = raw.trim();
+  if (t === '') return undefined;
+  if (t === 'true') return true;
+  if (t === 'false') return false;
+  if (!/^[-+]?[0-9.]+(e[-+]?[0-9]+)?$/i.test(t)) return t;
+  const n = Number(t);
+  return Number.isFinite(n) ? n : t;
+}
+
+/**
+ * Evaluate one target — an expression, a piecewise branch, or a lookup — by id.
+ * Inputs are keyed by symbol and override anything the spec declares.
+ */
+export function evaluateSpec(
+  spec: FormulaSpec,
+  targetId: string,
+  inputs: Record<string, FormulaValue> = {},
+): EvalResult {
+  const evaluator = new SpecEvaluator(spec, inputs);
+  try {
+    const value = evaluator.evalTarget(targetId);
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+      return {
+        ok: false,
+        error: `'${targetId}' evaluated to ${String(value)} — check for a divide by zero or an out-of-domain SQRT/LN`,
+        trace: evaluator.trace,
+      };
+    }
+    return { ok: true, value, trace: evaluator.trace };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+      trace: evaluator.trace,
+    };
+  }
+}

package/src/formula-seed.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest';
+import { checkLookupCoverage, parseFormulaSpec, type FormulaSpec } from './formula-spec';
+import { checkDimensions } from './formula-dimensions';
+import { evaluateSpec } from './formula-eval';
+import { signatureOf } from './formula-signature';
+import { FORMULA_SEED, FORMULA_SEED_SLUGS, SEED_TAG } from './formula-seed';
+
+/**
+ * The seed set is shipped content AND the regression suite. It is held to a
+ * higher bar than an owner's own formulas precisely because it is the example
+ * everyone learns the format from: it must parse clean, be dimensionally
+ * consistent, have no coverage gaps of its own, and produce the right NUMBERS.
+ *
+ * The arithmetic assertions are the valuable half. A change to the evaluator
+ * that quietly breaks exponentiation or lookup matching would otherwise surface
+ * on a live assessment rather than in CI.
+ */
+
+const specOf = (raw: Record<string, unknown>): FormulaSpec => {
+  const parsed = parseFormulaSpec(raw);
+  if (!parsed.ok) throw new Error(parsed.errors.join('; '));
+  return parsed.spec;
+};
+
+describe('FORMULA_SEED', () => {
+  it('ships exactly five — the bank is owner-derived, this is only the primer', () => {
+    expect(FORMULA_SEED).toHaveLength(5);
+  });
+
+  it('has unique slugs matching each spec id, so re-seeding can detect duplicates', () => {
+    expect(new Set(FORMULA_SEED_SLUGS).size).toBe(FORMULA_SEED.length);
+    for (const f of FORMULA_SEED) expect(f.spec.id).toBe(f.slug);
+  });
+
+  it('tags every entry so the owner can find and clear the set as a group', () => {
+    for (const f of FORMULA_SEED) expect(f.tags).toContain(SEED_TAG);
+  });
+
+  it.each(FORMULA_SEED.map((f) => [f.slug, f] as const))('%s parses clean', (_slug, f) => {
+    const parsed = parseFormulaSpec(f.spec);
+    expect(parsed.ok ? [] : parsed.errors).toEqual([]);
+  });
+
+  it.each(FORMULA_SEED.map((f) => [f.slug, f] as const))(
+    '%s is dimensionally consistent',
+    (_slug, f) => {
+      expect(checkDimensions(specOf(f.spec))).toEqual([]);
+    },
+  );
+
+  it.each(FORMULA_SEED.map((f) => [f.slug, f] as const))(
+    '%s has no coverage gaps of its own',
+    (_slug, f) => {
+      // An owner's transcription may legitimately have gaps (the SOURCE is
+      // incomplete). The teaching set must not — a gap here would read as the
+      // format being broken.
+      expect(checkLookupCoverage(specOf(f.spec))).toEqual([]);
+    },
+  );
+
+  it.each(FORMULA_SEED.map((f) => [f.slug, f] as const))(
+    '%s cites a source with an edition',
+    (_slug, f) => {
+      const source = specOf(f.spec).source;
+      expect(source?.standard).toBeTruthy();
+      // An equation number is part of a claim, and numbers move between
+      // editions — so the set practises what formula_authoring preaches.
+      expect(source?.edition).toBeTruthy();
+    },
+  );
+
+  it.each(FORMULA_SEED.map((f) => [f.slug, f] as const))(
+    '%s produces the right numbers',
+    (_slug, f) => {
+      expect(f.examples.length).toBeGreaterThan(0);
+      for (const ex of f.examples) {
+        const result = evaluateSpec(specOf(f.spec), ex.target, ex.inputs);
+        if (!result.ok) throw new Error(`${f.slug} / ${ex.target}: ${result.error}`);
+        expect(typeof result.value).toBe('number');
+        expect(result.value as number).toBeCloseTo(
+          ex.expected,
+          // toBeCloseTo takes digits; derive them from the stated tolerance.
+          Math.max(0, Math.round(-Math.log10(ex.tolerance ?? 1e-6))),
+        );
+      }
+    },
+  );
+
+  it.each(FORMULA_SEED.map((f) => [f.slug, f] as const))(
+    '%s asks only for inputs its signature declares',
+    (_slug, f) => {
+      // Guards the contract the whole feature rests on: if an example supplies
+      // a symbol the signature never mentions, the two have diverged.
+      const spec = specOf(f.spec);
+      const sig = signatureOf(spec);
+      for (const ex of f.examples) {
+        const target = sig.find((s) => s.id === ex.target);
+        expect(target, `${f.slug}: no signature for target ${ex.target}`).toBeDefined();
+        const declared = new Set(target!.inputs.map((i) => i.symbol));
+        for (const supplied of Object.keys(ex.inputs)) {
+          expect(declared.has(supplied), `${f.slug}/${ex.target}: ${supplied} undeclared`).toBe(
+            true,
+          );
+        }
+        // Every REQUIRED input must be covered by the example.
+        for (const required of target!.inputs.filter((i) => i.required)) {
+          expect(
+            Object.hasOwn(ex.inputs, required.symbol),
+            `${f.slug}/${ex.target}: missing required ${required.symbol}`,
+          ).toBe(true);
+        }
+      }
+    },
+  );
+});
+
+/**
+ * The set's other job: between the five, exercise every part of the model. A
+ * teaching set with no piecewise teaches nothing about piecewise.
+ */
+describe('FORMULA_SEED — construct coverage', () => {
+  const specs = FORMULA_SEED.map((f) => specOf(f.spec));
+  const some = (p: (s: FormulaSpec) => boolean) => specs.some(p);
+
+  it('covers plain expressions and derived variables', () => {
+    expect(some((s) => s.expressions.length > 0)).toBe(true);
+    expect(some((s) => s.variables.some((v) => v.role === 'derived'))).toBe(true);
+  });
+
+  it('covers constants and defaulted inputs', () => {
+    expect(some((s) => s.variables.some((v) => v.role === 'constant'))).toBe(true);
+    expect(some((s) => s.variables.some((v) => v.role === 'input' && v.value !== undefined))).toBe(
+      true,
+    );
+  });
+
+  it('covers a piecewise branch', () => {
+    expect(some((s) => s.piecewise.length > 0)).toBe(true);
+  });
+
+  it('covers a lookup with DECLARED domains — the reason coverage checking works', () => {
+    expect(some((s) => s.lookups.some((l) => l.domains && Object.keys(l.domains).length > 0))).toBe(
+      true,
+    );
+  });
+
+  it('covers a classification with criteria prose', () => {
+    expect(some((s) => s.classifications.length > 0)).toBe(true);
+  });
+
+  it('covers latex, notes, and units on results', () => {
+    expect(some((s) => s.expressions.some((e) => e.latex))).toBe(true);
+    expect(some((s) => Boolean(s.notes && Object.keys(s.notes).length > 0))).toBe(true);
+    expect(some((s) => s.expressions.some((e) => e.unit))).toBe(true);
+  });
+
+  it('carries exactly one unverified equation — the warning has to be seeable', () => {
+    const unverified = specs.flatMap((s) => s.expressions.filter((e) => e.unverified));
+    expect(unverified).toHaveLength(1);
+    // And it must say WHY, since that text is what a reader acts on.
+    expect(unverified[0]!.unverified!.length).toBeGreaterThan(40);
+  });
+
+  it('covers symbol chaining through a produced result', () => {
+    // pump-hydraulic-power's shaft power resolves Ph via the target producing it.
+    const chained = specs.some((s) =>
+      s.expressions.some((e) =>
+        s.expressions.some(
+          (o) => o.id !== e.id && o.resultSymbol && e.expression.includes(`{${o.resultSymbol}}`),
+        ),
+      ),
+    );
+    expect(chained).toBe(true);
+  });
+});