document-compute.js 0.0.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Mearman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# document-compute.js
+
+[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/documents.js/tree/main/packages/document-compute.js) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/document-compute.js) [![npm version](https://img.shields.io/npm/v/document-compute.js)](https://www.npmjs.com/package/document-compute.js) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/documents.js/ci.yml?branch=main)](https://github.com/ExaDev/documents.js/actions)
+
+> A units-typed, tree-walking evaluator for `document-schema.js`'s `MathExpression` — `evaluate()` for point values and bounded intervals over the same interpreter, `solveFor()` for numeric root-finding (bisection and Newton's method) on one unknown. Exact-rational arithmetic for unit-conversion factors, so a chain of registry conversions never accumulates floating-point drift. The compute package for the [documents.js family](https://github.com/ExaDev). Worker-isomorphic: the same code runs under Node and inside a Cloudflare Workers isolate.
+
+Created for [ExaDev/documents.js#573](https://github.com/ExaDev/documents.js/issues/573): a document's formula is stored as a `MathExpression` tree (`document-schema.js`'s `src/math.ts`, [ExaDev/document-schema.js#15](https://github.com/ExaDev/document-schema.js/issues/15)) — the semantic half of a `ContentFormula`, alongside the LaTeX a renderer serialises verbatim. Storing that tree buys nothing on its own; a document that states a formula and then reports its computed answer needs something that actually walks the tree and produces a number, unit-aware, without silently mixing dimensions that don't belong together. This package is that something: one interpreter, reused unchanged across three shapes of the same problem — a point value, a bounded interval, and (via root-finding) an unknown to solve for.
+
+## Getting started
+
+Requires Node.js `>=20` and pnpm `11.6.0`.
+
+```sh
+pnpm install
+pnpm build          # tsdown -> dist/ (ESM + CJS + .d.ts)
+pnpm typecheck      # tsc -p tsconfig.json && tsc -p tsconfig.node.json (dual tsconfig)
+pnpm lint           # eslint . --fix --cache --max-warnings 0
+pnpm test           # vitest run
+pnpm test:watch     # vitest
+pnpm test:workers   # vitest run --config vitest.workers.config.ts, inside a real Cloudflare Workers (workerd) isolate
+```
+
+To run a single test file, pass its path to vitest directly, e.g. `pnpm exec vitest run src/compute/evaluate.test.ts`.
+
+## What it provides
+
+| Module | Exports |
+|---|---|
+| `compute/rational` | `Rational`, `toRational`, `toExactRational`, `addRational`, `subtractRational`, `multiplyRational`, `divideRational`, `rationalToNumber` |
+| `compute/dimensions` | `dimensionExponent`, `dimensionsEqual`, `isDimensionless`, `multiplyDimensions`, `divideDimensions`, `scaleDimension`, `dimensionToString` |
+| `compute/quantity` | `quantity`, `addQuantities`, `subtractQuantities`, `multiplyQuantities`, `divideQuantities`, `negateQuantity`, `absQuantity`, `powQuantity`, `sqrtQuantity`, `sinQuantity`, `cosQuantity`, `tanQuantity` |
+| `compute/interval` | `interval`, `pointInterval`, `addIntervals`, `subtractIntervals`, `multiplyIntervals`, `divideIntervals`, `negateInterval`, `absInterval` |
+| `compute/evaluate` | `evaluate`, `EvaluationResult`, `isInterval` |
+| `compute/solve` | `solveFor`, `SolveMethod`, `SolveForOptions` |
+| `compute/errors` | `IncompatibleDimensionsError`, `UnboundSymbolError`, `UnknownUnitError`, `DivisionByZeroError`, `UnsupportedExpressionError`, `NumericDomainError`, `NonConvergentSolveError` |
+
+Every module in the table is re-exported from the package root, so its exports import from `'document-compute.js'` directly.
+
+The value types this evaluator consumes and produces — `Quantity`, `Interval`, `EvaluationValue`, `FormulaBindings`, and their Zod schemas — are not defined here: they are typed contracts in `document-schema.js` itself (`src/math.ts`, beside `MathExpression`), so evaluation inputs are schema-validated shapes like everything else in that package. Import them from `'document-schema.js'` the same way this package does:
+
+```ts
+import { evaluate } from 'document-compute.js';
+import type { FormulaBindings, MathExpression } from 'document-schema.js';
+
+// F = m * a
+const force: MathExpression = {
+  kind: 'app',
+  operator: 'math:multiply',
+  args: [{ kind: 'sym', id: 'm' }, { kind: 'sym', id: 'a' }],
+};
+
+const bindings: FormulaBindings = {
+  m: { kind: 'quantity', magnitude: 2, dimension: { mass: 1 } },
+  a: { kind: 'quantity', magnitude: 3, dimension: { length: 1, time: -2 } },
+};
+
+const result = evaluate(force, bindings);
+// { kind: 'quantity', magnitude: 6, dimension: { mass: 1, length: 1, time: -2 } }
+```
+
+`evaluate` never returns a failure inside its result: a successful call returns a plain `Quantity | Interval` (see below on why the return type is not literally `Quantity | Interval | error`), and every real failure throws one of `compute/errors`' own classes — the same idiom `document-schema.js`'s `schema-io.ts` and `archive-codec`'s `CompoundFileFormatError`/`ArchiveWalkLimitError` already use: a named, catchable `Error` subclass, never a `{ ok, error }` wrapper folded into the return type.
+
+## Units as the type system
+
+Every `Quantity` this evaluator produces carries a `dimension` — an SI exponent vector reusing `document-schema.js`'s own `DimensionVector` (`{ length: 1, time: -1 }` for speed, `{}` for dimensionless) — alongside a plain `magnitude`. Adding or subtracting two quantities whose dimensions don't match is not a number this package will produce: `addQuantities`/`subtractQuantities` (and the identical rule inside `evaluate` for `math:add`/`math:subtract`) throw `IncompatibleDimensionsError` rather than returning a value that happens to be wrong. Multiplication and division are always dimensionally defined — they combine dimension vectors by adding or subtracting exponents (`compute/dimensions.ts`'s `multiplyDimensions`/`divideDimensions`) — so there is nothing to reject there, only a resulting dimension to compute. `powQuantity`/`sqrtQuantity` extend the same rule to exponents: a dimensionless base tolerates any real exponent, a dimensioned one only an integer power whose scaled exponents stay integers (`DimensionVectorSchema` requires integers, so `sqrt` of `length^1` has no answer and throws — `IncompatibleDimensionsError` again, not a fractional dimension nobody asked for).
+
+A `MathExpression`'s `'qty'` leaf carries an exact value plus a unit-registry id (`document-schema.js`'s `MathQty`/`MathUnit`, resolved against the `SymbolTable` passed as `evaluate`'s third argument); `evaluateQty` (`compute/evaluate.ts`) resolves that id, then computes `si_value = value * factorToSi + offsetToSi` — **entirely in exact BigInt rational arithmetic** (`compute/rational.ts`), converting to a plain JS `number` exactly once, at the moment the resolved SI-coherent magnitude enters the evaluator as a `Quantity`. That is the one deliberate exactness boundary in this package: a chain of unit-registry conversions (feet to metres, an affine temperature scale, a per-unit-normalised power-system quantity) never compounds floating-point rounding the way repeated `Number` multiplication would, because every step upstream of that single conversion is bit-exact BigInt arithmetic, reduced to lowest terms at every operation. Downstream of that boundary — ordinary `+`/`-`/`*`/`/` between already-resolved `Quantity` magnitudes, `sin`/`cos`/`sqrt`, a `solveFor` root — is plain floating point, because those results are not exact in general (there is no exact rational `sin(1)`), and holding them to bit-exactness would be false precision, not a stronger guarantee. `QuantitySchema`'s own field comment on `magnitude` states this trade-off; it is a judgement call this package makes deliberately, not an oversight.
+
+## Interval arithmetic, over the same evaluator
+
+The issue's own example is a compliance region: `0.87 <= cos(phi) <= 1`. Rather than adding a second evaluator for "a formula, but with ranges," `FormulaBindings` lets any symbol be bound to an `Interval` (`{ kind: 'interval', min, max, dimension }`) instead of a point `Quantity`, and `evaluate`'s `'app'` dispatch promotes a plain `Quantity` operand to a degenerate point interval (`pointInterval`) the moment either side of a binary operator is an `Interval` — the same tree walk, the same operator ids, just running over ranges instead of points once it notices one. `addIntervals`/`subtractIntervals` combine endpoints directly; `multiplyIntervals`/`divideIntervals` implement the standard rule that a product's or quotient's extremes are always attained at one of the four corner combinations of the two intervals' endpoints (`min*min, min*max, max*min, max*max`, or the equivalent via the reciprocal for division) — which is what actually resolves the textbook sign-case table (positive×positive, negative×negative, straddling×straddling, and every mixed case) into one formula that is correct regardless of which side of zero either interval sits on; `interval.test.ts` exercises each sign combination directly rather than trusting the closed form on faith. Division by an interval that touches or straddles zero has no defined result (it would pass through ±Infinity) and throws `DivisionByZeroError` instead of letting `Infinity`/`NaN` flow silently into the rest of a computation. Only the four arithmetic operators plus negate/abs have interval rules in this pass — `pow`/`sqrt`/the trig functions are `Quantity`-only and throw `UnsupportedExpressionError` on an `Interval` operand, since a correct general interval range for a non-monotonic or sign-dependent function needs more analysis than this pass's scope covers (see below).
+
+## Numeric solve-for
+
+`solveFor(expression, targetValue, unknownSymbol, bindings, options?, context?)` finds the magnitude for `unknownSymbol` that makes `expression` evaluate to `targetValue`, by root-finding over the same `evaluate` — never by rearranging the expression algebraically. It implements both algorithms the issue asks for and lets `options.method` pick between them (`'bisection'`, the default, or `'newton'`):
+
+- **Bisection** needs `options.bracket: [low, high]` whose residuals have opposite signs (the intermediate-value theorem is its entire correctness argument), halves the bracket every iteration, and cannot diverge — the safe default.
+- **Newton's method** needs `options.initialGuess` and estimates the derivative by central difference, `(f(x+h) - f(x-h)) / (2h)` (`options.derivativeStep`, default `1e-6`) — chosen over a one-sided forward/backward difference because its truncation error is `O(h²)` rather than `O(h)`. No symbolic derivative is available without a symbolic layer this pass deliberately does not build (see Out of scope), so a numeric one is the whole story here.
+
+Both throw `NonConvergentSolveError` rather than returning a number they cannot vouch for: bisection when its bracket doesn't straddle a root or the iteration budget (`options.maxIterations`, default 100) runs out before the residual drops under `options.tolerance` (default `1e-9`); Newton when the numeric derivative vanishes or diverges, or the same budget/tolerance is exhausted. `options.unknownDimension` sets the `DimensionVector` the unknown is bound under at each trial point (default dimensionless) so a physically dimensioned unknown (a length, a mass) solves correctly against a formula that checks dimensions along the way.
+
+```ts
+import { solveFor } from 'document-compute.js';
+import type { MathExpression } from 'document-schema.js';
+
+// x^2 = 4, solve for x
+const xSquared: MathExpression = {
+  kind: 'app',
+  operator: 'math:pow',
+  args: [{ kind: 'sym', id: 'x' }, { kind: 'num', numerator: '2', denominator: '1' }],
+};
+
+solveFor(xSquared, 4, 'x', {}, { bracket: [0, 3] }); // 2, via bisection
+solveFor(xSquared, 4, 'x', {}, { method: 'newton', initialGuess: 3 }); // 2, via Newton
+```
+
+## Deviations from the issue
+
+Two things #573 asks for are not here in full. One was closed at adoption: `Quantity` and `FormulaBindings` (with `Interval` and `EvaluationValue`) are typed contracts in `document-schema.js`'s `src/math.ts`, beside `MathExpression` itself, exactly as the issue proposes — evaluation inputs are validated schemas like everything else in that package, and this package imports them from there the same way it imports `MathExpression`, `DimensionVector`, and `ExactRational`, rather than carrying package-local definitions.
+
+The one that remains: **the worked-example test harness** the issue describes as its differentiator — measuring the fraction of a real document corpus's formulae whose evaluation reproduces the document's own stated answer. That harness needs real document corpora with stated formulae and answers, which this package has no access to build against; what ships here instead is thorough unit-level coverage of `evaluate`, the unit/dimension model, interval arithmetic, and `solveFor` in isolation (`src/compute/*.test.ts`). It is tracked as a follow-up to this package, not silently dropped.
+
+## Out of scope
+
+Quoting the issue's own scope line directly: **this is deliberately not a CAS in the Mathematica sense — units-typed evaluation and numeric solving are the 90% of "compute the result of a formula from a document" and are buildable natively now.** Concretely, this pass does not attempt, and this package carries no code toward:
+
+- **Symbolic algebra** — exact rearrangement of an expression emitted back out as LaTeX, simplification, integration. `solveFor` finds a root numerically; it never isolates the unknown algebraically.
+- **A SymPy sidecar or any other symbolic-engine adapter.** The issue names this as the eventual home for symbolic work, behind an evaluator interface this package does not define or stub.
+- **The worked-example test harness** — see Deviations from the issue above.
+- **Matrix-valued evaluation.** `MathExpression`'s `'matrix'` node exists in the grammar `document-schema.js` defines, but this evaluator only ever produces scalar `Quantity`/`Interval` values; a `'matrix'` node throws `UnsupportedExpressionError` rather than being silently misevaluated.
+- **A general interval rule for `pow`/`sqrt`/the trigonometric operators.** These are implemented for `Quantity` only; applied to an `Interval` operand they throw `UnsupportedExpressionError` rather than guessing at a range a non-monotonic or sign-dependent function would need real analysis to get right.
+
+## Conventions
+
+- Worker-isomorphic (see the [family-wide convention](https://github.com/ExaDev/documents.js/blob/main/README.md#conventions)): runtime `src/` must not import `node:*`, a bare Node builtin, or use the `Buffer` global — enforced by a `no-restricted-imports`/`no-restricted-globals` ESLint rule and exercised in CI by running a test suite inside an actual `workerd` isolate (`pnpm test:workers`). Exact-rational arithmetic is plain `BigInt`, never `node:crypto` or any other Node-only primitive, precisely so this holds.
+- Only `src/index.ts` may be named `index.*` — a custom ESLint rule (`local/no-non-barrel-index`) rejects any other module using an `index` basename, since that would be a hidden entry point the `exports` map in `package.json` doesn't advertise.
+- Failure is always a thrown, named `Error` subclass (`compute/errors.ts`), never a `{ ok, error }` result wrapper — matching `document-schema.js`'s `schema-io.ts` and `archive-codec`'s own error classes rather than inventing a second convention for this package alone.
+- Not wired into the conversion pipeline. This package is a standalone evaluator: it is not a dependency of `documents.js`, `document-cli`, `document-mcp`, or `documents`, and adding it as one is a separate, deliberate decision for whichever of those surfaces first needs a document's formula actually computed.
+- Release, CI, and commit-message conventions are all workspace-wide, not package-local — see the [monorepo root README](../../README.md#releases) for the mechanism (topological per-package `semantic-release` via `@exadev/semantic-release-workspace`, OIDC trusted npm publishing, and the post-release republish/attestation jobs).
+
+## Install
+
+```sh
+pnpm add document-compute.js
+# or
+npm install document-compute.js
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,495 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let document_schema_js = require("document-schema.js");
+//#region src/compute/rational.ts
+function bigintOfCanonicalDigits(digits) {
+	return BigInt(digits);
+}
+function toRational(value) {
+	return {
+		n: bigintOfCanonicalDigits(value.numerator),
+		d: bigintOfCanonicalDigits(value.denominator)
+	};
+}
+function gcd(a, b) {
+	let x = a < 0n ? -a : a;
+	let y = b < 0n ? -b : b;
+	while (y !== 0n) [x, y] = [y, x % y];
+	return x === 0n ? 1n : x;
+}
+function reduce(n, d) {
+	if (d === 0n) throw new RangeError("rational.ts: denominator must not be zero");
+	if (n === 0n) return {
+		n: 0n,
+		d: 1n
+	};
+	const sign = d < 0n ? -1n : 1n;
+	const num = n * sign;
+	const den = d * sign;
+	const g = gcd(num, den);
+	return {
+		n: num / g,
+		d: den / g
+	};
+}
+function toExactRational(value) {
+	const reduced = reduce(value.n, value.d);
+	return {
+		numerator: reduced.n.toString(),
+		denominator: reduced.d.toString()
+	};
+}
+function addRational(a, b) {
+	return reduce(a.n * b.d + b.n * a.d, a.d * b.d);
+}
+function subtractRational(a, b) {
+	return reduce(a.n * b.d - b.n * a.d, a.d * b.d);
+}
+function multiplyRational(a, b) {
+	return reduce(a.n * b.n, a.d * b.d);
+}
+function divideRational(a, b) {
+	if (b.n === 0n) throw new RangeError("rational.ts: division by zero");
+	return reduce(a.n * b.d, a.d * b.n);
+}
+function rationalToNumber(value) {
+	return Number(value.n) / Number(value.d);
+}
+//#endregion
+//#region src/compute/dimensions.ts
+function dimensionExponent(dimension, base) {
+	return dimension[base] ?? 0;
+}
+function dimensionsEqual(a, b) {
+	return document_schema_js.SI_BASE_DIMENSIONS.every((base) => dimensionExponent(a, base) === dimensionExponent(b, base));
+}
+function isDimensionless(dimension) {
+	return document_schema_js.SI_BASE_DIMENSIONS.every((base) => dimensionExponent(dimension, base) === 0);
+}
+function combine(a, b, op) {
+	const result = {};
+	for (const base of document_schema_js.SI_BASE_DIMENSIONS) {
+		const value = op(dimensionExponent(a, base), dimensionExponent(b, base));
+		if (value !== 0) result[base] = value;
+	}
+	return result;
+}
+function multiplyDimensions(a, b) {
+	return combine(a, b, (x, y) => x + y);
+}
+function divideDimensions(a, b) {
+	return combine(a, b, (x, y) => x - y);
+}
+function scaleDimension(dimension, k) {
+	const result = {};
+	for (const base of document_schema_js.SI_BASE_DIMENSIONS) {
+		const exponent = dimensionExponent(dimension, base);
+		if (exponent === 0) continue;
+		const scaled = exponent * k;
+		if (!Number.isInteger(scaled)) throw new RangeError(`dimensions.ts: scaling '${base}' by ${k} does not land on an integer exponent`);
+		result[base] = scaled;
+	}
+	return result;
+}
+function dimensionToString(dimension) {
+	const parts = document_schema_js.SI_BASE_DIMENSIONS.filter((base) => dimensionExponent(dimension, base) !== 0).map((base) => `${base}^${dimensionExponent(dimension, base)}`);
+	return parts.length === 0 ? "dimensionless" : parts.join("·");
+}
+//#endregion
+//#region src/compute/errors.ts
+var IncompatibleDimensionsError = class extends Error {
+	operation;
+	left;
+	right;
+	constructor(operation, left, right, detail) {
+		super(`'${operation}' requires compatible dimensions, got ${dimensionToString(left)} and ${dimensionToString(right)}` + (detail === void 0 ? "." : ` (${detail}).`));
+		this.name = "IncompatibleDimensionsError";
+		this.operation = operation;
+		this.left = left;
+		this.right = right;
+	}
+};
+var UnboundSymbolError = class extends Error {
+	symbol;
+	constructor(symbol) {
+		super(`symbol '${symbol}' has no entry in the supplied bindings.`);
+		this.name = "UnboundSymbolError";
+		this.symbol = symbol;
+	}
+};
+var UnknownUnitError = class extends Error {
+	unit;
+	constructor(unit) {
+		super(`unit '${unit}' is not registered in the supplied symbol table's units.`);
+		this.name = "UnknownUnitError";
+		this.unit = unit;
+	}
+};
+var DivisionByZeroError = class extends Error {
+	operation;
+	constructor(operation, detail) {
+		super(`'${operation}': division by zero (${detail}).`);
+		this.name = "DivisionByZeroError";
+		this.operation = operation;
+	}
+};
+var UnsupportedExpressionError = class extends Error {
+	context;
+	constructor(context, detail) {
+		super(`${context}: ${detail}.`);
+		this.name = "UnsupportedExpressionError";
+		this.context = context;
+	}
+};
+var NumericDomainError = class extends Error {
+	operation;
+	constructor(operation, detail) {
+		super(`'${operation}': ${detail}.`);
+		this.name = "NumericDomainError";
+		this.operation = operation;
+	}
+};
+var NonConvergentSolveError = class extends Error {
+	method;
+	iterations;
+	constructor(method, iterations, detail) {
+		super(`solveFor (${method}) did not converge after ${iterations} iteration(s): ${detail}.`);
+		this.name = "NonConvergentSolveError";
+		this.method = method;
+		this.iterations = iterations;
+	}
+};
+//#endregion
+//#region src/compute/quantity.ts
+function quantity(magnitude, dimension = {}) {
+	return {
+		kind: "quantity",
+		magnitude,
+		dimension
+	};
+}
+function addQuantities(a, b) {
+	if (!dimensionsEqual(a.dimension, b.dimension)) throw new IncompatibleDimensionsError("math:add", a.dimension, b.dimension);
+	return quantity(a.magnitude + b.magnitude, a.dimension);
+}
+function subtractQuantities(a, b) {
+	if (!dimensionsEqual(a.dimension, b.dimension)) throw new IncompatibleDimensionsError("math:subtract", a.dimension, b.dimension);
+	return quantity(a.magnitude - b.magnitude, a.dimension);
+}
+function multiplyQuantities(a, b) {
+	return quantity(a.magnitude * b.magnitude, multiplyDimensions(a.dimension, b.dimension));
+}
+function divideQuantities(a, b) {
+	if (b.magnitude === 0) throw new DivisionByZeroError("math:divide", `divisor magnitude is exactly zero (dividend magnitude ${a.magnitude})`);
+	return quantity(a.magnitude / b.magnitude, divideDimensions(a.dimension, b.dimension));
+}
+function negateQuantity(a) {
+	return quantity(-a.magnitude, a.dimension);
+}
+function absQuantity(a) {
+	return quantity(Math.abs(a.magnitude), a.dimension);
+}
+function powQuantity(base, exponent) {
+	if (!isDimensionless(exponent.dimension)) throw new IncompatibleDimensionsError("math:pow", exponent.dimension, {}, "the exponent must be dimensionless");
+	if (isDimensionless(base.dimension)) return quantity(Math.pow(base.magnitude, exponent.magnitude), {});
+	if (!Number.isInteger(exponent.magnitude)) throw new IncompatibleDimensionsError("math:pow", base.dimension, {}, "a dimensioned base can only be raised to an integer power");
+	return quantity(Math.pow(base.magnitude, exponent.magnitude), scaleDimension(base.dimension, exponent.magnitude));
+}
+function sqrtQuantity(a) {
+	if (a.magnitude < 0) throw new NumericDomainError("math:sqrt", `magnitude must be non-negative, got ${a.magnitude}`);
+	let dimension;
+	try {
+		dimension = scaleDimension(a.dimension, .5);
+	} catch {
+		throw new IncompatibleDimensionsError("math:sqrt", a.dimension, {}, "every exponent must be even for the dimension to have an exact square root");
+	}
+	return quantity(Math.sqrt(a.magnitude), dimension);
+}
+function requireDimensionless(a, operator) {
+	if (!isDimensionless(a.dimension)) throw new IncompatibleDimensionsError(operator, a.dimension, {}, "trigonometric functions take a dimensionless (radian) argument");
+}
+function sinQuantity(a) {
+	requireDimensionless(a, "math:sin");
+	return quantity(Math.sin(a.magnitude), {});
+}
+function cosQuantity(a) {
+	requireDimensionless(a, "math:cos");
+	return quantity(Math.cos(a.magnitude), {});
+}
+function tanQuantity(a) {
+	requireDimensionless(a, "math:tan");
+	return quantity(Math.tan(a.magnitude), {});
+}
+//#endregion
+//#region src/compute/interval.ts
+function interval(min, max, dimension = {}) {
+	if (min > max) throw new RangeError(`interval: min (${min}) must not exceed max (${max})`);
+	return {
+		kind: "interval",
+		min,
+		max,
+		dimension
+	};
+}
+function pointInterval(magnitude, dimension = {}) {
+	return {
+		kind: "interval",
+		min: magnitude,
+		max: magnitude,
+		dimension
+	};
+}
+function addIntervals(a, b) {
+	if (!dimensionsEqual(a.dimension, b.dimension)) throw new IncompatibleDimensionsError("math:add", a.dimension, b.dimension);
+	return interval(a.min + b.min, a.max + b.max, a.dimension);
+}
+function subtractIntervals(a, b) {
+	if (!dimensionsEqual(a.dimension, b.dimension)) throw new IncompatibleDimensionsError("math:subtract", a.dimension, b.dimension);
+	return interval(a.min - b.max, a.max - b.min, a.dimension);
+}
+function multiplyIntervals(a, b) {
+	const corners = [
+		a.min * b.min,
+		a.min * b.max,
+		a.max * b.min,
+		a.max * b.max
+	];
+	return interval(Math.min(...corners), Math.max(...corners), multiplyDimensions(a.dimension, b.dimension));
+}
+function divideIntervals(a, b) {
+	if (b.min <= 0 && b.max >= 0) throw new DivisionByZeroError("math:divide", `divisor interval [${b.min}, ${b.max}] contains zero`);
+	const reciprocalMin = 1 / b.max;
+	const reciprocalMax = 1 / b.min;
+	const corners = [
+		a.min * reciprocalMin,
+		a.min * reciprocalMax,
+		a.max * reciprocalMin,
+		a.max * reciprocalMax
+	];
+	return interval(Math.min(...corners), Math.max(...corners), divideDimensions(a.dimension, b.dimension));
+}
+function negateInterval(a) {
+	return interval(-a.max, -a.min, a.dimension);
+}
+function absInterval(a) {
+	if (a.min >= 0) return a;
+	if (a.max <= 0) return negateInterval(a);
+	return interval(0, Math.max(-a.min, a.max), a.dimension);
+}
+//#endregion
+//#region src/compute/evaluate.ts
+const EMPTY_SYMBOL_TABLE$1 = {
+	symbols: [],
+	units: []
+};
+function isInterval(value) {
+	return value.kind === "interval";
+}
+function toInterval(value) {
+	return isInterval(value) ? value : pointInterval(value.magnitude, value.dimension);
+}
+function asQuantity(value, context) {
+	if (isInterval(value)) throw new UnsupportedExpressionError(context, "this position requires a plain Quantity, not an Interval");
+	return value;
+}
+const BINARY_OPERATORS = {
+	"math:add": {
+		quantity: addQuantities,
+		interval: addIntervals
+	},
+	"math:subtract": {
+		quantity: subtractQuantities,
+		interval: subtractIntervals
+	},
+	"math:multiply": {
+		quantity: multiplyQuantities,
+		interval: multiplyIntervals
+	},
+	"math:divide": {
+		quantity: divideQuantities,
+		interval: divideIntervals
+	}
+};
+const UNARY_OPERATORS = {
+	"math:negate": {
+		quantity: negateQuantity,
+		interval: negateInterval
+	},
+	"math:abs": {
+		quantity: absQuantity,
+		interval: absInterval
+	},
+	"math:sqrt": { quantity: sqrtQuantity },
+	"math:sin": { quantity: sinQuantity },
+	"math:cos": { quantity: cosQuantity },
+	"math:tan": { quantity: tanQuantity }
+};
+function evaluate(expression, bindings, context = EMPTY_SYMBOL_TABLE$1) {
+	switch (expression.kind) {
+		case "num": return quantity(rationalToNumber(toRational(expression)), {});
+		case "qty": return evaluateQty(expression, context);
+		case "sym": {
+			const bound = bindings[expression.id];
+			if (bound === void 0) throw new UnboundSymbolError(expression.id);
+			return bound;
+		}
+		case "app": return evaluateApp(expression, bindings, context);
+		case "sum":
+		case "prod": return evaluateBinder(expression, bindings, context);
+		case "matrix": throw new UnsupportedExpressionError("evaluate", "matrix-valued expressions are out of scope for this pass -- document-compute.js evaluates scalar Quantity/Interval values only");
+		case "unparsed": throw new UnsupportedExpressionError("evaluate", `this node is source LaTeX ("${expression.latex}") document-schema.js's lowering could not represent structurally, so there is nothing to evaluate`);
+	}
+}
+function evaluateQty(node, context) {
+	const unit = context.units.find((entry) => entry.id === node.unit);
+	if (unit === void 0) throw new UnknownUnitError(node.unit);
+	let siValue = multiplyRational(toRational(node.value), toRational(unit.factorToSi));
+	if (unit.offsetToSi !== void 0) siValue = addRational(siValue, toRational(unit.offsetToSi));
+	return quantity(rationalToNumber(siValue), unit.dimension);
+}
+function evaluateApp(node, bindings, context) {
+	const args = node.args.map((arg) => evaluate(arg, bindings, context));
+	const binary = BINARY_OPERATORS[node.operator];
+	if (binary !== void 0) {
+		if (args.length !== 2) throw new UnsupportedExpressionError("evaluate", `operator '${node.operator}' takes exactly 2 arguments, got ${args.length}`);
+		const [left, right] = args;
+		if (isInterval(left) || isInterval(right)) return binary.interval(toInterval(left), toInterval(right));
+		return binary.quantity(left, right);
+	}
+	const unary = UNARY_OPERATORS[node.operator];
+	if (unary !== void 0) {
+		if (args.length !== 1) throw new UnsupportedExpressionError("evaluate", `operator '${node.operator}' takes exactly 1 argument, got ${args.length}`);
+		const [only] = args;
+		if (isInterval(only)) {
+			if (unary.interval === void 0) throw new UnsupportedExpressionError("evaluate", `operator '${node.operator}' has no interval rule in this pass`);
+			return unary.interval(only);
+		}
+		return unary.quantity(only);
+	}
+	if (node.operator === "math:pow") {
+		if (args.length !== 2) throw new UnsupportedExpressionError("evaluate", `'math:pow' takes exactly 2 arguments, got ${args.length}`);
+		const [base, exponent] = args;
+		return powQuantity(asQuantity(base, "evaluate"), asQuantity(exponent, "evaluate"));
+	}
+	throw new UnsupportedExpressionError("evaluate", `unknown operator '${node.operator}'`);
+}
+function evaluateBinder(node, bindings, context) {
+	const lower = asQuantity(evaluate(node.lower, bindings, context), `evaluate:${node.kind}`);
+	const upper = asQuantity(evaluate(node.upper, bindings, context), `evaluate:${node.kind}`);
+	if (!isDimensionless(lower.dimension) || !isDimensionless(upper.dimension)) throw new IncompatibleDimensionsError(`math:${node.kind}`, lower.dimension, upper.dimension, "binder bounds must be dimensionless");
+	if (!Number.isInteger(lower.magnitude) || !Number.isInteger(upper.magnitude)) throw new UnsupportedExpressionError(`evaluate:${node.kind}`, "binder bounds must evaluate to integers");
+	let accumulator = node.kind === "sum" ? quantity(0, {}) : quantity(1, {});
+	for (let i = lower.magnitude; i <= upper.magnitude; i += 1) {
+		const bodyBindings = {
+			...bindings,
+			[node.binder]: quantity(i, {})
+		};
+		const bodyValue = asQuantity(evaluate(node.body, bodyBindings, context), `evaluate:${node.kind}`);
+		accumulator = node.kind === "sum" ? addQuantities(accumulator, bodyValue) : multiplyQuantities(accumulator, bodyValue);
+	}
+	return accumulator;
+}
+//#endregion
+//#region src/compute/solve.ts
+const DEFAULT_TOLERANCE = 1e-9;
+const DEFAULT_MAX_ITERATIONS = 100;
+const DEFAULT_DERIVATIVE_STEP = 1e-6;
+const EMPTY_SYMBOL_TABLE = {
+	symbols: [],
+	units: []
+};
+function residualFn(expression, targetValue, unknownSymbol, bindings, context, dimension) {
+	return (x) => {
+		const result = evaluate(expression, {
+			...bindings,
+			[unknownSymbol]: quantity(x, dimension)
+		}, context);
+		if (result.kind !== "quantity") throw new UnsupportedExpressionError("solveFor", "the expression must evaluate to a plain Quantity, not an Interval");
+		return result.magnitude - targetValue;
+	};
+}
+function solveFor(expression, targetValue, unknownSymbol, bindings, options = {}, context = EMPTY_SYMBOL_TABLE) {
+	const method = options.method ?? "bisection";
+	const tolerance = options.tolerance ?? DEFAULT_TOLERANCE;
+	const maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+	const f = residualFn(expression, targetValue, unknownSymbol, bindings, context, options.unknownDimension ?? {});
+	if (method === "bisection") return bisection(f, options.bracket, tolerance, maxIterations);
+	return newton(f, options.initialGuess, tolerance, maxIterations, options.derivativeStep ?? DEFAULT_DERIVATIVE_STEP);
+}
+function bisection(f, bracket, tolerance, maxIterations) {
+	if (bracket === void 0) throw new UnsupportedExpressionError("solveFor", "method 'bisection' requires options.bracket: [low, high]");
+	let [low, high] = bracket;
+	let fLow = f(low);
+	const fHigh0 = f(high);
+	if (Math.abs(fLow) < tolerance) return low;
+	if (Math.abs(fHigh0) < tolerance) return high;
+	if (fLow > 0 === fHigh0 > 0) throw new NonConvergentSolveError("bisection", 0, `residual at the bracket endpoints does not change sign (f(${low})=${fLow}, f(${high})=${fHigh0}) -- bisection needs a bracket straddling the root`);
+	for (let i = 0; i < maxIterations; i += 1) {
+		const mid = (low + high) / 2;
+		const fMid = f(mid);
+		if (Math.abs(fMid) < tolerance) return mid;
+		if (fMid > 0 === fLow > 0) {
+			low = mid;
+			fLow = fMid;
+		} else high = mid;
+	}
+	throw new NonConvergentSolveError("bisection", maxIterations, `residual still exceeds tolerance ${tolerance} after ${maxIterations} iterations`);
+}
+function newton(f, initialGuess, tolerance, maxIterations, h) {
+	if (initialGuess === void 0) throw new UnsupportedExpressionError("solveFor", "method 'newton' requires options.initialGuess");
+	let x = initialGuess;
+	for (let i = 0; i < maxIterations; i += 1) {
+		const fx = f(x);
+		if (Math.abs(fx) < tolerance) return x;
+		const derivative = (f(x + h) - f(x - h)) / (2 * h);
+		if (!Number.isFinite(derivative) || Math.abs(derivative) < 1e-14) throw new NonConvergentSolveError("newton", i, `the numeric derivative vanished or diverged near x=${x}`);
+		const next = x - fx / derivative;
+		if (!Number.isFinite(next)) throw new NonConvergentSolveError("newton", i, `the iteration diverged to a non-finite value near x=${x}`);
+		x = next;
+	}
+	throw new NonConvergentSolveError("newton", maxIterations, `residual still exceeds tolerance ${tolerance} after ${maxIterations} iterations`);
+}
+//#endregion
+exports.DivisionByZeroError = DivisionByZeroError;
+exports.IncompatibleDimensionsError = IncompatibleDimensionsError;
+exports.NonConvergentSolveError = NonConvergentSolveError;
+exports.NumericDomainError = NumericDomainError;
+exports.UnboundSymbolError = UnboundSymbolError;
+exports.UnknownUnitError = UnknownUnitError;
+exports.UnsupportedExpressionError = UnsupportedExpressionError;
+exports.absInterval = absInterval;
+exports.absQuantity = absQuantity;
+exports.addIntervals = addIntervals;
+exports.addQuantities = addQuantities;
+exports.addRational = addRational;
+exports.cosQuantity = cosQuantity;
+exports.dimensionExponent = dimensionExponent;
+exports.dimensionToString = dimensionToString;
+exports.dimensionsEqual = dimensionsEqual;
+exports.divideDimensions = divideDimensions;
+exports.divideIntervals = divideIntervals;
+exports.divideQuantities = divideQuantities;
+exports.divideRational = divideRational;
+exports.evaluate = evaluate;
+exports.interval = interval;
+exports.isDimensionless = isDimensionless;
+exports.isInterval = isInterval;
+exports.multiplyDimensions = multiplyDimensions;
+exports.multiplyIntervals = multiplyIntervals;
+exports.multiplyQuantities = multiplyQuantities;
+exports.multiplyRational = multiplyRational;
+exports.negateInterval = negateInterval;
+exports.negateQuantity = negateQuantity;
+exports.pointInterval = pointInterval;
+exports.powQuantity = powQuantity;
+exports.quantity = quantity;
+exports.rationalToNumber = rationalToNumber;
+exports.scaleDimension = scaleDimension;
+exports.sinQuantity = sinQuantity;
+exports.solveFor = solveFor;
+exports.sqrtQuantity = sqrtQuantity;
+exports.subtractIntervals = subtractIntervals;
+exports.subtractQuantities = subtractQuantities;
+exports.subtractRational = subtractRational;
+exports.tanQuantity = tanQuantity;
+exports.toExactRational = toExactRational;
+exports.toRational = toRational;