@reekon-tools/boldr-utils 1.9.6 → 1.10.1

package/dist/calculator/expressionUnits.js

@@ -1,7 +1,8 @@
 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';
+import { ColumnType } from '../types/firestore.js';
+import { bindingDefaultUnit, bindingDimension, bindingUnitForBase, equationBindings, fieldDimension, } from './schema.js';
+import { findConversionColumn } from './conversionTable.js';
+import { UNIT_BY_BASE, equationBaseOfUnit, isEquationBase, toCanonical, unitBase, unitDimension, unitForBase, } from './units.js';
 const math = create(all);
 // ---------------------------------------------------------------------------
 // Expression unit inference.
@@ -43,23 +44,41 @@ export const MATHJS_CONSTANTS = new Set([
     'NaN',
     'null',
 ]);
+// Parse cache, mirroring evaluate.ts's compile cache and sized to match. Unit
+// inference now runs on the evaluation path (an equation's scope units are
+// derived from its base, not read off the document), so the same handful of
+// expressions get parsed on every keystroke of the editor preview.
+//
+// The cached node is handed to callers directly. Every consumer in this
+// package only reads it — `traverse` in expressionSymbols, the structural walk
+// below — so nothing mutates the shared tree.
+const parseCache = new Map();
+const PARSE_CACHE_MAX = 200;
 /** Shared mathjs parse — the one place expression text becomes a tree. */
 export const parseExpression = (expression) => {
+    const hit = parseCache.get(expression);
+    if (hit)
+        return hit;
+    let result;
     try {
-        return { ok: true, node: math.parse(expression) };
+        result = { ok: true, node: math.parse(expression) };
     }
     catch (err) {
-        return {
+        result = {
             ok: false,
             error: err instanceof Error ? err.message : String(err),
         };
     }
+    if (parseCache.size >= PARSE_CACHE_MAX)
+        parseCache.clear();
+    parseCache.set(expression, result);
+    return result;
 };
 // 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];
+const baseUnitOf = unitBase;
 /**
  * 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
@@ -68,17 +87,6 @@ const baseUnitOf = (unit) => (CALCULATOR_UNIT_INFO[unit]?.mathUnit ?? '').split(
 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;
@@ -143,7 +151,7 @@ export const inferExpressionUnit = (fields, equation) => {
         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 dimension = bindingDimension(field, equation.variableColumnIds?.[name]);
             const exponents = EXPONENTS_BY_DIMENSION[dimension];
             noteBases(exponents, dimension === 'angle' ? CANONICAL_ANGLE_BASE : CANONICAL_LENGTH_BASE);
             return exponents;
@@ -300,28 +308,35 @@ export const inferExpressionUnit = (fields, equation) => {
     if (!exponents) {
         return { ok: false, reason: failure ?? 'unsupported-operation' };
     }
+    // Every success path reports both axes; `bases` narrows to whichever axis
+    // the RESULT lives on.
+    const axes = { lengthBases: [...lengthBases], angleBases: [...angleBases] };
     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];
+        const bases = axes.angleBases;
         return {
             ok: true,
             dimension: 'angle',
             unit: bases.length === 1 ? bases[0] : null,
             bases,
+            ...axes,
         };
     }
     if (exponents.len === 0) {
-        return { ok: true, dimension: 'none', unit: null, bases: [] };
+        // Dimensionless. `bases` is empty because the RESULT names no unit — but
+        // the per-axis lists still carry what went in, which is the only record
+        // that a cancelling ratio mixed inches with feet.
+        return { ok: true, dimension: 'none', unit: null, bases: [], ...axes };
     }
     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];
+    const bases = axes.lengthBases;
     return {
         ok: true,
         dimension,
@@ -329,6 +344,7 @@ export const inferExpressionUnit = (fields, equation) => {
             ? (UNIT_BY_BASE[bases[0]]?.[exponents.len] ?? null)
             : null,
         bases,
+        ...axes,
     };
 };
 /**
@@ -364,73 +380,312 @@ export const deriveResultUnit = (fields, equation) => {
         ? current
         : inferred.unit;
 };
+// ---------------------------------------------------------------------------
+// Base-anchored derivation.
+//
+// With `CalculatorEquation.base` set, units stop being authored and become a
+// function of (base, binding dimension). `deriveVariableUnits` answers "what
+// does each variable arrive as", `deriveResultUnitForBase` answers "what does
+// the expression hand back", and `deriveEquationBase` picks a base for an
+// equation that predates the field.
+// ---------------------------------------------------------------------------
+/** The scope unit for every variable of a base-anchored equation. */
+export const deriveVariableUnits = (base, fields, equation) => {
+    const fieldById = new Map(fields.map((f) => [f.id, f]));
+    const units = {};
+    for (const { variable, fieldId, columnId } of equationBindings(equation)) {
+        const field = fieldById.get(fieldId);
+        if (!field)
+            continue;
+        const unit = bindingUnitForBase(base, field, columnId);
+        if (unit != null)
+            units[variable] = unit;
+    }
+    return units;
+};
+/** The unit a base-anchored expression's raw value carries. */
+export const deriveResultUnitForBase = (base, fields, equation) => {
+    const inferred = inferExpressionUnit(fields, {
+        ...equation,
+        variableUnits: deriveVariableUnits(base, fields, equation),
+    });
+    if (!inferred.ok)
+        return { kind: 'unknown' };
+    if (inferred.dimension === 'none' || inferred.dimension === 'angle') {
+        return { kind: 'none' };
+    }
+    const unit = unitForBase(base, inferred.dimension);
+    return unit ? { kind: 'unit', unit } : { kind: 'unknown' };
+};
+/** Inert default when an equation has no length-valued binding at all. */
+export const DEFAULT_EQUATION_BASE = 'in';
+const LENGTH_DIMENSIONS = new Set(['length', 'area', 'volume']);
+// Most frequent base wins; ties break toward the first one seen, so the result
+// is stable across runs (variable order is the document's own key order).
+const mostCommon = (bases) => {
+    if (bases.length === 0)
+        return null;
+    const counts = new Map();
+    for (const b of bases)
+        counts.set(b, (counts.get(b) ?? 0) + 1);
+    let best = bases[0];
+    for (const b of bases) {
+        if ((counts.get(b) ?? 0) > (counts.get(best) ?? 0))
+            best = b;
+    }
+    return best;
+};
+/**
+ * The base a pre-`base` equation should adopt, in descending order of what the
+ * source can be trusted to mean:
+ *
+ *   1. A bound conversion COLUMN's unit. A cell reading "5.33" is literal text
+ *      a human typed; its unit is the only thing that says what the number is,
+ *      so it is the one declaration in the equation that cannot be re-expressed
+ *      without reinterpreting authored data.
+ *   2. An existing `variableUnits` entry — the author's own stated intent,
+ *      even if it disagreed with its neighbours.
+ *   3. A bound measurement field's display unit. Values are stored canonically,
+ *      so this only reflects a preference, but it is the author's preference.
+ *   4. Nothing length-valued in the equation, so the base cannot matter.
+ *
+ * Declines entirely (`base: null`) when a variable is ALREADY authored in a
+ * unit no base can name — cubic yards, liters, gallons. Re-expressing those is
+ * numerically lossless but semantically not: a gravel estimator multiplying a
+ * cu_yd volume by a tons-per-cubic-yard constant is correct only while the
+ * volume stays in cubic yards, and that constant is a bare number with nothing
+ * to declare its units. Silently rebasing it to cu_in would make the answer
+ * 46,656× too large. Better to leave such an equation on the pre-base path,
+ * where the mixed-base check still watches it, than to guess.
+ */
+export const deriveEquationBase = (fields, equation) => {
+    const fieldById = new Map(fields.map((f) => [f.id, f]));
+    const fromColumns = [];
+    const fromVariableUnits = [];
+    const fromFieldDefaults = [];
+    const blockedBy = [];
+    for (const { variable, fieldId, columnId } of equationBindings(equation)) {
+        const field = fieldById.get(fieldId);
+        if (!field)
+            continue;
+        // Only length-family bindings can disagree about scale; angles are their
+        // own axis and dimensionless bindings carry nothing.
+        if (!LENGTH_DIMENSIONS.has(bindingDimension(field, columnId)))
+            continue;
+        // bindingDefaultUnit resolves an absent/unknown column id to the first
+        // column, matching what the evaluator actually reads.
+        const columnUnit = field.kind === ColumnType.ConversionTable
+            ? bindingDefaultUnit(field, columnId)
+            : null;
+        const declared = equation.variableUnits?.[variable];
+        // The unit this variable is evaluating in TODAY. That is what a base has
+        // to be able to reproduce; a field's display default is only a preference.
+        const effective = declared ?? columnUnit;
+        if (effective != null && equationBaseOfUnit(effective) == null) {
+            blockedBy.push(effective);
+            continue;
+        }
+        if (columnUnit) {
+            const base = equationBaseOfUnit(columnUnit);
+            if (base)
+                fromColumns.push(base);
+        }
+        if (declared) {
+            const base = equationBaseOfUnit(declared);
+            if (base)
+                fromVariableUnits.push(base);
+        }
+        if (field.kind === ColumnType.Measurement) {
+            const base = equationBaseOfUnit(field.unit.defaultUnit);
+            if (base)
+                fromFieldDefaults.push(base);
+        }
+    }
+    if (blockedBy.length > 0) {
+        return {
+            base: null,
+            source: 'unanchorable',
+            candidates: [],
+            blockedBy: [...new Set(blockedBy)],
+        };
+    }
+    const tiers = [
+        ['conversion-column', fromColumns],
+        ['variable-unit', fromVariableUnits],
+        ['field-default', fromFieldDefaults],
+    ];
+    for (const [source, candidates] of tiers) {
+        const base = mostCommon(candidates);
+        if (base)
+            return { base, source, candidates: [...new Set(candidates)] };
+    }
+    return {
+        base: DEFAULT_EQUATION_BASE,
+        source: 'fallback',
+        candidates: [],
+    };
+};
 // Rebuild an equation without a key, since Firestore rejects `undefined`.
 const withoutResultUnit = (equation) => {
     const { resultUnit: _dropped, ...rest } = equation;
     return rest;
 };
+// Rebuild an equation without a key, since Firestore rejects `undefined`.
+const withoutVariableColumnIds = (equation) => {
+    const { variableColumnIds: _dropped, ...rest } = equation;
+    return rest;
+};
+// Rebuild an equation without a key, since Firestore rejects `undefined`.
+const withoutVariableUnits = (equation) => {
+    const { variableUnits: _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.
+ * The pre-base repair, kept verbatim for equations that cannot adopt a base.
+ * It only realigns a unit whose DIMENSION no longer matches its binding — it
+ * has no opinion about bases, which is precisely why it is safe here: an
+ * equation holding cubic yards keeps holding cubic yards.
+ */
+const reconcileLegacyUnits = (fields, fieldById, equation) => {
+    let repaired = equation;
+    if (repaired.variableUnits) {
+        const variableUnits = {};
+        let unitsChanged = false;
+        for (const [variable, unit] of Object.entries(repaired.variableUnits)) {
+            const field = fieldById.get(repaired.variableToFieldId[variable] ?? '');
+            if (!field) {
+                unitsChanged = true; // variable or field is gone
+                continue;
+            }
+            const columnId = repaired.variableColumnIds?.[variable];
+            if (unitDimension(unit) === bindingDimension(field, columnId)) {
+                variableUnits[variable] = unit;
+                continue;
+            }
+            const replacement = bindingDefaultUnit(field, columnId);
+            unitsChanged = true;
+            if (replacement)
+                variableUnits[variable] = replacement;
+        }
+        if (unitsChanged) {
+            repaired =
+                Object.keys(variableUnits).length > 0
+                    ? { ...repaired, variableUnits }
+                    : withoutVariableUnits(repaired);
+        }
+    }
+    const target = fieldById.get(repaired.targetFieldId);
+    const targetDimension = target ? fieldDimension(target) : 'none';
+    if (targetDimension === 'none') {
+        if (repaired.resultUnit != null)
+            repaired = withoutResultUnit(repaired);
+        return repaired;
+    }
+    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);
+    }
+    return repaired;
+};
+/**
+ * Bring an equation's field-derived annotations — variable column bindings,
+ * variable units, result unit — back in line with the fields it references.
+ * Field edits (a dimension switch, a kind change, a deleted conversion column,
+ * a deleted field) are written independently of equations, so a stale entry
+ * would otherwise keep converting against a unit or reading a column the field
+ * no longer has — 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)) {
+        // 1. Column bindings must name a column the bound field still has. A
+        //    dropped entry falls back to the first column, which is the same
+        //    reading the evaluator gives it — so pruning here only removes a lie,
+        //    it never changes what the equation computes.
+        if (equation.variableColumnIds) {
+            const variableColumnIds = {};
+            let bindingsChanged = false;
+            for (const [variable, columnId] of Object.entries(equation.variableColumnIds)) {
                 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;
+                if (field?.kind === ColumnType.ConversionTable &&
+                    findConversionColumn(field.columnData, columnId)) {
+                    variableColumnIds[variable] = columnId;
                     continue;
                 }
-                const replacement = fieldDefaultUnit(field);
-                unitsChanged = true;
-                if (replacement)
-                    variableUnits[variable] = replacement;
+                bindingsChanged = true;
             }
-            if (unitsChanged) {
+            if (bindingsChanged) {
                 repaired =
-                    Object.keys(variableUnits).length > 0
-                        ? { ...repaired, variableUnits }
-                        : (() => {
-                            const { variableUnits: _dropped, ...rest } = repaired;
-                            return rest;
-                        })();
+                    Object.keys(variableColumnIds).length > 0
+                        ? { ...repaired, variableColumnIds }
+                        : withoutVariableColumnIds(repaired);
             }
         }
-        // 2. The result unit follows from the repaired variable units.
+        // 2. Adopt a base. An equation authored before bases existed gets one
+        //    inferred from what it already says (deriveEquationBase), so opening
+        //    an old calculator and touching a field migrates it in place. An
+        //    unrecognized stored base is treated as absent rather than trusted.
+        //    Read against `repaired`: step 1 may have moved a variable back to the
+        //    first column, whose unit is what the base should follow.
+        //
+        //    An EXPLICIT base always wins — converting a cu_yd column into ft³ is
+        //    well defined, and an author who asked for it meant it. Only the
+        //    inference declines, and only for an equation already sitting in a
+        //    unit family no base can name (see deriveEquationBase).
+        const base = isEquationBase(repaired.base)
+            ? repaired.base
+            : deriveEquationBase(fields, repaired).base;
+        if (base == null) {
+            // Unanchorable: leave it exactly as the pre-base code would have.
+            repaired = reconcileLegacyUnits(fields, fieldById, repaired);
+            if (repaired !== equation)
+                changed = true;
+            return repaired;
+        }
+        if (repaired.base !== base)
+            repaired = { ...repaired, base };
+        // 3. Variable units are fully determined by the base and each binding's
+        //    dimension, so they are not stored at all — the evaluator derives them.
+        //    Anything left over from the pre-base form is dead weight that a reader
+        //    would reasonably mistake for the source of truth.
+        if (repaired.variableUnits != null) {
+            repaired = withoutVariableUnits(repaired);
+        }
+        // 4. The result unit is derived the same way, with ONE exception worth
+        //    persisting: an expression whose units inference cannot model at all
+        //    (an unmodelled function, a dimension this vocabulary can't name). The
+        //    base says nothing useful there, so the author picks, and that choice
+        //    is real authored data rather than a cache.
+        //
+        //    Number targets take the raw value either way — that is what makes
+        //    `area_in_ft² / 33` read as 33 ft², not 33 µm².
         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 &&
+        const derived = targetDimension === 'none'
+            ? { kind: 'none' }
+            : deriveResultUnitForBase(base, fields, repaired);
+        if (derived.kind === 'unknown') {
+            // Keep the author's pick, unless it isn't even the target's dimension —
+            // that would convert a length factor into an area field.
+            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);
             }
         }
+        else if (repaired.resultUnit != null) {
+            // Derivable, so a stored unit is either redundant or wrong. Drop it.
+            repaired = withoutResultUnit(repaired);
+        }
         if (repaired !== equation)
             changed = true;
         return repaired;

package/dist/calculator/index.d.ts

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

package/dist/calculator/index.js

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

package/dist/calculator/schema.d.ts

@@ -1,5 +1,5 @@
 import { ColumnType, type ColumnConfig, type ConversionTableColumnData, type InstructionsColumnData, type SelectColumnData, type DecimalTolerance, type FractionalTolerance } from '../types/firestore.js';
-import type { AngleUnit, CalculatorUnit, FieldDimension, MeasurementDimension } from './units.js';
+import type { AngleUnit, CalculatorUnit, EquationBase, FieldDimension, MeasurementDimension } from './units.js';
 import type { CalculatorCategoryId } from './categories.js';
 /**
  * Version of the definition format itself. Bumped only on breaking schema
@@ -112,15 +112,55 @@ export interface CalculatorEquation {
     /** 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.
+     * Variable letter -> `ConversionColumn.id`, for variables bound to a
+     * conversion-table field. Absent (or absent for one letter) means that
+     * variable reads the table's FIRST column — the only reading under which
+     * equations written before multi-column tables keep computing.
+     *
+     * Two letters may map to the same field with different columns: that is the
+     * whole point, one row selection feeding several terms of an expression.
+     */
+    variableColumnIds?: Record<string, string>;
+    /**
+     * The ONE length base this expression evaluates in ('ft', 'in', 'mm', …) —
+     * and, when present, the only unit information the equation stores. Each
+     * variable's scope unit is this base at the variable's own exponent (ft,
+     * ft², ft³); the result unit is this base at the result's exponent. Both are
+     * computed on demand, never written down.
+     *
+     * This exists because per-variable units could disagree. Authoring
+     * `(A_in * B_in) / C_ft²` passed every dimensional check — length·length ÷
+     * area cancels to a valid dimensionless count — while computing 144× the
+     * truth, because nothing reconciled inches against feet. A single base makes
+     * that unrepresentable rather than merely detectable.
+     *
+     * The base is per EQUATION, not per calculator: values are stored
+     * canonically, so two equations may work in different bases and still feed
+     * each other — each converts in and out at its own edge.
+     *
+     * Absent means the pre-base form below. Still read, because saved instances
+     * freeze their definition and older docs migrate lazily, but never written
+     * for new equations.
+     */
+    base?: EquationBase;
+    /**
+     * LEGACY (pre-`base`). Variable letter -> display unit its value enters the
+     * scope in; a mapped variable with no entry stays canonical (µm-scale).
+     *
+     * Ignored entirely when `base` is set, and stripped by
+     * reconcileEquationUnits, since the base determines every one of these — a
+     * stored copy could only go stale and be mistaken for the source of truth.
      */
     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.
+     *
+     * With `base` set this survives in ONE case: an expression whose units
+     * inference cannot model (an unmodelled function, an unnameable dimension).
+     * The base yields no answer there, so the author picks one and it is real
+     * authored data. Everywhere else it is derived and not stored.
      */
     resultUnit?: CalculatorUnit;
 }
