@cyanheads/calculator-mcp-server 0.4.3 → 0.5.0

package/dist/services/math/math-service.js

@@ -1,12 +1,15 @@
 /**
  * @fileoverview Hardened math.js wrapper for secure expression evaluation.
  * Creates a restricted math.js instance with dangerous functions disabled in
- * the expression scope, and wraps evaluation in a vm sandbox with timeout.
+ * the expression scope, parses each expression once and checks the tree before
+ * anything runs, and evaluates, inspects, and formats the result inside a vm
+ * sandbox with a timeout.
  * @module services/math/math-service
  */
 import vm from 'node:vm';
-import { timeout, validationError } from '@cyanheads/mcp-ts-core/errors';
-import { all, create } from 'mathjs';
+import { McpError, timeout, validationError } from '@cyanheads/mcp-ts-core/errors';
+import { all, create, isBigNumber, isComplex, isHelp, isMatrix, isSparseMatrix, isUnit, } from 'mathjs';
+import { beginEvaluation, installSizeGuards, isPlainObject, meterNode, sizeLimitErrorIn, } from './size-guard.js';
 /**
  * Custom simplification rules extending math.js defaults.
  * math.js ships with algebraic rules only — these add common trig identities.
@@ -43,6 +46,7 @@ const CUSTOM_UNITS = {
  * Functions disabled in the expression scope for security.
  * These are overridden via math.import() — expressions cannot call them.
  * simplify/derivative are called programmatically by the tool handler, not from expressions.
+ * `config` is not listed: it gets a read-only guard instead (see createMathInstance).
  */
 const DISABLED_FUNCTIONS = [
     'import',
@@ -55,7 +59,6 @@ const DISABLED_FUNCTIONS = [
     'reviver',
     'compile',
     'chain',
-    'config',
     'parser',
 ];
 /**
@@ -81,17 +84,92 @@ const BLOCKED_RESULT_TYPES = new Set(['function', 'Function', 'ResultSet', 'Pars
  * accessor: `.toString()` / `.toLocaleString()` on a function-valued identifier
  * (e.g. `cos.toString()`) otherwise returns internal source as a plain string,
  * slipping past {@link BLOCKED_RESULT_TYPES} (which only sees the value after
- * stringification). See {@link MathService.validateNoFunctionStringification}.
+ * stringification). See {@link inspectTree}.
  */
 const STRINGIFYING_METHODS = new Set(['toString', 'toLocaleString']);
 /**
- * math.js error thrown when a Fraction-mode expression yields a value that has
- * no exact rational representation (`sqrt`, `sin`, `log`, …). math.js reports it
- * as an implicit type-conversion failure; paired with a `numericType === 'Fraction'`
- * guard it maps to the actionable `fraction_unsupported` error instead of the
- * misleading, syntax-oriented `parse_failed`. See {@link MathService.runWithTimeout}.
+ * The tool's `operation` values. Each is also a disabled function name, so a
+ * call such as `derivative("x^2", "x")` inside an expression is a caller asking
+ * for the operation the wrong way — rejected at parse time with a pointer to the
+ * `operation` parameter rather than the generic disabled-function message.
+ */
+const OPERATION_FUNCTIONS = new Set(['evaluate', 'simplify', 'derivative']);
+/**
+ * Standard-notation function names math.js does not define — natural log `ln`
+ * and the inverse-trig `arc*` family. Renamed on the parse tree (see
+ * {@link inspectTree}) to their math.js builtins.
+ */
+const NOTATION_ALIAS = /^(?:ln|arc(?:sin|cos|tan|sec|csc|cot)h?)$/;
+/**
+ * Node types that compute a new value — a call, an operator, a matrix or object
+ * literal, an indexed read, a range. Each is metered against the evaluation's
+ * element budget; the rest (symbols, constants, parentheses, assignments,
+ * conditionals) pass along a value some other node built.
+ */
+const VALUE_BUILDING_NODES = new Set([
+    'AccessorNode',
+    'ArrayNode',
+    'FunctionNode',
+    'ObjectNode',
+    'OperatorNode',
+    'RangeNode',
+]);
+/**
+ * Lower bound on the characters one element of a collection result renders to:
+ * at least one character plus the `, ` separator (a one-element matrix, `[0]`,
+ * is three). A result with more than `maxResultLength / 3` elements can never
+ * fit, so it is rejected before formatting.
+ */
+const MIN_CHARS_PER_ELEMENT = 3;
+/**
+ * math.js error thrown when a Fraction-mode expression calls a function with no
+ * Fraction implementation: irrational and transcendental ones (`sqrt`, `sin`,
+ * `log`, …) and some whose result can be rational (`sqrt(4)`, `5!`,
+ * `combinations`). math.js reports it as an implicit type-conversion failure that
+ * does not name the function; paired with a `numericType === 'Fraction'` guard it
+ * maps to the actionable `fraction_unsupported` error instead of the misleading,
+ * syntax-oriented `parse_failed`. See {@link MathService.classifyFailure}.
  */
 const FRACTION_CONVERSION_ERROR = /Cannot implicitly convert a Fraction/;
+/**
+ * math.js error thrown when a 64-bit float meets a Fraction and has no Fraction
+ * equal to it — `pi * 2/3`, `pi^40`, `sin(pi) + 1/3`. Under numericType
+ * "Fraction" the float can only have come from a value Fraction mode holds
+ * approximately, so it maps to `fraction_unsupported`, not `type_mismatch`.
+ */
+const FLOAT_TO_FRACTION_ERROR = /^Cannot implicitly convert a number to a Fraction when there will be a loss of precision/;
+/** `fraction_unsupported` message for a function Fraction mode cannot compute. */
+const FRACTION_FUNCTION_MESSAGE = 'numericType "Fraction" cannot compute this expression: either its result has no exact rational value (e.g. sqrt(2), sin(1), log(3)), or it calls a function Fraction mode cannot compute, even for a rational result (e.g. sqrt(4), 5!, combinations(5, 2)). Retry with numericType "number" or "BigNumber".';
+/** `undefined_result` message: a non-finite value, or a Fraction division by zero. */
+const UNDEFINED_RESULT_MESSAGE = 'Expression evaluated to a non-finite result (Infinity, -Infinity, or NaN): either the operation is mathematically undefined (division by zero, 0/0, log(0)), or a value overflowed its numeric range (under numericType "number", past about 1.8e308 — e.g. 171!, 2^1024, exp(1000)).';
+/** `fraction_unsupported` message for a Fraction-mode evaluation that picked up a float. */
+const FRACTION_FLOAT_MESSAGE = 'numericType "Fraction" cannot return this result exactly: the expression uses a value Fraction mode holds only as a rounded 64-bit float — an irrational constant (pi, e), a non-integer power (2^(1/2)), a complex number with a non-integer part, or a float from number() or random(). Retry with numericType "number" or "BigNumber".';
+/** math.js derivative error for a function or operator it has no differentiation rule for. */
+const NO_DERIVATIVE_RULE = /^Cannot process (function|operator) "([^"]+)" in derivative/;
+/**
+ * Unit names math.js resolves to a function first — `5 min` multiplies by the
+ * minimum function — paired with a unit name to write instead.
+ */
+const FUNCTION_SHADOWED_UNITS = { min: 'minute', sec: 's' };
+/** Message of the vm timeout error (`ERR_SCRIPT_EXECUTION_TIMEOUT`), also when re-wrapped. */
+const VM_TIMEOUT_ERROR = /Script execution timed out after/;
+/**
+ * fraction.js throws this for any Fraction division by zero — reachable in every
+ * numericType through `fraction()`. Fractions never hold Infinity, so it is the
+ * Fraction form of a non-finite result and maps to `undefined_result`.
+ */
+const FRACTION_DIVISION_BY_ZERO = /^Division by Zero$/;
+/**
+ * Evaluation-time errors that are about the expression's names rather than its
+ * values: an undefined symbol, function, or unit, a disabled function, or a
+ * blocked property. They stay `parse_failed`, whose recovery is about names.
+ */
+const NAME_ERROR = /^(?:Undefined (?:symbol|function) |Unit ".*" not found|No access to )|is disabled for security\.$/;
+/**
+ * Operand type and unit errors that math.js raises as plain messages (typed-function
+ * `wrongType` errors are recognized by `data.category` instead).
+ */
+const TYPE_MISMATCH_ERROR = /^(?:Units do not match|Cannot convert |Cannot implicitly convert )|is no angle$/;
 /**
  * Scope key names that could pollute the object prototype chain or shadow
  * critical Object.prototype methods. Validated before passing to math.js.
@@ -112,96 +190,262 @@ const BLOCKED_SCOPE_KEYS = new Set([
     'toLocaleString',
 ]);
 /**
- * Check for expression separators (`;` or newline) that split the input into
- * multiple statements. Three contexts are NOT separators and are skipped:
- *  - `;` inside `[...]` — a matrix row separator (`[1, 2; 3, 4]`).
- *  - `;` or a newline inside a double-quoted string literal — part of the data,
- *    not a statement break (`"a;b"`, `concat("a;b", "c")`).
- *  - `[` / `]` inside a string literal — they must not shift the bracket depth,
- *    or a string such as `"]"` would let a later top-level `;` slip past.
+ * Walk a freshly parsed tree once: flag stringifier access and operation-named
+ * calls, collect the names used as values, meter every value-building node against the element budget (so a node
+ * in a loop body — a user-defined function or an inline `map` callback — is
+ * charged on each iteration), and rename standard-notation calls in place —
+ * `ln` → `log`, `arc<fn>` → `a<fn>` (`arcsin` → `asin`, `arctanh` → `atanh`, …).
  *
- * Single quotes are NOT string delimiters in math.js — `'` is the transpose
- * operator (`A'`) — so only `"` opens a string span, and a backslash escapes the
- * next character within it (`"\""` stays open). The scan is intentionally
- * lexical rather than a full parse: it only has to recognize quoted spans, and a
- * genuine multi-statement input (`1+2; 3+4`) is still caught at depth 0.
+ * The rename works on `FunctionNode`s whose callee is a `SymbolNode`, so string
+ * literals (`"ln("` is a `ConstantNode`) and scope variables named `ln` (a bare
+ * `SymbolNode`) are never touched, and nested calls are reached because the walk
+ * covers every node. It is name-level rather than a `math.import` alias because
+ * symbolic `derivative` matches builtin names — an imported alias is not in its
+ * differentiation table. The tree is evaluated as-is afterwards, never
+ * re-stringified: a Fraction-mode tree prints `0.1` as `1/10`.
  */
