@reekon-tools/boldr-utils 1.8.4 → 1.9.0

package/dist/calculator/expressionUnits.d.ts

@@ -0,0 +1,84 @@
+import { type MathNode } from 'mathjs';
+import type { CalculatorEquation, CalculatorField } from './schema.js';
+import { type CalculatorUnit, type FieldDimension } from './units.js';
+/** Constants mathjs resolves without a scope entry. */
+export declare const MATHJS_CONSTANTS: Set<string>;
+export type ParseResult = {
+    ok: true;
+    node: MathNode;
+} | {
+    ok: false;
+    error: string;
+};
+/** Shared mathjs parse — the one place expression text becomes a tree. */
+export declare const parseExpression: (expression: string) => ParseResult;
+/**
+ * Bases whose values are ALREADY canonical, so an equation in them needs no
+ * `resultUnit` at all (the pre-unit-annotation form: a canonical scope in
+ * µm / µm² / µm³ / degrees).
+ */
+export declare const CANONICAL_BASES: Set<string>;
+export type InferenceFailureReason = 
+/** The expression does not parse. */
+'unparseable'
+/** A symbol is neither a mapped variable nor a mathjs constant. */
+ | 'unknown-symbol'
+/** A function or operator whose unit behaviour we don't model. */
+ | 'unsupported-operation'
+/** Dimensioned terms added or compared against a different dimension. */
+ | 'inconsistent-terms'
+/** A real exponent, but one this unit vocabulary can't name (µm⁴, 1/ft). */
+ | 'unnameable-dimension';
+export interface InferredExpressionUnit {
+    /** The dimension of the expression's raw value. */
+    dimension: FieldDimension;
+    /**
+     * The unit the raw value carries, or null when no single unit names it
+     * (mixed bases, or a canonical/yard/liter base with no entry).
+     */
+    unit: CalculatorUnit | null;
+    /** Distinct base units among the variables carrying that dimension. */
+    bases: string[];
+}
+export type ExpressionUnitInference = ({
+    ok: true;
+} & InferredExpressionUnit) | {
+    ok: false;
+    reason: InferenceFailureReason;
+};
+/**
+ * The dimension and unit of an equation's raw expression value — what the
+ * number means BEFORE `resultUnit` is applied.
+ */
+export declare const inferExpressionUnit: (fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "expression" | "variableToFieldId" | "variableUnits">) => ExpressionUnitInference;
+/**
+ * True when an expression's raw value is already canonical, so omitting
+ * `resultUnit` is correct rather than a 25400× mistake. Only the
+ * no-variable-units form (and dimensionless results) qualifies.
+ */
+export declare const producesCanonicalValue: (inferred: InferredExpressionUnit) => boolean;
+/** Same physical unit, ignoring display form: `in` ≡ `in_frac`, `ft` ≡ `ft_in_frac`. */
+export declare const isEquivalentUnit: (a: CalculatorUnit, b: CalculatorUnit) => boolean;
+/**
+ * How far off a value is when it carries `actual` but was declared as
+ * `declared` — 144 for in² labelled ft². Used to make validation messages
+ * say what the author will actually see.
+ */
+export declare const unitScaleRatio: (declared: CalculatorUnit, actual: CalculatorUnit) => number;
+/**
+ * The `resultUnit` an equation should carry, or null when it should be omitted
+ * (dimensionless or already-canonical result) or cannot be derived. An
+ * existing equivalent unit is preserved so `in_frac` isn't churned to `in`.
+ */
+export declare const deriveResultUnit: (fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "expression" | "variableToFieldId" | "variableUnits" | "resultUnit">) => CalculatorUnit | null;
+/**
+ * Bring an equation's unit annotations back in line with the fields it
+ * references. Field edits (a dimension switch, a kind change, a deletion) are
+ * written independently of equations, so a stale `variableUnits` entry or
+ * `resultUnit` would otherwise keep converting against a unit the field no
+ * longer uses — the failure mode this whole module exists to prevent.
+ */
+export declare const reconcileEquationUnits: (fields: readonly CalculatorField[], equations: readonly CalculatorEquation[]) => {
+    equations: CalculatorEquation[];
+    changed: boolean;
+};