@@ -171,12 +211,55 @@ 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;
+/**
+ * What one equation VARIABLE binds to: a field, and for a conversion table
+ * which of its value columns. Everything downstream of the variable map — unit
+ * inference, validation, the scope build — needs the pair, because a
+ * conversion table's dimension is a property of the column, not the field.
+ */
+export interface VariableBinding {
+    fieldId: string;
+    /** Undefined for non-conversion fields and for first-column bindings. */
+    columnId?: string;
+}
+/** The binding for one variable letter, or null when the letter is unmapped. */
+export declare const equationBinding: (equation: Pick<CalculatorEquation, "variableToFieldId" | "variableColumnIds">, variable: string) => VariableBinding | null;
+/** Every variable's binding, in the variable map's order. */
+export declare const equationBindings: (equation: Pick<CalculatorEquation, "variableToFieldId" | "variableColumnIds">) => (VariableBinding & {
+    variable: string;
+})[];
+/**
+ * The dimension a BOUND value carries. Same as `fieldDimension` for every kind
+ * but a conversion table, where a column may declare a unit and so give the
+ * binding a real dimension — the thing that lets `width · depth` off one table
+ * row infer as an area rather than a bare product.
+ */
+export declare const bindingDimension: (field: CalculatorField, columnId?: string) => 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;
+/**
+ * The unit a BOUND value is DECLARED in — the conversion column's unit for a
+ * table binding (the unit the cell text was typed in), the field's display
+ * unit otherwise. This is what the value means at rest, not what it means
+ * inside an equation; `bindingUnitForBase` converts it to the latter.
+ */
+export declare const bindingDefaultUnit: (field: CalculatorField, columnId?: string) => CalculatorUnit | null;
+/**
+ * The unit a bound value enters a base-anchored equation's scope in — the
+ * base's member at the binding's own exponent, so a length arrives in `ft` and
+ * an area off the same equation in `ft²`.
+ *
+ * Never an author choice, and deliberately independent of how the value is
+ * declared or displayed: a column typed in ft² feeding an inch-based equation
+ * converts to in², which is a lossless re-expression of the same quantity, not
+ * a reinterpretation of the author's cell text. Returns null for dimensionless
+ * bindings, which enter the scope raw.
+ */
+export declare const bindingUnitForBase: (base: EquationBase, field: CalculatorField, columnId?: string) => 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). */