-function hasExpressionSeparator(expr) {
-    let depth = 0;
-    let inString = false;
-    for (let i = 0; i < expr.length; i++) {
-        const ch = expr[i];
-        if (inString) {
-            if (ch === '\\')
-                i++;
-            else if (ch === '"')
-                inString = false;
-            continue;
+function inspectTree(tree) {
+    const inspection = {
+        stringifies: false,
+        operationCall: undefined,
+        valueNames: new Set(),
+    };
+    tree.traverse((node, path) => {
+        if (VALUE_BUILDING_NODES.has(node.type))
+            meterNode(node);
+        if (node.type === 'SymbolNode' && path !== 'fn') {
+            inspection.valueNames.add(node.name);
         }
-        if (ch === '"')
-            inString = true;
-        else if (ch === '[')
-            depth++;
-        else if (ch === ']')
-            depth--;
-        else if (ch === '\n' || ch === '\r')
-            return true;
-        else if (ch === ';' && depth === 0)
-            return true;
-    }
+        if (node.type === 'IndexNode') {
+            const { dimensions } = node;
+            if (dimensions.some((dim) => dim.type === 'ConstantNode' &&
+                STRINGIFYING_METHODS.has(String(dim.value)))) {
+                inspection.stringifies = true;
+            }
+            return;
+        }
+        if (node.type !== 'FunctionNode')
+            return;
+        const callee = node.fn;
+        if (callee.type !== 'SymbolNode' || callee.name === undefined)
+            return;
+        if (OPERATION_FUNCTIONS.has(callee.name)) {
+            inspection.operationCall ??= callee.name;
+        }
+        else if (NOTATION_ALIAS.test(callee.name)) {
+            callee.name = callee.name === 'ln' ? 'log' : `a${callee.name.slice(3)}`;
+        }
+    });
+    return inspection;
+}
+/** Whether a scalar math.js value is Infinity, -Infinity, or NaN. */
+function isNonFiniteScalar(value) {
+    if (typeof value === 'number')
+        return !Number.isFinite(value);
+    if (isBigNumber(value))
+        return !value.isFinite();
+    if (isComplex(value))
+        return isNonFiniteScalar(value.re) || isNonFiniteScalar(value.im);
     return false;
 }
 /**
- * Recursively test whether a math.js result holds any non-finite number
- * (Infinity, -Infinity, NaN). The `undefined_result` guard must reach inside
- * compound types: a `DenseMatrix`/`SparseMatrix` element or the real/imaginary
- * part of a `Complex` can be non-finite while the outer value is an object — a
- * scalar `typeof === 'number'` check would skip it and leak `Infinity` to clients.
+ * Whether a scalar is a 64-bit float that need not be the exact value: a
+ * `number`, or a `Complex` part, that is not a safe integer. Under numericType
+ * "Fraction" an exact value is a Fraction or a whole-number count (`count`,
+ * `size`), so such a float came from an irrational constant, a non-integer
+ * power, complex arithmetic, or an explicit float conversion. The test is
+ * safe-integer rather than integer because every double past 2^53 is an integer.
+ * A `BigNumber` only appears when an expression asks for one (`bignumber(x)`),
+ * and a `Unit` is judged by its magnitude.
  */
-function containsNonFinite(value) {
+function isFloatApproximation(value) {
     if (typeof value === 'number')
-        return !Number.isFinite(value);
-    if (value === null || typeof value !== 'object')
-        return false;
-    if (Array.isArray(value))
-        return value.some(containsNonFinite);
-    // Complex: re/im are plain numbers.
-    if ('re' in value && 'im' in value) {
-        return containsNonFinite(value.re) || containsNonFinite(value.im);
+        return !Number.isSafeInteger(value);
+    if (isComplex(value))
+        return isFloatApproximation(value.re) || isFloatApproximation(value.im);
+    return false;
+}
+/** Record a scalar's non-finite and float-approximation findings on the scan. */
+function scanScalar(value, scan) {
+    if (isNonFiniteScalar(value))
+        scan.nonFinite = true;
+    if (scan.exactOnly && isFloatApproximation(value))
+        scan.inexact = true;
+}
+/**
+ * Walk a result once, counting leaf elements (stopping past `limit`) and flagging
+ * `help()` objects, non-finite numbers, and — with `exactOnly` — float
+ * approximations. The number checks reach every container a result can nest a
+ * number in — matrix elements (dense data, or a sparse matrix's stored values,
+ * never densified), `Complex` parts, a `Unit`'s magnitude, `BigNumber`s, and
+ * object-literal values. `Fraction`s are always finite (fraction.js throws
+ * instead of producing Infinity) and always exact.
+ */
+function scanResult(value, limit, scan) {
+    if (scan.elements > limit)
+        return;
+    if (value === null || typeof value !== 'object') {
+        scan.elements++;
+        scanScalar(value, scan);
+        return;
     }
-    // DenseMatrix / SparseMatrix expose toArray() → nested JS arrays.
-    if (typeof value.toArray === 'function') {
-        return containsNonFinite(value.toArray());
+    if (isHelp(value)) {
+        scan.elements++;
+        scan.help = true;
+        return;
     }
-    return false;
+    if (isSparseMatrix(value)) {
+        scanResult(value._values ?? [], limit, scan);
+        return;
+    }
+    if (isMatrix(value)) {
+        const size = value.size();
+        if (size.reduce((n, d) => n * d, 1) > limit) {
+            scan.elements = limit + 1;
+            return;
+        }
+        scanResult(value.valueOf(), limit, scan);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            scanResult(item, limit, scan);
+            if (scan.elements > limit)
+                return;
+        }
+        return;
+    }
+    if (isUnit(value)) {
+        scan.elements++;
+        scanScalar(value.value, scan);
+        return;
+    }
+    // BigNumber, Complex, Fraction, and other class instances are scalars.
+    if (!isPlainObject(value)) {
+        scan.elements++;
+        scanScalar(value, scan);
+        return;
+    }
+    for (const item of Object.values(value)) {
+        scanResult(item, limit, scan);
+        if (scan.elements > limit)
+            return;
+    }
+}
+/** Script every timed call runs in the service's reused vm context. */
+const TIMED_CALL = new vm.Script('result = fn()');
+/**
+ * Largest decimal exponent a Fraction-mode literal may carry. `1e1000` already
+ * spells out a 1001-digit integer; past this, an exponent only builds numbers too
+ * large to return, so it fails fast instead of allocating.
+ */
+const MAX_FRACTION_LITERAL_EXPONENT = 1000;
+/** A decimal literal in exponent notation: mantissa digits, fraction digits, exponent. */
+const EXPONENT_LITERAL = /^(\d*)(?:\.(\d*))?[eE]([+-]?\d+)$/;
+/**
+ * Rewrite an exponent-notation literal as the plain decimal it denotes
+ * (`1.5e-3` → `0.0015`), which fraction.js reads exactly. Returns `undefined`
+ * for anything that is not exponent notation.
+ */
+function expandExponentLiteral(literal) {
+    const match = EXPONENT_LITERAL.exec(literal);
+    if (!match)
+        return undefined;
+    const [, whole = '', fraction = '', exponentText = '0'] = match;
+    const exponent = Number(exponentText);
+    if (Math.abs(exponent) > MAX_FRACTION_LITERAL_EXPONENT) {
+        throw new SyntaxError(`Exponent literal "${literal}" is out of range for numericType "Fraction" (exponents up to ±${MAX_FRACTION_LITERAL_EXPONENT}); use numericType "BigNumber" for numbers this large or small.`);
+    }
+    const digits = whole + fraction;
+    const point = whole.length + exponent;
+    if (point <= 0)
+        return `0.${'0'.repeat(-point)}${digits}`;
+    if (point >= digits.length)
+        return digits + '0'.repeat(point - digits.length);
+    return `${digits.slice(0, point)}.${digits.slice(point)}`;
 }
 /**
- * Matches standard-notation function names math.js does not define — natural log
- * `ln` and the inverse-trig `arc*` family — only at call sites (word boundary +
- * `(` lookahead), so identifiers and scope variables are never rewritten.
+ * Let a Fraction instance read exponent-notation literals exactly. `numeric` is
+ * what the parser uses to turn a literal into a value; for a Fraction target, an
+ * exponent literal is expanded to plain decimal first. Every other conversion is
+ * passed through unchanged.
  */
-const NOTATION_ALIAS_PATTERN = /\b(ln|arc(?:sin|cos|tan|sec|csc|cot)h?)(?=\s*\()/g;
+function installExponentLiterals(math, mathImport) {
+    const numeric = math.numeric.bind(math);
+    const exactNumeric = (value, outputType) => {
+        const expanded = outputType === 'Fraction' && typeof value === 'string'
+            ? expandExponentLiteral(value)
+            : undefined;
+        return numeric(expanded ?? value, outputType);
+    };
+    mathImport({ numeric: exactNumeric }, { override: true });
+}
+/**
+ * Read Fraction-mode scope values the way the instance's own arithmetic does:
+ * math.js converts a number to a Fraction implicitly when the Fraction equals it
+ * exactly (0.5 → 1/2, 0.1 → 1/10), so `x + 0` already reads 0.5 as 1/2. Applying
+ * that rule up front makes a bare `x` read the same. A number with no equal
+ * Fraction stays a float, which the result scan then rejects.
+ */
+function fractionScopeValue(fraction) {
+    return (value) => {
+        const exact = fraction(value);
+        return exact.valueOf() === value ? exact : value;
+    };
+}
 /**
- * Rewrite standard mathematical notation to math.js canonical names before
- * parsing: `ln` → `log` (natural log) and `arc<fn>` → `a<fn>` for inverse trig
- * (`arcsin` → `asin`, `arctanh` → `atanh`, …). All 12 `a*` targets are math.js
- * builtins, so every operation resolves them.
+ * Register {@link CUSTOM_UNITS} without changing how other results simplify, and
+ * return a function that resets the instance's auto unit system.
  *
- * The rewrite is name-level (not a `math.import` alias) deliberately: symbolic
- * `derivative` matches on builtin function names, and an imported alias is not in
- * its differentiation table — so an alias would fix evaluate/simplify but leave
- * `derivative('ln(x)')` throwing. A pre-parse rewrite covers all three operations.
+ * math.js simplifies a combined result (`10 m / 2 s`) through its "auto" unit
+ * system: one unit per base dimension, overwritten by every unit it parses. That
+ * state lives on the instance, so it leaked between calls, and `createUnit`
+ * disturbed it three ways. A unit whose dimensions match no base unit (a velocity)
+ * got a base of its own (`mph_STUFF`), so every velocity then simplified to mph or
+ * knot. A unit with a base enters the auto system whenever it is parsed, so a
+ * `lightyear` elsewhere turned length results into `ly`. And parsing the
+ * definitions re-seeded the system (`hour` as the time unit). So the new base is
+ * removed, the custom units lose their base (they keep their dimensions, so
+ * conversions and unit checks are unchanged), and the auto system is reset to its
+ * seed before every call (#37).
  */
-function normalizeNotation(expression) {
-    return expression.replace(NOTATION_ALIAS_PATTERN, (name) => name === 'ln' ? 'log' : `a${name.slice(3)}`);
+function registerCustomUnits(math) {
+    const registry = math.Unit;
+    const auto = registry.UNIT_SYSTEMS.auto;
+    const seed = { ...auto };
+    const bases = new Set(Object.keys(registry.BASE_UNITS));
+    const units = new Set(Object.keys(registry.UNITS));
+    math.createUnit(CUSTOM_UNITS);
+    for (const key of Object.keys(registry.BASE_UNITS)) {
+        if (bases.has(key))
+            continue;
+        delete registry.BASE_UNITS[key];
+        for (const system of Object.values(registry.UNIT_SYSTEMS))
+            delete system[key];
+    }
+    for (const [name, unit] of Object.entries(registry.UNITS)) {
+        if (!units.has(name))
+            delete unit.base;
+    }
+    return () => {
+        for (const key of Object.keys(auto))
+            delete auto[key];
+        Object.assign(auto, seed);
+    };
 }
 /** Create and harden a math.js instance with the given numeric type. */
 function createMathInstance(number) {
     // biome-ignore lint/style/noNonNullAssertion: math.js types declare `all` as potentially undefined, but it's always defined at runtime
     const math = create(all, { number });
+    // Capture math.import before it's disabled — needed for the imports and guards below.
+    const mathImport = math.import.bind(math);
+    // fraction.js cannot read exponent notation, so a Fraction-mode literal such as
+    // `2e5` fails to parse. The parser converts literals through `numeric`, which it
+    // captures when first created — so the override must precede the `parse` capture.
+    if (number === 'Fraction')
+        installExponentLiterals(math, mathImport);
     // Capture references BEFORE the override step — the import shim replaces these
     // on the instance, so binding after would capture the disabled stubs.
-    const evaluate = math.evaluate.bind(math);
     const format = math.format.bind(math);
     const typeOf = math.typeOf.bind(math);
     // Symbolic operations are captured here too so a hardened instance can back
@@ -212,23 +456,24 @@ function createMathInstance(number) {
     const simplify = math.simplify.bind(math);
     const derivative = math.derivative.bind(math);
     const simplifyRules = [...math.simplify.rules];
-    // Capture math.import before it's disabled — needed to install the config guard below.
-    const mathImport = math.import.bind(math);
-    // For BigNumber/Fraction instances, also capture config before the override.
-    // math.js BigNumber arithmetic reads config() internally to get the Decimal.js precision.
-    // Replacing config with a throwing stub breaks that and causes:
-    //   [DecimalError] Invalid argument: precision: NaN
-    // Instead, we install a read-only guard after the disable step: reads pass through,
-    // writes throw — blocking expression-scope config mutations while preserving internal access.
-    const realConfig = number !== 'number' ? math.config.bind(math) : null;
+    const scopeValue = number === 'Fraction' ? fractionScopeValue(math.fraction.bind(math)) : (value) => value;
+    // Read the config before the override (an empty options object changes nothing).
+    // math.js injects `config` into every factory it instantiates lazily, and reads it
+    // both as a call (config()) and as properties (config.relTol, config.precision). A
+    // throwing stub breaks those readers — BigNumber arithmetic fails with
+    // `[DecimalError] precision: NaN`, and number-mode functions created after the
+    // override (eigs, schur, intersect, isPositive, compare, …) see `relTol`/`absTol` as
+    // undefined (#25). Every instance therefore gets a read-only guard (installed
+    // below): reads pass through, writes throw.
+    const currentConfig = math.config({});
     // Register custom units and function-name aliases (natural-language plus common
     // cross-ecosystem synonyms from Excel/NumPy/calculator notation). None are math.js
     // builtins, so the imports are purely additive — they turn an agent's natural guess
     // into a result instead of an "undefined function" error. Statistics/combinatorics
     // functions aren't differentiable, so a value-alias suffices (unlike ln/arc*, which
-    // need the pre-parse rewrite to stay in the derivative table).
+    // are renamed on the parse tree to stay in the derivative table — see inspectTree).
     // Must run before createUnit/import are disabled below.
-    math.createUnit(CUSTOM_UNITS);
+    const resetUnitSystem = registerCustomUnits(math);
     mathImport({
         average: math.mean,
         avg: math.mean,
@@ -241,55 +486,63 @@ function createMathInstance(number) {
         length: math.count,
         len: math.count,
     });
-    // Disable dangerous functions in expression scope.
-    // `config` is excluded here for BigNumber/Fraction instances — installed as a
-    // read-only guard via mathImport after this block (import is also disabled here).
-    const disabled = {};
-    for (const fn of DISABLED_FUNCTIONS) {
-        if (fn === 'config' && number !== 'number')
-            continue; // read-only guard installed below
-        disabled[fn] = () => {
-            throw new Error(`Function "${fn}" is disabled for security.`);
-        };
-    }
-    // Redact constants that leak implementation details
-    for (const [key, value] of Object.entries(REDACTED_CONSTANTS)) {
-        disabled[key] = value;
-    }
-    mathImport(disabled, { override: true });
-    // For BigNumber/Fraction: install a read-only config guard using the pre-captured
-    // mathImport reference (math.import is now disabled in the expression scope).
-    //
-    // Two access patterns must be preserved for math.js internals:
+    // Bound what an expression can build from a size argument, a product, a broadcast,
+    // a repeated input, an index, or a formatting precision. Installed on the instance,
+    // so simplify/derivative constant folding on this instance hits the same limits.
+    installSizeGuards(math, mathImport, all);
+    // Replace `config` with a read-only guard. Two access patterns must be preserved
+    // for math.js internals:
     //   1. config()          — gamma/factorial call this to read the full config object
-    //   2. config.precision  — gamma accesses precision directly as a property on the function
+    //   2. config.precision  — gamma accesses precision directly as a property on the
+    //      function; eigs, intersect, compare, … read config.relTol / config.absTol
     //
     // Replacing config with a plain stub breaks both; the guard function below satisfies
     // both patterns while blocking write access (calls with a non-empty options object).
-    if (realConfig !== null) {
-        const currentConfig = realConfig({});
-        const configGuard = Object.assign((options) => {
-            if (options !== undefined && Object.keys(options).length > 0) {
-                throw new Error('"config" is disabled for security.');
-            }
-            return currentConfig;
-        }, currentConfig);
-        mathImport({ config: configGuard }, { override: true });
+    // A bare `config()` from an expression therefore returns the config object — a fresh
+    // copy each call, as stock math.js does: the instance outlives the request, and an
+    // expression can assign into a plain object it holds (`c.k = …` after `c = config()`).
+    const configGuard = Object.assign((options) => {
+        if (options !== undefined && Object.keys(options).length > 0) {
+            throw new Error('"config" is disabled for security.');
+        }
+        return { ...currentConfig };
+    }, currentConfig);
+    // Disable dangerous functions and redact constants that leak implementation details,
+    // through the pre-captured import (this step disables math.import too).
+    const overrides = { ...REDACTED_CONSTANTS, config: configGuard };
+    for (const fn of DISABLED_FUNCTIONS) {
+        overrides[fn] = () => {
+            throw new Error(`Function "${fn}" is disabled for security.`);
+        };
     }
-    return { evaluate, format, typeOf, parse, simplify, derivative, simplifyRules };
+    mathImport(overrides, { override: true });
+    // The namespace an expression's names resolve in (before units), transforms included.
+    const expressionNames = math.expression.mathWithTransform;
+    return {
+        format,
+        typeOf,
+        parse,
+        isFunction: (name) => Object.hasOwn(expressionNames, name) && typeof expressionNames[name] === 'function',
+        resetUnitSystem,
+        scopeValue,
+        simplify: simplify,
+        derivative: derivative,
+        simplifyRules,
+    };
 }
 export class MathService {
     /** Default IEEE 754 instance — used for the vast majority of evaluations. */
     defaultInstance;
-    /** BigNumber instance — arbitrary precision; selected via numericType: "BigNumber". */
+    /** BigNumber instance — 64 significant digits; selected via numericType: "BigNumber". */
     bigNumberInstance;
     /** Fraction instance — exact rational arithmetic; selected via numericType: "Fraction". */
     fractionInstance;
-    parse;
     simplify;
     derivative;
     simplifyRules;
     config;
+    /** vm context reused by every timed call; see {@link runWithTimeout}. */
+    sandbox = vm.createContext({});
     constructor(config) {
         this.config = config;
         // Pre-initialize one hardened instance per numeric type so numeric-type selection
@@ -303,7 +556,6 @@ export class MathService {
         // simplify/derivative resolves disabled functions to their throwing stubs and reads
         // the redacted `version` — closing the bypass where folded `evaluate("…")` ran on an
         // unhardened instance (#18).
-        this.parse = this.defaultInstance.parse;
         this.simplify = this.defaultInstance.simplify;
         this.derivative = this.defaultInstance.derivative;
         this.simplifyRules = [...this.defaultInstance.simplifyRules, ...TRIG_SIMPLIFY_RULES];
@@ -324,56 +576,57 @@ export class MathService {
         this.validateInput(expression, ctx);
         if (scope)
             this.validateScope(scope, ctx);
-        const normalized = normalizeNotation(expression);
-        this.validateNoFunctionStringification(normalized, ctx);
         const inst = this.instanceFor(numericType);
-        const raw = this.runWithTimeout(() => (scope ? inst.evaluate(normalized, scope) : inst.evaluate(normalized)), ctx, numericType);
-        const resultType = inst.typeOf(raw);
-        this.validateResultType(resultType, ctx);
-        this.validateFinite(raw, ctx);
-        // Match JS Number.toString thresholds — math.js defaults to exp ≥ 5,
-        // which would render 83810205 as "8.3810205e+7".
-        const result = inst.format(raw, {
-            lowerExp: -6,
-            upperExp: 21,
-            ...(precision != null && { precision }),
+        // Parse with the instance for the requested numericType: constant nodes take
+        // their numeric type at parse time.
+        const { tree, functionValues } = this.parseExpression(expression, inst, ctx);
+        // Evaluation, result inspection, and formatting all run inside the timeout, so
+        // no result reaches formatting unchecked and no step runs unbounded (#31).
+        return this.runWithTimeout(() => {
+            // Evaluate against a copy: an assignment in the expression (`(y = 2) + x`)
+            // writes into the scope it is given, and the caller's object must not change (#34).
+            const variables = Object.entries(scope ?? {}).map(([name, value]) => [name, inst.scopeValue(value)]);
+            const raw = tree.compile().evaluate(new Map(variables));
+            const resultType = inst.typeOf(raw);
+            this.validateResultType(resultType, ctx);
+            this.validateResultValue(raw, ctx, numericType);
+            // Match JS Number.toString thresholds — math.js defaults to exp ≥ 5,
+            // which would render 83810205 as "8.3810205e+7".
+            const result = inst.format(raw, {
+                lowerExp: -6,
+                upperExp: 21,
+                ...(precision != null && { precision }),
+            });
+            this.validateResultSize(result, ctx);
+            return { result, resultType };
+        }, ctx, {
+            operation: 'evaluate',
+            numericType,
+            // A scope value shadows the function of the same name.
+            functionValues: functionValues.filter((name) => !(scope && Object.hasOwn(scope, name))),
         });
-        this.validateResultSize(result, ctx);
-        return { result, resultType };
     }
     /** Simplify an algebraic expression symbolically. */
     simplifyExpression(expression, ctx) {
         this.validateInput(expression, ctx);
-        const normalized = normalizeNotation(expression);
-        this.validateNoFunctionStringification(normalized, ctx);
-        // Capture the AST-normalized form of the input before simplification so we
-        // can detect whether the simplifier made any progress. String comparison is
-        // not sufficient — formatting-only changes like `x+1` vs `x + 1` should not
-        // count as progress. We parse both sides and compare their `.toString()` output,
-        // which normalises whitespace and operator representation consistently.
-        let inputNormalized;
-        try {
-            inputNormalized = this.parse(normalized).toString();
-        }
-        catch {
-            // If the expression cannot be parsed, let the simplify step surface the error
-            // with full math.js context. Set to the raw input so the unchanged flag is
-            // false (we don't know, but a parse error is not a no-op simplification).
-            inputNormalized = '';
-        }
-        const simplified = this.runWithTimeout(() => this.simplify(normalized, this.simplifyRules), ctx);
-        const result = simplified.toString();
+        const { tree } = this.parseExpression(expression, this.defaultInstance, ctx);
+        // Capture the alias-normalized input before simplification so we can detect
+        // whether the simplifier made any progress. String comparison of the raw input
+        // is not sufficient — formatting-only changes like `x+1` vs `x + 1` should not
+        // count as progress — so both sides are compared as math.js renders them.
+        const inputNormalized = tree.toString();
+        const result = this.runWithTimeout(() => this.simplify(tree, this.simplifyRules).toString(), ctx, { operation: 'simplify' });
         this.validateResultSize(result, ctx);
-        const unchanged = inputNormalized !== '' && inputNormalized === result;
-        return { result, resultType: 'string', unchanged };
+        return { result, resultType: 'string', unchanged: inputNormalized === result };
     }
     /** Compute the symbolic derivative of an expression with respect to a variable. */
     differentiateExpression(expression, variable, ctx) {
         this.validateInput(expression, ctx);
-        const normalized = normalizeNotation(expression);
-        this.validateNoFunctionStringification(normalized, ctx);
-        const derived = this.runWithTimeout(() => this.derivative(normalized, variable), ctx);
-        const result = derived.toString();
+        const { tree } = this.parseExpression(expression, this.defaultInstance, ctx);
+        const result = this.runWithTimeout(() => this.derivative(tree, variable).toString(), ctx, {
+            operation: 'derivative',
+            variable,
+        });
         this.validateResultSize(result, ctx);
         return { result, resultType: 'string' };
     }
@@ -383,107 +636,273 @@ export class MathService {
     }
     validateInput(expression, ctx) {
         if (!expression.trim()) {
-            throw validationError('Expression cannot be empty.', {
-                reason: 'empty_expression',
-                ...ctx.recoveryFor('empty_expression'),
-            });
+            throw declared(ctx, 'empty_expression', 'Expression cannot be empty.');
         }
         if (expression.length > this.config.maxExpressionLength) {
-            throw validationError(`Expression exceeds maximum length of ${this.config.maxExpressionLength} characters.`, { reason: 'expression_too_long', ...ctx.recoveryFor('expression_too_long') });
+            throw declared(ctx, 'expression_too_long', `Expression exceeds maximum length of ${this.config.maxExpressionLength} characters.`);
         }
-        if (hasExpressionSeparator(expression)) {
-            throw validationError('Multiple expressions are not allowed. Submit one expression per call.', { reason: 'multiple_expressions', ...ctx.recoveryFor('multiple_expressions') });
+    }
+    /**
+     * Parse once and check the tree before anything evaluates. A parse failure is
+     * `parse_failed`. Multiple statements are detected structurally — math.js parses
+     * `a; b` and a top-level newline into a `BlockNode` — so `;` inside a matrix or
+     * inside either quote style (`"a;b"`, `'a;b'`) is data, transpose `A'` stays an
+     * operator, and a real separator is rejected before either statement runs (#32).
+     * math.js treats a bare carriage return as a syntax error rather than a
+     * separator; when it is what broke the parse, the input is re-parsed with line
+     * feeds purely to report `multiple_expressions` — the rewritten text is never
+     * evaluated. The same tree then gets the stringifier check, the
+     * operation-as-function check (#27), and the notation rename (#24), and yields
+     * the names it uses as values that resolve to functions (#38). Every operation
+     * starts here, so it also resets the instance's auto unit system (#37).
+     */
+    parseExpression(expression, inst, ctx) {
+        inst.resetUnitSystem();
+        let tree;
+        try {
+            tree = inst.parse(expression);
         }
+        catch (err) {
+            if (expression.includes('\r') &&
+                this.parsesAsBlock(expression.replace(/\r\n?/g, '\n'), inst)) {
+                throw this.multipleExpressions(ctx);
+            }
+            throw declared(ctx, 'parse_failed', `Invalid expression: ${errorMessage(err)}`);
+        }
+        if (tree.type === 'BlockNode')
+            throw this.multipleExpressions(ctx);
+        const { stringifies, operationCall, valueNames } = inspectTree(tree);
+        // `.toString()` / `.toLocaleString()` on a function-valued identifier
+        // (`cos.toString()`) returns the function's source as a plain string, slipping
+        // past validateResultType, which only sees the value after stringification. No
+        // calculator expression needs either method, so the accessor is rejected on any
+        // operand; a string literal containing "toString" is a ConstantNode, not an
+        // accessor, and is unaffected.
+        if (stringifies) {
+            throw declared(ctx, 'disallowed_result_type', 'Converting a function to a string is not allowed — it would expose internal source.');
+        }
+        if (operationCall !== undefined) {
+            const variableHint = operationCall === 'derivative' ? ' and pass `variable`' : '';
+            throw declared(ctx, 'operation_as_function', `"${operationCall}" is an operation, not a function available inside expressions. Send the inner expression as \`expression\` with \`operation: "${operationCall}"\`${variableHint}.`);
+        }
+        return { tree, functionValues: [...valueNames].filter(inst.isFunction) };
+    }
+    /** Whether `expression` parses to multiple statements. */
+    parsesAsBlock(expression, inst) {
+        try {
+            return inst.parse(expression).type === 'BlockNode';
+        }
+        catch {
+            return false;
+        }
+    }
+    multipleExpressions(ctx) {
+        return declared(ctx, 'multiple_expressions', 'Multiple expressions are not allowed. Submit one expression per call.');
     }
     /** Reject scope keys that could pollute the object prototype chain. */
     validateScope(scope, ctx) {
         for (const key of Object.keys(scope)) {
             if (BLOCKED_SCOPE_KEYS.has(key)) {
-                throw validationError(`Scope key "${key}" is not allowed — it conflicts with a reserved property name.`, { reason: 'reserved_scope_key', ...ctx.recoveryFor('reserved_scope_key') });
+                throw declared(ctx, 'reserved_scope_key', `Scope key "${key}" is not allowed — it conflicts with a reserved property name.`);
             }
         }
     }
     /** Reject result types that leak internals (functions, parsers, multi-expression ResultSets). */
     validateResultType(resultType, ctx) {
         if (BLOCKED_RESULT_TYPES.has(resultType)) {
-            throw validationError(`Expression produced a ${resultType} — only numeric, string, matrix, complex, unit, and boolean results are allowed.`, { reason: 'disallowed_result_type', ...ctx.recoveryFor('disallowed_result_type') });
+            throw declared(ctx, 'disallowed_result_type', `Expression produced a ${resultType}, which cannot be returned — the result must be a value, not a function.`);
         }
     }
-    /** Reject results holding a non-finite value (Infinity, -Infinity, NaN), including inside matrices and complex numbers. */
-    validateFinite(raw, ctx) {
-        if (containsNonFinite(raw)) {
-            throw validationError('Expression evaluated to a non-finite result (Infinity, -Infinity, or NaN) — this typically means the operation is mathematically undefined (e.g., division by zero, log of zero). Check the expression.', { reason: 'undefined_result', ...ctx.recoveryFor('undefined_result') });
+    /**
+     * Inspect a result before it is formatted: reject a `help()` object (its
+     * rendering evaluates the documentation examples, #31), a collection too large
+     * to ever fit `maxResultLength` (checked before formatting, so it is never
+     * stringified), any non-finite number, scalar or nested (#21), and under
+     * numericType "Fraction", any float approximation, scalar or nested (#35).
+     */
+    validateResultValue(raw, ctx, numericType) {
+        const { maxResultLength } = this.config;
+        if (typeof raw === 'string' && raw.length > maxResultLength) {
+            throw this.resultTooLarge(ctx);
         }
+        const elementLimit = Math.floor(maxResultLength / MIN_CHARS_PER_ELEMENT);
+        const scan = {
+            elements: 0,
+            help: false,
+            nonFinite: false,
+            exactOnly: numericType === 'Fraction',
+            inexact: false,
+        };
+        scanResult(raw, elementLimit, scan);
+        if (scan.help) {
+            throw declared(ctx, 'disallowed_result_type', 'help() is not available inside expressions — read the calculator://help resource for the function reference.');
+        }
+        if (scan.elements > elementLimit)
+            throw this.resultTooLarge(ctx);
+        if (scan.nonFinite)
+            throw declared(ctx, 'undefined_result', UNDEFINED_RESULT_MESSAGE);
+        if (scan.inexact)
+            throw declared(ctx, 'fraction_unsupported', FRACTION_FLOAT_MESSAGE);
     }
     /** Reject results that exceed the configured maximum size. */
     validateResultSize(result, ctx) {
-        if (result.length > this.config.maxResultLength) {
-            throw validationError(`Result exceeds maximum size (${this.config.maxResultLength} characters). Reduce matrix dimensions or simplify the expression.`, { reason: 'result_too_large', ...ctx.recoveryFor('result_too_large') });
-        }
+        if (result.length > this.config.maxResultLength)
+            throw this.resultTooLarge(ctx);
+    }
+    resultTooLarge(ctx) {
+        return declared(ctx, 'result_too_large', `Result exceeds maximum size (${this.config.maxResultLength} characters). Reduce matrix dimensions or simplify the expression.`);
     }
     /**
-     * Reject expressions that access `.toString` / `.toLocaleString` on any value.
-     * math.js permits these methods on function-valued identifiers (`cos.toString()`,
-     * `import.toString()`), returning the function's source as a plain string — which
-     * slips past {@link validateResultType}, whose function defense only inspects the
-     * value AFTER stringification. The check is parse-time and AST-based rather than a
-     * runtime `Function.prototype` patch: math.js itself calls `toString` on functions
-     * internally while evaluating units, statistics, and complex results, so patching
-     * the prototype would reject legitimate expressions. No real calculator expression
-     * needs `.toString()`/`.toLocaleString()`, so blocking the accessor outright (dot
-     * or bracket form, on any operand) is both sufficient and side-effect-free. String
-     * literals that merely contain the text "toString" parse as ConstantNodes, not
-     * accessors, so they are unaffected.
+     * Runs a synchronous function inside a vm sandbox with timeout protection and
+     * maps anything it throws to a declared reason via {@link classifyFailure}.
+     *
+     * The context exists only to carry the timeout — `fn` and everything it calls
+     * run in this realm — so one context is reused for every call and cleared
+     * afterwards. A fresh context per call costs ~100 µs and, under Bun, retains
+     * ~100 KB of memory per call.
      */
-    validateNoFunctionStringification(expr, ctx) {
-        let ast;
+    runWithTimeout(fn, ctx, stage) {
+        const { sandbox } = this;
+        sandbox.fn = fn;
+        beginEvaluation();
         try {
-            ast = this.parse(expr);
+            TIMED_CALL.runInContext(sandbox, { timeout: this.config.evaluationTimeoutMs });
+            return sandbox.result;
         }
-        catch {
-            // Let the evaluate path surface parse errors with full mathjs context.
-            return;
+        catch (err) {
+            throw this.classifyFailure(err, ctx, stage);
         }
-        const accessesStringifier = ast.filter((node) => {
-            if (node.type !== 'IndexNode')
-                return false;
-            const { dimensions } = node;
-            return dimensions.some((dim) => dim.type === 'ConstantNode' && STRINGIFYING_METHODS.has(String(dim.value)));
-        });
-        if (accessesStringifier.length > 0) {
-            throw validationError('Converting a function to a string is not allowed — it would expose internal source. Only numeric, string, matrix, complex, unit, and boolean results are allowed.', { reason: 'disallowed_result_type', ...ctx.recoveryFor('disallowed_result_type') });
+        finally {
+            sandbox.fn = undefined;
+            sandbox.result = undefined;
         }
     }
     /**
-     * Runs a synchronous function inside a vm sandbox with timeout protection.
-     * `numericType` is supplied only by the evaluate path so a Fraction-mode
-     * conversion failure can be remapped to the actionable `fraction_unsupported`
-     * error instead of the misleading `parse_failed` (#19).
+     * Classify a failure raised after the expression parsed (evaluation, result
+     * inspection, formatting, or a symbolic operation). First match wins:
+     *
+     * 1. Already-classified `McpError`s (result checks) pass through.
+     * 2. Timeout → `evaluation_timeout`.
+     * 3. A size guard (see size-guard.ts) → `result_too_large`.
+     * 4. Fraction mode calling a function with no Fraction implementation (sqrt,
+     *    sin, log, factorial, …) → `fraction_unsupported` (#19); so does Fraction
+     *    mode meeting a float with no equal Fraction (`pi * 2/3`, #35).
+     * 5. fraction.js `Division by Zero`, in any numericType → `undefined_result` (#21).
+     * 6. Name errors (undefined symbol/function/unit, disabled function, blocked
+     *    property) → `parse_failed`.
+     * 7. A symbolic operation (simplify, derivative) that cannot process the parsed
+     *    tree → `evaluation_failed`, with a hint about the symbolic engine rather
+     *    than about argument values (see {@link symbolicFailure}).
+     * 8. Operand type/unit errors (typed-function `wrongType`, unit mismatch,
+     *    string-to-number) → `type_mismatch`.
+     * 9. Anything else — arity, domain, singular matrix, dimensions, index →
+     *    `evaluation_failed` (#29). Stage decides, not error class: a runtime
+     *    `SyntaxError` such as `number("abc")` lands here, never in `parse_failed`.
      */
-    runWithTimeout(fn, ctx, numericType) {
-        const sandbox = { fn, result: undefined };
-        try {
-            vm.runInNewContext('result = fn()', sandbox, { timeout: this.config.evaluationTimeoutMs });
-            return sandbox.result;
+    classifyFailure(err, ctx, stage) {
+        const { numericType } = stage;
+        if (err instanceof McpError)
+            return err;
+        const message = errorMessage(err);
+        // math.js's map/forEach/filter re-wrap a callback's error in a new one that
+        // embeds its message, so a timeout inside a callback loses the error code.
+        const timedOut = (err instanceof Error && 'code' in err && err.code === 'ERR_SCRIPT_EXECUTION_TIMEOUT') ||
+            VM_TIMEOUT_ERROR.test(message);
+        if (timedOut) {
+            return timeout(`Expression evaluation timed out after ${this.config.evaluationTimeoutMs / 1000} seconds. Simplify the expression or reduce matrix dimensions.`, { reason: 'evaluation_timeout', ...ctx.recoveryFor('evaluation_timeout') });
         }
-        catch (err) {
-            if (err instanceof Error && 'code' in err && err.code === 'ERR_SCRIPT_EXECUTION_TIMEOUT') {
-                throw timeout(`Expression evaluation timed out after ${this.config.evaluationTimeoutMs / 1000} seconds. Simplify the expression or reduce matrix dimensions.`, { reason: 'evaluation_timeout', ...ctx.recoveryFor('evaluation_timeout') });
-            }
-            const message = err instanceof Error ? err.message : String(err);
-            // Fraction mode cannot represent an irrational/transcendental result (sqrt, sin,
-            // log, …); math.js surfaces this as an implicit-conversion error. Remap to a
-            // dedicated, actionable error rather than the syntax-oriented parse_failed.
-            if (numericType === 'Fraction' && FRACTION_CONVERSION_ERROR.test(message)) {
-                throw validationError('This expression has no exact fractional value (irrational or transcendental result, e.g. sqrt, sin, log). Retry with numericType "number" or "BigNumber".', { reason: 'fraction_unsupported', ...ctx.recoveryFor('fraction_unsupported') });
-            }
-            // All other non-timeout errors from the VM are expression-related.
-            throw validationError(`Invalid expression: ${message}`, {
-                reason: 'parse_failed',
-                ...ctx.recoveryFor('parse_failed'),
-            });
+        const limitError = sizeLimitErrorIn(err);
+        if (limitError) {
+            return declared(ctx, 'result_too_large', `Size limit exceeded: ${limitError.message}`);
         }
+        if (numericType === 'Fraction' && FRACTION_CONVERSION_ERROR.test(message)) {
+            return declared(ctx, 'fraction_unsupported', FRACTION_FUNCTION_MESSAGE);
+        }
+        if (numericType === 'Fraction' && FLOAT_TO_FRACTION_ERROR.test(message)) {
+            return declared(ctx, 'fraction_unsupported', FRACTION_FLOAT_MESSAGE);
+        }
+        if (FRACTION_DIVISION_BY_ZERO.test(message)) {
+            return declared(ctx, 'undefined_result', UNDEFINED_RESULT_MESSAGE);
+        }
+        if (NAME_ERROR.test(message)) {
+            return declared(ctx, 'parse_failed', `Invalid expression: ${message}`);
+        }
+        if (stage.operation !== 'evaluate')
+            return symbolicFailure(stage, message);
+        const data = err?.data;
+        const category = data?.category;
+        if (category === 'wrongType' &&
+            Array.isArray(data?.actual) &&
+            data.actual.includes('function')) {
+            return functionAsValue(stage.functionValues, message);
+        }
+        if (category === 'wrongType' || TYPE_MISMATCH_ERROR.test(message)) {
+            return declared(ctx, 'type_mismatch', `Type mismatch: ${message}`);
+        }
+        return declared(ctx, 'evaluation_failed', `Evaluation failed: ${message}`);
+    }
+}
+/**
+ * `evaluation_failed` for a symbolic operation that parsed but could not be
+ * carried out. The hint is written at the throw site: the contract hint is about
+ * fixing an argument, but here the syntax and arguments are fine — the symbolic
+ * engine has no rule for part of the expression (a function such as `floor` or
+ * an operator such as `==` in a derivative, or a matrix or conditional node).
+ */
+function symbolicFailure(stage, message) {
+    const { operation } = stage;
+    const noRule = operation === 'derivative' && NO_DERIVATIVE_RULE.exec(message);
+    if (noRule) {
+        const [, kind, name] = noRule;
+        return validationError(`The derivative operation has no rule for the ${kind} "${name}", so it cannot differentiate this expression symbolically.`, {
+            reason: 'evaluation_failed',
+            recovery: {
+                hint: `"${name}" has no symbolic derivative rule — rewrite the expression without it, or evaluate it numerically with operation "evaluate", passing values for its variables (such as ${stage.variable}) through scope.`,
+            },
+        });
     }
+    return validationError(`The ${operation} operation cannot process this expression symbolically: ${message}`, {
+        reason: 'evaluation_failed',
+        recovery: {
+            hint: `The ${operation} engine cannot handle part of this expression (for example a matrix or conditional) — rewrite it with scalar functions and operators, or evaluate it numerically with operation "evaluate" and values passed through scope.`,
+        },
+    });
+}
+/**
+ * `type_mismatch` for a function where a value belongs: math.js reads a name or
+ * definition next to a value as multiplication (`5 min` is 5 times the minimum
+ * function, `(f(x) = x^2)(3)` is the function times 3). The contract hint is about
+ * units, so the hint is written here (#38), naming the functions the expression
+ * uses as values and the unit to write for one that shadows a unit name.
+ */
+function functionAsValue(names, detail) {
+    const described = names.map((name) => {
+        const unit = FUNCTION_SHADOWED_UNITS[name];
+        return unit ? `"${name}" is a function, not the unit "${unit}"` : `"${name}" is a function`;
+    });
+    const unitHints = names.flatMap((name) => {
+        const unit = FUNCTION_SHADOWED_UNITS[name];
+        return unit
+            ? [`"${name}" names a function here; for the unit, write ${unit} (\`5 ${unit}\`).`]
+            : [];
+    });
+    return validationError(`Type mismatch: a function was used as a value${described.length ? ` (${described.join('; ')})` : ''}. ${detail}`, {
+        reason: 'type_mismatch',
+        recovery: {
+            hint: [
+                ...unitHints,
+                'To call a function, use parentheses (`sin(1)`, `f(3)`); a function name or definition next to a value multiplies it instead.',
+            ].join(' '),
+        },
+    });
+}
+/** A validation error carrying `reason` and the recovery hint its contract entry declares. */
+function declared(ctx, reason, message) {
+    return validationError(message, { reason, ...ctx.recoveryFor(reason) });
+}
+/** Message of a thrown value, whatever its type. */
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
 }
 // --- Init/accessor pattern ---
 let _service;
@@ -520,11 +939,13 @@ const HELP_CONTENT = `# Calculator Help
 | e | 2.71828... | Euler's number |
 | phi | 1.61803... | Golden ratio |
 | i | sqrt(-1) | Imaginary unit |
-| Infinity | Infinity | Positive infinity |
-| NaN | NaN | Not a number |
+| Infinity | Infinity | Positive infinity — intermediate values only |
+| NaN | NaN | Not a number — intermediate values only |
 | true | true | Boolean true |
 | false | false | Boolean false |
 
+\`Infinity\` and \`NaN\` work inside an expression (\`1/Infinity\` => \`0\`, \`isNaN(NaN)\` => \`true\`), but a result that is Infinity, -Infinity, or NaN anywhere in it fails with \`undefined_result\`: \`Infinity\` and \`NaN\` on their own fail.
+
 ## Functions
 
 > **Standard notation accepted:** \`ln\` works as natural log (canonical \`log\`), and the \`arc*\` inverse-trig names (\`arcsin\`, \`arccos\`, \`arctan\`, \`arcsinh\`, …) work as their \`a*\` equivalents (\`asin\`, \`acos\`, \`atan\`, …). Both forms are valid across evaluate, simplify, and derivative.
@@ -533,11 +954,25 @@ const HELP_CONTENT = `# Calculator Help
 abs, ceil, floor, round, sign, sqrt, cbrt, exp, expm1, log (also: ln), log2, log10, log1p, pow, mod, gcd, lcm, nthRoot, hypot, fix, cube, square, unaryMinus, unaryPlus
 
 ### Trigonometry
-sin, cos, tan, asin (arcsin), acos (arccos), atan (arctan), atan2, sinh, cosh, tanh, asinh (arcsinh), acosh (arccosh), atanh (arctanh), sec, csc, cot, asec (arcsec), acsc (arccsc), acot (arccot), sech (arcsech), csch (arccsch), coth (arccoth)
+sin, cos, tan, asin (arcsin), acos (arccos), atan (arctan), atan2, sinh, cosh, tanh, asinh (arcsinh), acosh (arccosh), atanh (arctanh), sec, csc, cot, asec (arcsec), acsc (arccsc), acot (arccot), sech, csch, coth, asech (arcsech), acsch (arccsch), acoth (arccoth)
 
 ### Statistics
 mean (aliases: average, avg), median, mode, std (aliases: stdev, stddev), variance, min, max, sum, prod, quantileSeq, mad, count (aliases: length, len)
 
+\`std\` and \`variance\` (and the \`stdev\`/\`stddev\` aliases) return the sample statistic by default. An optional normalization string after the array or matrix picks the divisor:
+
+| Normalization | Divisor | \`std([2, 4, 6], …)\` | \`variance([2, 4, 6], …)\` |
+|:--------------|:--------|:--------------------|:-------------------------|
+| \`"unbiased"\` (default, sample) | n − 1 | \`2\` | \`4\` |
+| \`"uncorrected"\` (population) | n | \`1.632993161855452\` | \`2.6666666666666665\` |
+| \`"biased"\` | n + 1 | \`1.4142135623730951\` | \`2\` |
+
+\`std([2, 4, 6], "uncorrected")\` => \`1.632993161855452\`. The normalization must follow an array or matrix: \`std(2, 4, 6, "uncorrected")\` fails.
+
+- \`mad\` is the unscaled median absolute deviation (no 1.4826 factor): \`mad([1, 2, 3, 4, 100])\` => \`1\`
+- \`quantileSeq\` interpolates linearly: \`quantileSeq([1, 2, 3, 4], 0.25)\` => \`1.75\`. A third argument \`true\` declares the data already sorted and skips sorting, so unsorted data then gives a wrong answer: \`quantileSeq([4, 3, 2, 1], 0.25, true)\` => \`3.25\`
+- \`mode\` always returns an array, even with a single mode: \`mode([1, 2, 2, 3])\` => \`[2]\`
+
 ### Matrix
 det, inv, transpose, trace, zeros, ones, identity, diag, size, reshape, flatten, concat, sort, cross, dot, eigs, expm, sqrtm, kron, pinv, range
 
@@ -556,55 +991,60 @@ equal, unequal, larger, largerEq, smaller, smallerEq, compare, deepEqual
 ### Unit Conversion
 Syntax: \`value unit to targetUnit\`
 
-Common units: m, cm, mm, km, inch, ft, yard, mile, lightyear (ly), kg, g, lb, oz, s, min, hour, day, mph, knot (kt), celsius, fahrenheit, kelvin, liter, gallon, joule, watt, newton, pascal, bar, psi, radian, degree
+Common units: m, cm, mm, km, inch, ft, yard, mile, lightyear (ly), kg, g, lb, oz, s, minute, hour, day, mph, knot (kt), celsius, fahrenheit, kelvin, liter, gallon, joule, watt, newton, Pa, bar, psi, radian, degree
+
+\`min\` is the minimum function, not minutes, so write \`minute\`: \`5 minute to s\` => \`300 s\`. Pascals are \`Pa\`: \`1 bar to Pa\` => \`100000 Pa\`.
 
 ## Syntax Examples
 
+Each example shows the exact result string \`calculate\` returns.
+
 ### Basic arithmetic
-\`2 + 3 * 4\` => 14
+\`2 + 3 * 4\` => \`14\`
 
 ### Functions
-\`sqrt(144)\` => 12
-\`sin(pi / 2)\` => 1
-\`log(1000, 10)\` => 3
+\`sqrt(144)\` => \`12\`
+\`sin(pi / 2)\` => \`1\`
+\`log(1000, 10)\` => \`2.9999999999999996\` (floating-point rounding); with \`precision: 10\`, \`log(1000, 10)\` => \`3\`
 
-### Variables (via scope parameter)
+### Variables (scope parameter, evaluate only)
 Provide scope: { "x": 5, "y": 3 }
-Expression: \`x^2 + y\` => 28
+Expression: \`x^2 + y\` => \`28\`
 
 ### Matrices
-\`[1, 2; 3, 4]\` — 2x2 matrix
-\`det([1, 2; 3, 4])\` => -2
-\`inv([1, 2; 3, 4])\` => [[-2, 1], [1.5, -0.5]]
+\`[1, 2; 3, 4]\` — 2x2 matrix (\`;\` separates rows)
+\`det([1, 2; 3, 4])\` => \`-2\`
+\`inv([1, 2; 3, 4])\` => \`[[-2, 1], [1.5, -0.5]]\`
 
 ### Complex numbers
-\`2 + 3i\` => 2 + 3i
-\`sqrt(-4)\` => 2i
-\`abs(3 + 4i)\` => 5
+\`2 + 3i\` => \`2 + 3i\`
+\`sqrt(-4)\` => \`2i\`
+\`abs(3 + 4i)\` => \`5\`
+\`log(-1)\` => \`3.141592653589793i\` — the log of a negative number is complex, not undefined
 
 ### Unit conversion
-\`5 kg to lbs\` => 11.02 lbs
-\`100 celsius to fahrenheit\` => 212 fahrenheit
-\`1 mile to km\` => 1.60934 km
+\`5 kg to lbs\` => \`11.023113109243878 lbs\`
+\`100 celsius to fahrenheit\` => \`211.99999999999997 fahrenheit\`
+\`1 mile to km\` => \`1.609344 km\`
 
-> **Note:** Unit conversions use IEEE 754 floating-point arithmetic. Results may include minor rounding artifacts (e.g., 211.99999999999997 instead of 212). Use the \`precision\` parameter to round.
+> **Note:** Unit conversions use IEEE 754 floating-point arithmetic, so results can carry rounding artifacts like the one above. Use the \`precision\` parameter to round: with \`precision: 6\`, \`100 celsius to fahrenheit\` => \`212 fahrenheit\`.
 
 ### Precision
-Use the precision parameter (1\u201316 significant digits) for numeric results.
+The \`precision\` parameter (1\u201316 significant digits) rounds numeric results: with \`precision: 4\`, \`1 / 3\` => \`0.3333\`. Fraction results always print exactly, and symbolic operations ignore it.
 
 ### Operations
 
-- **evaluate** (default): Compute a numeric result. Use the \`numericType\` parameter to control precision:
-  - \`"number"\` (default): 64-bit IEEE 754 float — fastest. Standard for most calculations.
-  - \`"BigNumber"\`: Arbitrary-precision decimal — use when intermediate values overflow (e.g. \`10000! / 9999!\` overflows as a 64-bit float but evaluates correctly as a BigNumber). Slower than \`"number"\`.
-  - \`"Fraction"\`: Exact rational arithmetic — eliminates floating-point rounding (e.g. \`0.1 + 0.2 = 0.3\` exactly). Limited to expressions with exactly-rational results; an irrational or transcendental result (\`sqrt(2)\`, \`sin(1)\`, \`log(3)\`, …) fails with a \`fraction_unsupported\` error — use \`"number"\` or \`"BigNumber"\` for those.
+- **evaluate** (default): Compute a numeric result. The \`numericType\` parameter picks the number representation:
+  - \`"number"\` (default): 64-bit IEEE 754 float — fastest, about 16 significant digits. A value past about 1.8e308 overflows to Infinity and fails with \`undefined_result\` (\`171!\`, \`2^1024\`, \`exp(1000)\`).
+  - \`"BigNumber"\`: decimal with 64 significant digits and a much wider exponent range; slower than \`"number"\`. Use it when a value overflows the float range: with \`numericType: "BigNumber"\`, \`2^2000\` => \`1.148130695274254524232833201177681984022317702088695200477642737e+602\`. Results are 64-digit approximations, not exact: \`10000! / 9999!\` => \`9999.999999999999999999999999999999999999999999999999999999999996\`, and adding \`precision: 16\` rounds it, \`10000! / 9999!\` => \`10000\`.
+  - \`"Fraction"\`: exact rational arithmetic — \`0.1 + 0.2\` => \`3/10\`, \`1/3 + 1/6\` => \`1/2\`. An expression fails with \`fraction_unsupported\` when its result has no exact rational value (\`sqrt(2)\`, \`sin(1)\`, \`log(3)\`), when it calls a function Fraction mode cannot compute, even for a rational result (\`sqrt(4)\`, \`5!\`, \`combinations(5, 2)\`), or when it uses a value Fraction mode holds only as a rounded 64-bit float (\`pi\`, \`e\`, \`2^(1/2)\`, \`sin(pi)\`, a complex number with a non-integer part, \`number(x)\`, or \`random()\`); use \`"number"\` or \`"BigNumber"\` for those. A unit conversion with an irrational factor returns a close rational approximation, not an exact value: \`30 deg to rad\` => \`191068/364913 rad\`. Whole-number indexes and dimensions work as in \`"number"\`: \`[1, 2, 3][2]\` => \`2/1\`, \`sum([1, 2; 3, 4], 1)\` => \`[4/1, 6/1]\`.
 
-  When \`"number"\` evaluation returns an \`undefined_result\` error (division by zero, overflow), retry with \`numericType: "BigNumber"\`.
+  An \`undefined_result\` caused by overflow (large powers, factorials, \`exp\`) can be retried with \`numericType: "BigNumber"\`. Division by zero, \`0/0\`, and \`log(0)\` are undefined in every numeric type, and BigNumber does not change that.
 
-- **simplify**: Reduce algebraic expressions symbolically (e.g., "2x + 3x" => "5 * x", "sin(x)^2 + cos(x)^2" => 1). Supports algebraic rules and common trigonometric identities (Pythagorean, double-angle, tan/sec/csc/cot relationships).
+- **simplify**: Reduce an algebraic expression symbolically: \`2x + 3x\` => \`5 * x\`, \`sin(x)^2 + cos(x)^2\` => \`1\`. Supports algebraic rules and common trigonometric identities (Pythagorean, double-angle, tan/sec/csc/cot relationships). \`scope\`, \`precision\`, and \`numericType\` are ignored.
 
-  **Known limits:** The built-in simplifier does not perform polynomial factoring or rational cancellation. Expressions like \`(x^2 - 1) / (x - 1)\` are returned unchanged (\`unchanged: true\` in the output). For these cases, consider rewriting by hand or using \`evaluate\` with a numeric scope.
+  **Known limits:** The built-in simplifier does not perform polynomial factoring or rational cancellation: \`(x^2 - 1) / (x - 1)\` => \`(x ^ 2 - 1) / (x - 1)\`, returned with \`unchanged: true\`. For these cases, rewrite by hand or use \`evaluate\` with a numeric scope.
 
-- **derivative**: Compute symbolic derivative (requires variable parameter, e.g., variable: "x")
+- **derivative**: Compute a symbolic derivative; requires the \`variable\` parameter. With \`variable: "x"\`, \`x^2\` => \`2 * x\`. \`scope\`, \`precision\`, and \`numericType\` are ignored.
 `;
 //# sourceMappingURL=math-service.js.map