package/dist/calculator/expressionUnits.js

@@ -0,0 +1,439 @@
+import { create, all } from 'mathjs';
+import { Units } from '../types/firestore.js';
+import { fieldDefaultUnit, fieldDimension } from './schema.js';
+import { CALCULATOR_UNIT_INFO, toCanonical, unitDimension, } from './units.js';
+const math = create(all);
+// ---------------------------------------------------------------------------
+// Expression unit inference.
+//
+// An equation's `variableUnits` / `resultUnit` (schema.ts) evaluate it in the
+// author's display units: each variable is converted OUT of canonical before
+// entering the scope, and the raw result is converted back FROM `resultUnit`.
+// Nothing in the evaluator checks that `resultUnit` is the unit the expression
+// actually produces — it is an assertion, not a conversion. Assert wrongly and
+// the answer is silently off by a scale factor: three inch-valued variables
+// multiplied yield in³, so declaring the result `cu_ft` overstates it 1728×,
+// with every unit label on screen still reading correctly.
+//
+// This module recovers the missing information by propagating unit exponents
+// through the expression tree. Each variable contributes its dimension's
+// exponent (length 1, area 2, volume 3), `*` adds them, `/` subtracts, `sqrt`
+// halves, and the result's exponent names the dimension. Pair that with the
+// base unit the variables share and the correct `resultUnit` is fully
+// determined — which is why the authoring UI derives it rather than asking,
+// and why validation can flag the scale errors it otherwise cannot see.
+//
+// Inference is deliberately conservative. Anything it cannot reason about —
+// unknown functions, non-integer powers, symbols with no mapping — returns
+// `ok: false` so callers fall back to prior behaviour instead of reporting a
+// false positive on valid math.
+// ---------------------------------------------------------------------------
+/** Constants mathjs resolves without a scope entry. */
+export const MATHJS_CONSTANTS = new Set([
+    'pi',
+    'PI',
+    'e',
+    'E',
+    'tau',
+    'phi',
+    'i',
+    'true',
+    'false',
+    'Infinity',
+    'NaN',
+    'null',
+]);
+/** Shared mathjs parse — the one place expression text becomes a tree. */
+export const parseExpression = (expression) => {
+    try {
+        return { ok: true, node: math.parse(expression) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+};
+// The math.js base token a unit reduces to: 'sq_ft' -> 'ft', 'in_frac' -> 'in',
+// 'liter' -> 'L'. Two units share a base exactly when they are the same
+// physical unit at different exponents, which is what makes a result unit
+// nameable.
+const baseUnitOf = (unit) => (CALCULATOR_UNIT_INFO[unit]?.mathUnit ?? '').split('^')[0];
+/**
+ * Bases whose values are ALREADY canonical, so an equation in them needs no
+ * `resultUnit` at all (the pre-unit-annotation form: a canonical scope in
+ * µm / µm² / µm³ / degrees).
+ */
+export const CANONICAL_BASES = new Set(['um', 'deg']);
+const CANONICAL_LENGTH_BASE = 'um';
+const CANONICAL_ANGLE_BASE = 'deg';
+// Base + length exponent -> the unit that names it. Yards have no length
+// entry (the Units enum has no yard) and liters/gallons no length base at all,
+// so both simply fail to name a unit rather than guessing.
+const UNIT_BY_BASE = {
+    mm: { 1: Units.Millimeters, 2: 'sq_mm', 3: 'cu_mm' },
+    cm: { 1: Units.Centimeters, 2: 'sq_cm', 3: 'cu_cm' },
+    m: { 1: Units.Meters, 2: 'sq_m', 3: 'cu_m' },
+    in: { 1: Units.Inches, 2: 'sq_in', 3: 'cu_in' },
+    ft: { 1: Units.Feet, 2: 'sq_ft', 3: 'cu_ft' },
+    yd: { 2: 'sq_yd', 3: 'cu_yd' },
+};
+const SCALAR = { len: 0, ang: 0 };
+const isScalar = (e) => e.len === 0 && e.ang === 0;
+const sameExponents = (a, b) => a.len === b.len && a.ang === b.ang;
+const EXPONENTS_BY_DIMENSION = {
+    none: SCALAR,
+    length: { len: 1, ang: 0 },
+    area: { len: 2, ang: 0 },
+    volume: { len: 3, ang: 0 },
+    angle: { len: 0, ang: 1 },
+};
+// Functions that return their arguments' dimension (scalar arguments — a digit
+// count, a clamp bound — are ignored).
+const DIMENSION_PRESERVING_FNS = new Set([
+    'abs',
+    'min',
+    'max',
+    'mean',
+    'median',
+    'sum',
+    'round',
+    'floor',
+    'ceil',
+    'fix',
+    'mod',
+]);
+// Trig works in DEGREES here (evaluate.ts overrides mathjs), so an inverse
+// function's result is an angle in the canonical angle unit.
+const DIRECT_TRIG_FNS = new Set(['sin', 'cos', 'tan', 'sec', 'csc', 'cot']);
+const INVERSE_TRIG_FNS = new Set(['asin', 'acos', 'atan', 'atan2']);
+// Functions that require and return plain numbers.
+const SCALAR_FNS = new Set(['log', 'log10', 'log2', 'exp', 'sign']);
+/**
+ * The dimension and unit of an equation's raw expression value — what the
+ * number means BEFORE `resultUnit` is applied.
+ */
+export const inferExpressionUnit = (fields, equation) => {
+    const parsed = parseExpression(equation.expression);
+    if (!parsed.ok)
+        return { ok: false, reason: 'unparseable' };
+    const fieldById = new Map(fields.map((f) => [f.id, f]));
+    const lengthBases = new Set();
+    const angleBases = new Set();
+    let failure = null;
+    const fail = (reason) => {
+        failure ?? (failure = reason);
+        return null;
+    };
+    const noteBases = (exponents, base) => {
+        if (exponents.len !== 0)
+            lengthBases.add(base);
+        if (exponents.ang !== 0)
+            angleBases.add(base);
+    };
+    const resolveSymbol = (name) => {
+        const unit = equation.variableUnits?.[name];
+        if (unit != null) {
+            const exponents = EXPONENTS_BY_DIMENSION[unitDimension(unit)];
+            noteBases(exponents, baseUnitOf(unit));
+            return exponents;
+        }
+        const fieldId = equation.variableToFieldId[name];
+        const field = fieldId != null ? fieldById.get(fieldId) : undefined;
+        if (field) {
+            // No variable unit: the value enters the scope canonically (units.ts).
+            const dimension = fieldDimension(field);
+            const exponents = EXPONENTS_BY_DIMENSION[dimension];
+            noteBases(exponents, dimension === 'angle' ? CANONICAL_ANGLE_BASE : CANONICAL_LENGTH_BASE);
+            return exponents;
+        }
+        // Unmapped: fine if mathjs resolves it, otherwise validation's
+        // unmapped-symbol check owns the error and we just decline to infer.
+        return MATHJS_CONSTANTS.has(name) ? SCALAR : fail('unknown-symbol');
+    };
+    // Scale a term's exponents by a constant power, e.g. `^2` or `sqrt`. Only
+    // whole-number results are nameable: sqrt of an area is a length, sqrt of a
+    // length is not anything we can express.
+    const scaled = (exponents, factor) => {
+        const len = exponents.len * factor;
+        const ang = exponents.ang * factor;
+        return Number.isInteger(len) && Number.isInteger(ang)
+            ? { len, ang }
+            : fail('unnameable-dimension');
+    };
+    const constantValue = (node) => {
+        if (node.type === 'ParenthesisNode' && node.content) {
+            return constantValue(node.content);
+        }
+        if (node.type === 'ConstantNode' && typeof node.value === 'number') {
+            return node.value;
+        }
+        if (node.type === 'OperatorNode' && node.fn === 'unaryMinus') {
+            const inner = node.args?.[0] ? constantValue(node.args[0]) : null;
+            return inner == null ? null : -inner;
+        }
+        return null;
+    };
+    const walk = (node) => {
+        switch (node.type) {
+            case 'ConstantNode':
+                return SCALAR;
+            case 'ParenthesisNode':
+                return node.content
+                    ? walk(node.content)
+                    : fail('unsupported-operation');
+            case 'SymbolNode':
+                return node.name ? resolveSymbol(node.name) : fail('unknown-symbol');
+            case 'OperatorNode':
+                return walkOperator(node);
+            case 'FunctionNode':
+                return walkFunction(node);
+            default:
+                // ConditionalNode, AssignmentNode, ranges, matrices, ...
+                return fail('unsupported-operation');
+        }
+    };
+    const walkArgs = (node) => {
+        const args = node.args ?? [];
+        const out = [];
+        for (const arg of args) {
+            const exponents = walk(arg);
+            if (!exponents)
+                return null;
+            out.push(exponents);
+        }
+        return out;
+    };
+    const walkOperator = (node) => {
+        const args = walkArgs(node);
+        if (!args)
+            return null;
+        switch (node.fn) {
+            case 'multiply':
+                return args.reduce((acc, e) => ({ len: acc.len + e.len, ang: acc.ang + e.ang }), SCALAR);
+            case 'divide':
+                return args.length === 2
+                    ? {
+                        len: args[0].len - args[1].len,
+                        ang: args[0].ang - args[1].ang,
+                    }
+                    : fail('unsupported-operation');
+            case 'add':
+            case 'subtract': {
+                // A bare literal added to a dimensioned term adopts its unit — that is
+                // the whole point of evaluating in display units ("wall + 2 inches").
+                // Two DIFFERENT dimensions added is an author error.
+                const dimensioned = args.filter((e) => !isScalar(e));
+                if (dimensioned.length === 0)
+                    return SCALAR;
+                return dimensioned.every((e) => sameExponents(e, dimensioned[0]))
+                    ? dimensioned[0]
+                    : fail('inconsistent-terms');
+            }
+            case 'unaryMinus':
+            case 'unaryPlus':
+                return args[0] ?? fail('unsupported-operation');
+            case 'pow': {
+                if (args.length !== 2)
+                    return fail('unsupported-operation');
+                if (isScalar(args[0]))
+                    return SCALAR;
+                const exponent = node.args?.[1] ? constantValue(node.args[1]) : null;
+                return exponent == null
+                    ? fail('unsupported-operation')
+                    : scaled(args[0], exponent);
+            }
+            case 'mod':
+                return args[0] ?? fail('unsupported-operation');
+            default:
+                // Comparisons, logic, bit ops — not meaningful on dimensioned values.
+                return fail('unsupported-operation');
+        }
+    };
+    const walkFunction = (node) => {
+        const args = walkArgs(node);
+        if (!args)
+            return null;
+        const name = typeof node.fn === 'string' ? node.fn : node.fn?.name;
+        if (!name)
+            return fail('unsupported-operation');
+        if (name === 'sqrt')
+            return scaled(args[0] ?? SCALAR, 0.5);
+        if (name === 'cbrt')
+            return scaled(args[0] ?? SCALAR, 1 / 3);
+        if (name === 'nthRoot') {
+            const root = node.args?.[1] ? constantValue(node.args[1]) : 2;
+            return root == null || root === 0
+                ? fail('unsupported-operation')
+                : scaled(args[0] ?? SCALAR, 1 / root);
+        }
+        if (DIMENSION_PRESERVING_FNS.has(name)) {
+            const dimensioned = args.filter((e) => !isScalar(e));
+            if (dimensioned.length === 0)
+                return SCALAR;
+            return dimensioned.every((e) => sameExponents(e, dimensioned[0]))
+                ? dimensioned[0]
+                : fail('inconsistent-terms');
+        }
+        if (DIRECT_TRIG_FNS.has(name)) {
+            // Degrees in, plain ratio out.
+            const arg = args[0] ?? SCALAR;
+            return arg.len === 0 && arg.ang <= 1
+                ? SCALAR
+                : fail('inconsistent-terms');
+        }
+        if (INVERSE_TRIG_FNS.has(name)) {
+            // atan2's two arguments cancel, so they only need to match.
+            if (!args.every((e) => sameExponents(e, args[0] ?? SCALAR))) {
+                return fail('inconsistent-terms');
+            }
+            angleBases.add(CANONICAL_ANGLE_BASE);
+            return { len: 0, ang: 1 };
+        }
+        if (SCALAR_FNS.has(name)) {
+            return args.every(isScalar) ? SCALAR : fail('inconsistent-terms');
+        }
+        return fail('unsupported-operation');
+    };
+    const exponents = walk(parsed.node);
+    if (!exponents) {
+        return { ok: false, reason: failure ?? 'unsupported-operation' };
+    }
+    if (exponents.ang !== 0) {
+        // Angles don't combine with lengths into anything nameable (a length·deg
+        // has no unit here), and neither does deg².
+        if (exponents.len !== 0 || exponents.ang !== 1) {
+            return { ok: false, reason: 'unnameable-dimension' };
+        }
+        const bases = [...angleBases];
+        return {
+            ok: true,
+            dimension: 'angle',
+            unit: bases.length === 1 ? bases[0] : null,
+            bases,
+        };
+    }
+    if (exponents.len === 0) {
+        return { ok: true, dimension: 'none', unit: null, bases: [] };
+    }
+    if (exponents.len < 1 || exponents.len > 3) {
+        return { ok: false, reason: 'unnameable-dimension' };
+    }
+    const dimension = exponents.len === 1 ? 'length' : exponents.len === 2 ? 'area' : 'volume';
+    const bases = [...lengthBases];
+    return {
+        ok: true,
+        dimension,
+        unit: bases.length === 1
+            ? (UNIT_BY_BASE[bases[0]]?.[exponents.len] ?? null)
+            : null,
+        bases,
+    };
+};
+/**
+ * True when an expression's raw value is already canonical, so omitting
+ * `resultUnit` is correct rather than a 25400× mistake. Only the
+ * no-variable-units form (and dimensionless results) qualifies.
+ */
+export const producesCanonicalValue = (inferred) => inferred.dimension === 'none' ||
+    (inferred.bases.length > 0 &&
+        inferred.bases.every((b) => CANONICAL_BASES.has(b)));
+/** Same physical unit, ignoring display form: `in` ≡ `in_frac`, `ft` ≡ `ft_in_frac`. */
+export const isEquivalentUnit = (a, b) => a === b ||
+    (unitDimension(a) === unitDimension(b) && baseUnitOf(a) === baseUnitOf(b));
+/**
+ * How far off a value is when it carries `actual` but was declared as
+ * `declared` — 144 for in² labelled ft². Used to make validation messages
+ * say what the author will actually see.
+ */
+export const unitScaleRatio = (declared, actual) => toCanonical(1, declared) / toCanonical(1, actual);
+/**
+ * The `resultUnit` an equation should carry, or null when it should be omitted
+ * (dimensionless or already-canonical result) or cannot be derived. An
+ * existing equivalent unit is preserved so `in_frac` isn't churned to `in`.
+ */
+export const deriveResultUnit = (fields, equation) => {
+    const inferred = inferExpressionUnit(fields, equation);
+    if (!inferred.ok || inferred.unit == null)
+        return null;
+    if (producesCanonicalValue(inferred))
+        return null;
+    const current = equation.resultUnit;
+    return current != null && isEquivalentUnit(current, inferred.unit)
+        ? current
+        : inferred.unit;
+};
+// Rebuild an equation without a key, since Firestore rejects `undefined`.
+const withoutResultUnit = (equation) => {
+    const { resultUnit: _dropped, ...rest } = equation;
+    return rest;
+};
+/**
+ * Bring an equation's unit annotations back in line with the fields it
+ * references. Field edits (a dimension switch, a kind change, a deletion) are
+ * written independently of equations, so a stale `variableUnits` entry or
+ * `resultUnit` would otherwise keep converting against a unit the field no
+ * longer uses — the failure mode this whole module exists to prevent.
+ */
+export const reconcileEquationUnits = (fields, equations) => {
+    const fieldById = new Map(fields.map((f) => [f.id, f]));
+    let changed = false;
+    const next = equations.map((equation) => {
+        let repaired = equation;
+        // 1. Variable units must match the dimension of the field they annotate.
+        if (equation.variableUnits) {
+            const variableUnits = {};
+            let unitsChanged = false;
+            for (const [variable, unit] of Object.entries(equation.variableUnits)) {
+                const field = fieldById.get(equation.variableToFieldId[variable] ?? '');
+                if (!field) {
+                    unitsChanged = true; // variable or field is gone
+                    continue;
+                }
+                if (unitDimension(unit) === fieldDimension(field)) {
+                    variableUnits[variable] = unit;
+                    continue;
+                }
+                const replacement = fieldDefaultUnit(field);
+                unitsChanged = true;
+                if (replacement)
+                    variableUnits[variable] = replacement;
+            }
+            if (unitsChanged) {
+                repaired =
+                    Object.keys(variableUnits).length > 0
+                        ? { ...repaired, variableUnits }
+                        : (() => {
+                            const { variableUnits: _dropped, ...rest } = repaired;
+                            return rest;
+                        })();
+            }
+        }
+        // 2. The result unit follows from the repaired variable units.
+        const target = fieldById.get(equation.targetFieldId);
+        const targetDimension = target ? fieldDimension(target) : 'none';
+        if (targetDimension === 'none') {
+            if (repaired.resultUnit != null)
+                repaired = withoutResultUnit(repaired);
+        }
+        else {
+            const derived = deriveResultUnit(fields, repaired);
+            if (derived != null) {
+                if (repaired.resultUnit !== derived) {
+                    repaired = { ...repaired, resultUnit: derived };
+                }
+            }
+            else if (repaired.resultUnit != null &&
+                unitDimension(repaired.resultUnit) !== targetDimension) {
+                // Not derivable AND not even the right dimension: drop it rather than
+                // keep converting a length factor into an area field.
+                repaired = withoutResultUnit(repaired);
+            }
+        }
+        if (repaired !== equation)
+            changed = true;
+        return repaired;
+    });
+    return { equations: next, changed };
+};

package/dist/calculator/index.d.ts

@@ -1,6 +1,7 @@
 export * from './schema.js';
 export * from './categories.js';
 export * from './units.js';
+export * from './expressionUnits.js';
 export * from './evaluate.js';
 export * from './solve.js';
 export * from './instance.js';

package/dist/calculator/index.js

@@ -5,6 +5,7 @@
 export * from './schema.js';
 export * from './categories.js';
 export * from './units.js';
+export * from './expressionUnits.js';
 export * from './evaluate.js';
 export * from './solve.js';
 export * from './instance.js';

package/dist/calculator/schema.d.ts

@@ -111,6 +111,18 @@ export interface CalculatorEquation {
     expression: string;
     /** Variable letter -> field id. */
     variableToFieldId: Record<string, string>;
+    /**
+     * Variable letter -> display unit its value enters the scope in. A mapped
+     * variable without an entry stays canonical (µm-scale) — the pre-1.9
+     * behavior. Unit dimension must match the mapped field's dimension.
+     */
+    variableUnits?: Record<string, CalculatorUnit>;
+    /**
+     * Display unit the expression's RESULT is expressed in; converted back to
+     * canonical before storage/chaining. Only meaningful for measurement/angle
+     * targets — number targets take the result raw. Absent = canonical.
+     */
+    resultUnit?: CalculatorUnit;
 }
 /** A runtime/preview value for one field, in canonical units. */
 export type CalculatorFieldValue = number | string | string[] | null;
@@ -159,6 +171,12 @@ export declare const findEquation: (definition: Pick<CalculatorDefinition, "equa
 export declare const equationForField: (definition: Pick<CalculatorDefinition, "equations">, fieldId: string) => CalculatorEquation | undefined;
 /** The dimension a field's numeric value carries. */
 export declare const fieldDimension: (field: CalculatorField) => FieldDimension;
+/**
+ * The unit a field's value is entered and displayed in, or null for fields
+ * that carry no unit. Also the unit an equation referencing the field starts
+ * out annotated with.
+ */
+export declare const fieldDefaultUnit: (field: CalculatorField) => CalculatorUnit | null;
 /** Fields whose value participates in equations as a number. */
 export declare const isNumericFieldKind: (kind: CalculatorFieldKind) => kind is ColumnType.Number | ColumnType.Measurement | ColumnType.Angle | ColumnType.ConversionTable;
 /** Field kinds an equation may target (compute into). */

package/dist/calculator/schema.js

@@ -13,11 +13,17 @@ import { unitsForDimension } from './units.js';
 // brackets) and every runtime field value is canonical — µm for length, µm²
 // area, µm³ volume, degrees for angle, raw for dimensionless (see units.ts).
 //
-// EXPRESSION SEMANTICS: equations are math.js expressions evaluated over a
-// canonical scope. Numeric literals inside an expression are therefore
-// canonical too (a bare `2` multiplying a length is a plain scalar; a bare
-// additive length constant would be micrometers). Authors should express
-// length constants as input fields with a defaultValue instead of literals.
+// EXPRESSION SEMANTICS: equations are math.js expressions. By default they
+// evaluate over a canonical scope, which makes numeric literals canonical too
+// (a bare `2` multiplying a length is a plain scalar; a bare additive length
+// constant would be micrometers). Per-equation `variableUnits` / `resultUnit`
+// instead evaluate in author-chosen display units: each mapped variable is
+// converted OUT of canonical into its unit before entering the scope, and the
+// result is converted back FROM `resultUnit` into canonical. This is what
+// makes literals meaningful ("roof area in ft² / 100 = roofing squares") —
+// without it, a number-kind output consuming a measurement variable silently
+// receives µm-scale values. The authoring UI always sets units; the bare
+// canonical form survives for pre-existing definitions.
 // ---------------------------------------------------------------------------
 /**
  * Version of the definition format itself. Bumped only on breaking schema
@@ -53,6 +59,21 @@ export const fieldDimension = (field) => {
             return 'none';
     }
 };
+/**
+ * The unit a field's value is entered and displayed in, or null for fields
+ * that carry no unit. Also the unit an equation referencing the field starts
+ * out annotated with.
+ */
+export const fieldDefaultUnit = (field) => {
+    switch (field.kind) {
+        case ColumnType.Measurement:
+            return field.unit.defaultUnit;
+        case ColumnType.Angle:
+            return field.angleUnit ?? 'deg';
+        default:
+            return null;
+    }
+};
 /** Fields whose value participates in equations as a number. */
 export const isNumericFieldKind = (kind) => kind === ColumnType.Number ||
     kind === ColumnType.Measurement ||

package/dist/calculator/validate.d.ts

@@ -157,6 +157,8 @@ export declare const calculatorDefinitionSchema: z.ZodObject<{
         targetFieldId: z.ZodString;
         expression: z.ZodString;
         variableToFieldId: z.ZodRecord<z.ZodString, z.ZodString>;
+        variableUnits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        resultUnit: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     diagramFileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     isPublic: z.ZodBoolean;
@@ -182,8 +184,16 @@ export interface ValidationResult {
     ok: boolean;
     issues: ValidationIssue[];
 }
-/** Free variables of an expression (function names and constants excluded). */
-export declare const expressionSymbols: (expression: string) => {
+/**
+ * Free variables of an expression (function names and constants excluded).
+ *
+ * `knownVariables` are treated as variables even when mathjs would resolve
+ * them as constants: the authoring UI names variables A, B, C… and `E` is
+ * Euler's number, so without this a mapped `E` reads as a constant and gets
+ * reported as an unused variable. Evaluation is unaffected — a scope entry
+ * shadows the constant — so this only realigns validation with reality.
+ */
+export declare const expressionSymbols: (expression: string, knownVariables?: Iterable<string>) => {
     ok: true;
     symbols: string[];
 } | {