@classytic/stage 0.3.0 → 0.4.0

package/dist/quantity/index.mjs

@@ -0,0 +1,417 @@
+//#region src/quantity/index.ts
+/**
+* quantity, a number that knows its unit.
+*
+* The model: every quantity is stored as its value in SI BASE UNITS plus a dimension vector over
+* (kg, m, s, mol, K, A). A unit string is a recipe for converting to that pair, so arithmetic is
+* ordinary arithmetic on the SI values and integer addition on the exponents:
+*
+*   a · b  →  si = a.si · b.si,   dim = a.dim + b.dim
+*   a / b  →  si = a.si / b.si,   dim = a.dim − b.dim
+*   a ± b  →  requires a.dim = b.dim
+*
+* Why this matters more than it looks. "Choose the right formula" is, operationally, "choose the
+* one whose units cancel to the unit the answer is in", and cm³-against-dm³ is the single most
+* common arithmetic error in A-level chemistry. Under this model that error cannot be made:
+*
+*   qty(0.100, 'mol/dm3').times(qty(24.50, 'cm3'))   →   2.45e-3 mol
+*
+* is simply correct, because both volumes reduce to m³ and the factors cancel. (An earlier plan
+* said this case should THROW, on the grounds that cm³ "is not" dm³. That would be a worse design:
+* it rejects a valid calculation and leaves the author to do the conversion by hand, which is the
+* step that goes wrong.) What does throw is genuine nonsense: adding a mass to a volume, or asking
+* for a mass in dm³.
+*
+* SCOPE, deliberately small: dimensional analysis over a fixed table of the units the Cambridge
+* syllabuses actually use. Not a general units library, not arbitrary dimensional algebra, no
+* user-defined units. The whole of A-level chemistry and physics fits in the table below.
+*
+* Pure: no React, no pixels.
+*/
+/** SI base dimensions. Everything in the table reduces to integer powers of these. */
+const BASE = [
+	"kg",
+	"m",
+	"s",
+	"mol",
+	"K",
+	"A"
+];
+const DIMENSIONLESS = {};
+const u = (dim, factor = 1, offset) => offset === void 0 ? {
+	dim,
+	factor
+} : {
+	dim,
+	factor,
+	offset
+};
+/**
+* The atomic units. Volume units are atomic (`dm3`, not `dm` cubed) because that is how they are
+* written and it keeps the parser from having to read `dm3` as d·m·3.
+*/
+const UNITS = {
+	"1": u(DIMENSIONLESS),
+	"%": u(DIMENSIONLESS, .01),
+	mol: u({ mol: 1 }),
+	mmol: u({ mol: 1 }, .001),
+	kg: u({ kg: 1 }),
+	g: u({ kg: 1 }, .001),
+	mg: u({ kg: 1 }, 1e-6),
+	tonne: u({ kg: 1 }, 1e3),
+	m: u({ m: 1 }),
+	cm: u({ m: 1 }, .01),
+	mm: u({ m: 1 }, .001),
+	km: u({ m: 1 }, 1e3),
+	m3: u({ m: 3 }),
+	dm3: u({ m: 3 }, .001),
+	cm3: u({ m: 3 }, 1e-6),
+	L: u({ m: 3 }, .001),
+	mL: u({ m: 3 }, 1e-6),
+	s: u({ s: 1 }),
+	ms: u({ s: 1 }, .001),
+	min: u({ s: 1 }, 60),
+	h: u({ s: 1 }, 3600),
+	K: u({ K: 1 }),
+	degC: u({ K: 1 }, 1, 273.15),
+	J: u({
+		kg: 1,
+		m: 2,
+		s: -2
+	}),
+	kJ: u({
+		kg: 1,
+		m: 2,
+		s: -2
+	}, 1e3),
+	MJ: u({
+		kg: 1,
+		m: 2,
+		s: -2
+	}, 1e6),
+	/**
+	* The kilowatt-hour: an energy, despite being spelled out of two units that both sound like rates.
+	* It is on every electricity bill and it is the standard way to catch out a student who has not
+	* separated power from energy, so it is worth being able to declare and convert rather than
+	* leaving it as a piece of folklore. 1 kWh = 1000 W x 3600 s = 3.6 MJ.
+	*/
+	kWh: u({
+		kg: 1,
+		m: 2,
+		s: -2
+	}, 36e5),
+	N: u({
+		kg: 1,
+		m: 1,
+		s: -2
+	}),
+	kN: u({
+		kg: 1,
+		m: 1,
+		s: -2
+	}, 1e3),
+	W: u({
+		kg: 1,
+		m: 2,
+		s: -3
+	}),
+	kW: u({
+		kg: 1,
+		m: 2,
+		s: -3
+	}, 1e3),
+	MW: u({
+		kg: 1,
+		m: 2,
+		s: -3
+	}, 1e6),
+	/**
+	* Horsepower, which is a power like any other despite not being SI. Declared because questions in
+	* this market quote pump and motor ratings in it, and because there are TWO of them: this is the
+	* mechanical one that exam boards mean, 745.7 W. The metric horsepower (735.5 W) is what a car
+	* brochure means, and mixing them is a one per cent error that looks like a rounding difference.
+	*/
+	hp: u({
+		kg: 1,
+		m: 2,
+		s: -3
+	}, 745.699872),
+	Hz: u({ s: -1 }),
+	/**
+	* Angles are dimensionless, which is why `sin(theta)` passes the argument check whichever of
+	* these is declared. They are still worth having as units, because the conversion is the step
+	* that goes wrong: a launch angle arrives from a question in degrees and every trig function in
+	* the language wants radians. Declaring a relation's angle as `rad` and passing `qty(30, 'deg')`
+	* converts once, at the boundary, instead of at each call site.
+	*/
+	rad: u(DIMENSIONLESS),
+	deg: u(DIMENSIONLESS, Math.PI / 180),
+	rev: u(DIMENSIONLESS, 2 * Math.PI),
+	Pa: u({
+		kg: 1,
+		m: -1,
+		s: -2
+	}),
+	kPa: u({
+		kg: 1,
+		m: -1,
+		s: -2
+	}, 1e3),
+	atm: u({
+		kg: 1,
+		m: -1,
+		s: -2
+	}, 101325),
+	bar: u({
+		kg: 1,
+		m: -1,
+		s: -2
+	}, 1e5),
+	A: u({ A: 1 }),
+	C: u({
+		s: 1,
+		A: 1
+	}),
+	V: u({
+		kg: 1,
+		m: 2,
+		s: -3,
+		A: -1
+	})
+};
+/** Named SI-coherent units, for naming the result of an arithmetic operation. */
+const NAMED = [
+	["mol", { mol: 1 }],
+	["kg", { kg: 1 }],
+	["m", { m: 1 }],
+	["s", { s: 1 }],
+	["K", { K: 1 }],
+	["A", { A: 1 }],
+	["m3", { m: 3 }],
+	["J", {
+		kg: 1,
+		m: 2,
+		s: -2
+	}],
+	["N", {
+		kg: 1,
+		m: 1,
+		s: -2
+	}],
+	["W", {
+		kg: 1,
+		m: 2,
+		s: -3
+	}],
+	["Hz", { s: -1 }],
+	["Pa", {
+		kg: 1,
+		m: -1,
+		s: -2
+	}],
+	["C", {
+		s: 1,
+		A: 1
+	}],
+	["V", {
+		kg: 1,
+		m: 2,
+		s: -3,
+		A: -1
+	}]
+];
+function combineDim(a, b, sign) {
+	const out = {};
+	for (const k of BASE) {
+		const n = (a[k] ?? 0) + sign * (b[k] ?? 0);
+		if (n !== 0) out[k] = n;
+	}
+	return out;
+}
+const mulDim = (a, b) => combineDim(a, b, 1);
+const divDim = (a, b) => combineDim(a, b, -1);
+/** Raise a dimension to an integer power. A fractional power is legal only if it leaves every
+*  exponent an integer, which is what makes `sqrt(Ka·c)` work and `sqrt(mol)` fail. */
+function powDim(a, n) {
+	const out = {};
+	for (const k of BASE) {
+		const e = (a[k] ?? 0) * n;
+		if (e === 0) continue;
+		if (!Number.isInteger(e)) throw new Error(`${formatDimension(a)}^${n} has a fractional dimension, which is not a unit`);
+		out[k] = e;
+	}
+	return out;
+}
+const sameDim = (a, b) => BASE.every((k) => (a[k] ?? 0) === (b[k] ?? 0));
+const isDimensionless = (a) => BASE.every((k) => (a[k] ?? 0) === 0);
+/** For error messages, where "1" would read as a number rather than as "has no units". */
+const describeDimension = (d) => isDimensionless(d) ? "dimensionless" : formatDimension(d);
+/**
+* "kg·m^2/s^2·mol": readable in an error message AND parseable by `parseUnit`.
+*
+* Both properties are required. It names the dimension in messages, and it also names the unit of
+* a quantity produced by arithmetic, which is then re-read the next time that quantity is used. An
+* earlier version emitted `m2`, which reads back as an unknown unit rather than as m², so a
+* perfectly good result became unusable one operation later.
+*/
+function formatDimension(d) {
+	const show = (k, e) => e === 1 ? k : `${k}^${e}`;
+	const top = BASE.filter((k) => (d[k] ?? 0) > 0).map((k) => show(k, d[k]));
+	const bot = BASE.filter((k) => (d[k] ?? 0) < 0).map((k) => show(k, -d[k]));
+	if (!top.length && !bot.length) return "1";
+	return `${top.join("·") || "1"}${bot.length ? `/${bot.join("·")}` : ""}`;
+}
+const cache = /* @__PURE__ */ new Map();
+/**
+* Resolve a unit string to a dimension and a factor.
+*
+* Grammar: atoms separated by `·`, `*` or a space are multiplied; **every** segment after a `/` is
+* a denominator, so `J/K/mol` is J·K⁻¹·mol⁻¹. That reading is the chemistry convention and it is
+* stated here because `a/b/c` is genuinely ambiguous in general.
+*
+* An atom may carry an integer exponent written with a caret: `mol^2`, `dm3^2` (which is dm⁶, the
+* denominator of a Ksp for a 1:2 salt). The caret is REQUIRED rather than optional, because a
+* trailing digit is already part of the name in `dm3` and `cm3`, so `dm6` would have to be read as
+* both a name and a power.
+*/
+function parseUnit(spec) {
+	const hit = cache.get(spec);
+	if (hit) return hit;
+	const segments = spec.trim().split("/");
+	if (segments.length === 0 || segments[0].trim() === "") throw new Error(`Unit "${spec}" is empty`);
+	let dim = DIMENSIONLESS;
+	let factor = 1;
+	let offset;
+	let atomCount = 0;
+	segments.forEach((segment, index) => {
+		const atoms = segment.split(/[·*\s]+/).map((a) => a.trim()).filter(Boolean);
+		if (!atoms.length) throw new Error(`Unit "${spec}" has an empty part`);
+		for (const atom of atoms) {
+			const caret = atom.indexOf("^");
+			const name = caret === -1 ? atom : atom.slice(0, caret);
+			const power = caret === -1 ? 1 : Number(atom.slice(caret + 1));
+			if (!Number.isInteger(power) || power === 0) throw new Error(`Exponent in "${atom}" must be a non-zero integer`);
+			const def = UNITS[name];
+			if (!def) throw new Error(`Unknown unit "${name}" in "${spec}". Add it to the table if the syllabus uses it.`);
+			atomCount++;
+			if (def.offset !== void 0) offset = def.offset;
+			const signed = index === 0 ? power : -power;
+			dim = mulDim(dim, powDim(def.dim, signed));
+			factor *= Math.pow(def.factor, signed);
+		}
+	});
+	if (offset !== void 0 && atomCount > 1) throw new Error(`"${spec}" combines degC with another unit. A temperature on the Celsius scale is a point, not a size; use K.`);
+	const resolved = offset === void 0 ? {
+		dim,
+		factor
+	} : {
+		dim,
+		factor,
+		offset
+	};
+	cache.set(spec, resolved);
+	return resolved;
+}
+/** The units this kernel knows, for an error message or an editor. */
+const knownUnits = () => Object.keys(UNITS);
+/**
+* A value with a unit. Immutable: every operation returns a new Quantity.
+*
+* `si` is the value in SI base units and is the single source of truth; `unit` is only how it is
+* currently being displayed.
+*/
+var Quantity = class Quantity {
+	si;
+	dim;
+	unit;
+	/** True only for a Celsius temperature. Carried rather than re-derived: see `requireScale`. */
+	onScale;
+	constructor(si, dim, unit, onScale = false) {
+		this.si = si;
+		this.dim = dim;
+		this.unit = unit;
+		this.onScale = onScale;
+	}
+	static of(value, unit) {
+		const r = parseUnit(unit);
+		return new Quantity(value * r.factor + (r.offset ?? 0), r.dim, unit, r.offset !== void 0);
+	}
+	/** Build directly from an SI value, naming the unit from the dimension. */
+	static fromSI(si, dim) {
+		return new Quantity(si, dim, canonicalUnit(dim));
+	}
+	/** The number, expressed in `this.unit`. */
+	get value() {
+		return this.in(this.unit);
+	}
+	/** The number, expressed in `unit`. Throws if the dimensions differ. */
+	in(unit) {
+		const r = parseUnit(unit);
+		if (!sameDim(this.dim, r.dim)) throw new Error(`Cannot express ${describeDimension(this.dim)} in "${unit}" (${describeDimension(r.dim)}).`);
+		return (this.si - (r.offset ?? 0)) / r.factor;
+	}
+	/** The same quantity, displayed in `unit`. */
+	to(unit) {
+		const r = parseUnit(unit);
+		if (!sameDim(this.dim, r.dim)) throw new Error(`Cannot convert ${describeDimension(this.dim)} to "${unit}" (${describeDimension(r.dim)}).`);
+		return new Quantity(this.si, this.dim, unit, r.offset !== void 0);
+	}
+	requireScale(op) {
+		if (this.onScale) throw new Error(`Cannot ${op} a temperature on the Celsius scale. Convert to K first: .to('K').`);
+	}
+	times(other) {
+		this.requireScale("multiply");
+		if (typeof other === "number") return new Quantity(this.si * other, this.dim, this.unit);
+		other.requireScale("multiply");
+		return Quantity.fromSI(this.si * other.si, mulDim(this.dim, other.dim));
+	}
+	over(other) {
+		this.requireScale("divide");
+		if (typeof other === "number") return new Quantity(this.si / other, this.dim, this.unit);
+		other.requireScale("divide");
+		return Quantity.fromSI(this.si / other.si, divDim(this.dim, other.dim));
+	}
+	plus(other) {
+		this.requireSame(other, "add");
+		return new Quantity(this.si + other.si, this.dim, this.unit);
+	}
+	/**
+	* Note what this CANNOT do: subtract two Celsius temperatures. The SI difference would be right
+	* (a kelvin interval) but the result would be displayed back on the Celsius scale, where 12.5 K
+	* reads as −260.65 °C. `requireScale` refuses it, and `.to('K')` on both sides is the fix.
+	*/
+	minus(other) {
+		this.requireSame(other, "subtract");
+		return new Quantity(this.si - other.si, this.dim, this.unit);
+	}
+	pow(n) {
+		this.requireScale("raise to a power");
+		return Quantity.fromSI(Math.pow(this.si, n), powDim(this.dim, n));
+	}
+	requireSame(other, op) {
+		this.requireScale(op);
+		other.requireScale(op);
+		if (!sameDim(this.dim, other.dim)) throw new Error(`Cannot ${op} ${describeDimension(this.dim)} and ${describeDimension(other.dim)}.`);
+	}
+	/** Equal within a RELATIVE tolerance (default 1e-9), after reducing both to SI. */
+	equals(other, tol = 1e-9) {
+		if (!sameDim(this.dim, other.dim)) return false;
+		return Math.abs(this.si - other.si) <= tol * Math.max(1, Math.abs(this.si), Math.abs(other.si));
+	}
+	/** "2.45e-3 mol", at `sf` significant figures. */
+	toString(sf = 3) {
+		const v = this.value;
+		return `${Number.isFinite(v) ? Number(v.toPrecision(sf)) : v} ${this.unit === "1" ? "" : this.unit}`.trim();
+	}
+};
+/** `qty(24.50, 'cm3')`. */
+const qty = (value, unit) => Quantity.of(value, unit);
+/** The SI-coherent name for a dimension: 'mol', 'J', or a composed 'kg·m2/s2'. */
+function canonicalUnit(dim) {
+	if (isDimensionless(dim)) return "1";
+	for (const [name, d] of NAMED) if (sameDim(dim, d)) return name;
+	return formatDimension(dim);
+}
+
+//#endregion
+export { DIMENSIONLESS, Quantity, canonicalUnit, describeDimension, divDim, formatDimension, isDimensionless, knownUnits, mulDim, parseUnit, powDim, qty, sameDim };

package/dist/relation/derive.d.mts

@@ -0,0 +1,74 @@
+import { Relation } from "./index.mjs";
+
+//#region src/relation/derive.d.ts
+/** One application of a known relation on the way to the target. */
+interface DerivationStep {
+  /** The relation being used. A getter, so a lazily built one stays lazy. */
+  readonly relation: () => Relation;
+  /**
+   * Which variable of that relation this step works out.
+   *
+   * Named in the PREMISE relation's own vocabulary, so `n` for `n = c * V`.
+   */
+  readonly solveFor: string;
+  /**
+   * How the premise relation's variables are filled, as premise name to derivation name.
+   *
+   * The two vocabularies differ on purpose: a dilution talks about `c1` and `c2`, and the relation
+   * it leans on only knows `c`. Spelling the mapping out is what lets one relation be reused at
+   * both ends of an argument.
+   */
+  readonly using: Readonly<Record<string, string>>;
+  /** What the result is called from here on. */
+  readonly gives: string;
+  /** Why this step is allowed. The sentence a learner actually needs. */
+  readonly because: string;
+}
+type DerivationKind = 'definition' | 'derived' | 'measured';
+interface Derivation {
+  readonly kind: DerivationKind;
+  /** The argument in one sentence. */
+  readonly summary: string;
+  /** What is held fixed, which is usually the whole reason a derivation works. */
+  readonly invariant?: string;
+  /** The chain, for a derived relation. Empty for a definition or a measurement. */
+  readonly steps?: readonly DerivationStep[];
+  /** Which variable of the TARGET relation the chain arrives at. */
+  readonly arrivesAt?: string;
+  /** What was observed, for a measured relation. */
+  readonly evidence?: string;
+}
+/**
+ * Walk a derivation and compute its result from the inputs, the long way round.
+ *
+ * Each step solves one premise relation and adds its answer to the scope, so later steps can use
+ * it. The value returned is whatever the last step produced.
+ */
+declare function deriveValue(derivation: Derivation, inputs: Readonly<Record<string, number>>): number;
+interface DerivationCheck {
+  readonly agrees: boolean;
+  /** The largest relative difference found across the samples. */
+  readonly worstError: number;
+  /** The inputs that produced it, for a failure worth reading. */
+  readonly worstAt?: Readonly<Record<string, number>>;
+}
+/**
+ * Check a derivation by computing the answer both ways over a set of inputs.
+ *
+ * The target relation gives the short answer, the chain gives the long one, and a sound derivation
+ * makes them the same number. Anything else means the argument does not actually reach the formula
+ * it claims to reach, which is a thing a paragraph of prose can hide indefinitely.
+ *
+ * The samples are supplied rather than generated, so a check reads as a list of cases and a failure
+ * names the one that broke.
+ */
+declare function checkDerivation(target: Relation, derivation: Derivation, samples: readonly Readonly<Record<string, number>>[], tolerance?: number): DerivationCheck;
+/**
+ * The derivation as lines of reasoning, for a lesson to show.
+ *
+ * Returns the sentences and not a rendered block, because how it is laid out is a decision for
+ * whatever is displaying it.
+ */
+declare function explain(derivation: Derivation): string[];
+//#endregion
+export { Derivation, DerivationCheck, DerivationKind, DerivationStep, checkDerivation, deriveValue, explain };

package/dist/relation/derive.mjs

@@ -0,0 +1,73 @@
+//#region src/relation/derive.ts
+/**
+* Walk a derivation and compute its result from the inputs, the long way round.
+*
+* Each step solves one premise relation and adds its answer to the scope, so later steps can use
+* it. The value returned is whatever the last step produced.
+*/
+function deriveValue(derivation, inputs) {
+	if (!derivation.steps || derivation.steps.length === 0) throw new Error(`this ${derivation.kind} has no chain to walk: only a derived relation can be computed step by step`);
+	const scope = { ...inputs };
+	let last = 0;
+	for (const step of derivation.steps) {
+		const given = {};
+		for (const [premiseName, ourName] of Object.entries(step.using)) {
+			const value = scope[ourName];
+			if (value === void 0) throw new Error(`the step giving "${step.gives}" needs "${ourName}", which no earlier step produced and the inputs do not contain`);
+			given[premiseName] = value;
+		}
+		last = step.relation().solve(given).value;
+		scope[step.gives] = last;
+	}
+	return last;
+}
+/**
+* Check a derivation by computing the answer both ways over a set of inputs.
+*
+* The target relation gives the short answer, the chain gives the long one, and a sound derivation
+* makes them the same number. Anything else means the argument does not actually reach the formula
+* it claims to reach, which is a thing a paragraph of prose can hide indefinitely.
+*
+* The samples are supplied rather than generated, so a check reads as a list of cases and a failure
+* names the one that broke.
+*/
+function checkDerivation(target, derivation, samples, tolerance = 1e-9) {
+	if (!derivation.arrivesAt) throw new Error("a derivation that is checked must say which variable of the target it arrives at");
+	let worstError = 0;
+	let worstAt;
+	for (const sample of samples) {
+		const theLongWay = deriveValue(derivation, sample);
+		const theShortWay = target.solve({ ...sample }).value;
+		const scale = Math.max(Math.abs(theShortWay), 1e-12);
+		const error = Math.abs(theLongWay - theShortWay) / scale;
+		if (error > worstError) {
+			worstError = error;
+			worstAt = sample;
+		}
+	}
+	return worstError <= tolerance ? {
+		agrees: true,
+		worstError
+	} : {
+		agrees: false,
+		worstError,
+		...worstAt ? { worstAt } : {}
+	};
+}
+/**
+* The derivation as lines of reasoning, for a lesson to show.
+*
+* Returns the sentences and not a rendered block, because how it is laid out is a decision for
+* whatever is displaying it.
+*/
+function explain(derivation) {
+	const lines = [derivation.summary];
+	if (derivation.invariant) lines.push(`What stays fixed: ${derivation.invariant}`);
+	if (derivation.kind === "measured" && derivation.evidence) lines.push(`This one is measured, not derived. ${derivation.evidence}`);
+	if (derivation.kind === "definition") lines.push("This one is a definition. There is nothing underneath it to derive.");
+	for (const step of derivation.steps ?? []) lines.push(`${step.relation().title}, solved for ${step.solveFor}: ${step.because}`);
+	return lines;
+}
+
+//#endregion
+export { checkDerivation, deriveValue, explain };

package/dist/relation/index.d.mts

@@ -0,0 +1,56 @@
+import { Quantity } from "../quantity/index.mjs";
+import { Worked } from "../core/worked.mjs";
+import { Derivation, DerivationCheck, DerivationKind, DerivationStep, checkDerivation, deriveValue, explain } from "./derive.mjs";
+
+//#region src/relation/index.d.ts
+/** A value supplied to `solve`: a bare number IN THE DECLARED UNIT, or a quantity in any unit. */
+type Given = number | Quantity;
+interface Solved {
+  /** The variable that was solved for. */
+  readonly name: string;
+  /** Its value, in the unit the relation declared for it. */
+  readonly value: number;
+  readonly unit: string;
+  readonly quantity: Quantity;
+}
+interface RelationSpec {
+  /** `'n = c * V'`. Exactly one `=`. */
+  readonly equation: string;
+  /** Unit for every variable in the equation. A missing one is an error, not a guess. */
+  readonly units: Readonly<Record<string, string>>;
+  /** Shown instead of the raw equation in worked steps. Defaults to the equation. */
+  readonly title?: string;
+}
+declare class Relation {
+  readonly equation: string;
+  readonly title: string;
+  readonly units: Readonly<Record<string, string>>;
+  readonly variables: readonly string[];
+  private readonly left;
+  private readonly right;
+  private readonly dims;
+  private readonly isolated;
+  constructor(spec: RelationSpec);
+  /** The declared unit of a variable. */
+  unitOf(name: string): string;
+  /** Numeric values in declared units, converting any Quantity that was passed in. */
+  private normalise;
+  /** The one variable of the relation that `given` does not supply. */
+  private unknownOf;
+  private expressionFor;
+  /** Solve for whichever variable was left out of `given`. */
+  solve(given: Readonly<Record<string, Given>>): Solved;
+  /** Solve for a named variable, ignoring any value supplied for it. */
+  solveFor(target: string, given: Readonly<Record<string, Given>>): Solved;
+  /**
+   * The worked substitution, for a lesson's derivation.
+   *
+   * Three lines: the relation, the relation rearranged for the unknown, and the substitution with
+   * the answer. Every number shown came from `given`, which is the property that makes a generated
+   * derivation trustworthy in a way a hand-written one is not.
+   */
+  steps(given: Readonly<Record<string, Given>>, sf?: number): Worked;
+}
+declare const relation: (equation: string, units: Readonly<Record<string, string>>, title?: string) => Relation;
+//#endregion
+export { type Derivation, type DerivationCheck, type DerivationKind, type DerivationStep, Given, Relation, RelationSpec, Solved, checkDerivation, deriveValue, explain, relation };