@reekon-tools/boldr-utils 1.9.6 → 1.10.1

package/dist/calculator/conversionTable.d.ts

@@ -0,0 +1,81 @@
+import type { Conversion, ConversionColumn, ConversionTableColumnData } from '../types/firestore.js';
+import { type FieldDimension } from './units.js';
+/**
+ * Id of the implicit first column. Stable and reserved: a table that has never
+ * been given explicit columns is addressed by this id, so equations written
+ * against a single-column table keep resolving after columns are added (the
+ * editor preserves it as `columns[0].id`).
+ */
+export declare const DEFAULT_CONVERSION_COLUMN_ID = "value";
+/** Name shown for the implicit first column. */
+export declare const DEFAULT_CONVERSION_COLUMN_NAME = "Value";
+/**
+ * A table's value columns, always at least one. An absent or empty `columns`
+ * normalizes to the single implicit column, so callers never branch on shape.
+ */
+export declare const conversionColumns: (data: Pick<ConversionTableColumnData, "columns">) => ConversionColumn[];
+/** True when equations must name a column to be unambiguous. */
+export declare const hasMultipleConversionColumns: (data: Pick<ConversionTableColumnData, "columns">) => boolean;
+/**
+ * The column an equation variable binds to. An absent/unknown `columnId` is the
+ * first column: that is what a binding written before multi-column tables
+ * meant, and the only reading that keeps such equations computing.
+ */
+export declare const resolveConversionColumn: (data: Pick<ConversionTableColumnData, "columns">, columnId?: string) => ConversionColumn;
+export declare const findConversionColumn: (data: Pick<ConversionTableColumnData, "columns">, columnId: string) => ConversionColumn | undefined;
+/** Raw cell text for one row/column, or '' when the cell was never filled. */
+export declare const conversionCellValue: (data: Pick<ConversionTableColumnData, "columns">, conversion: Conversion, columnId: string) => string;
+/**
+ * `conversion` with one cell replaced, honouring the column-0-in-`value` rule.
+ * Returns a new object; `values` is omitted entirely when it would be empty so
+ * Firestore never receives a stray `{}`.
+ */
+export declare const writeConversionCell: (data: Pick<ConversionTableColumnData, "columns">, conversion: Conversion, columnId: string, cell: string) => Conversion;
+/** The dimension a column's values carry — 'none' for an unannotated column. */
+export declare const conversionColumnDimension: (column: ConversionColumn) => FieldDimension;
+/**
+ * The CANONICAL number a cell contributes to an equation, or null when the
+ * cell is blank or unparseable. Unit-less columns pass their value through
+ * unchanged (the historical meaning of a conversion factor); a column with a
+ * unit converts, so downstream code can treat it like any measurement value.
+ */
+export declare const conversionCellNumber: (data: Pick<ConversionTableColumnData, "columns">, conversion: Conversion, columnId?: string) => number | null;
+/** The row a selected label refers to. */
+export declare const findConversionRow: (data: Pick<ConversionTableColumnData, "conversions">, label: string) => Conversion | undefined;
+/**
+ * How a column is named in a chip, a picker or a validation message. Falls back
+ * to the positional `[i]` form the column is otherwise anonymous — an unnamed
+ * column still has to be tellable apart from its neighbours.
+ */
+export declare const conversionColumnLabel: (data: Pick<ConversionTableColumnData, "columns">, columnId?: string) => string;
+/**
+ * Qualified name for a binding — what the formula builder puts on a chip and
+ * what validation quotes back. Single-column tables read as the bare field
+ * name, so nothing changes for the tables that already exist.
+ */
+export declare const conversionBindingLabel: (fieldName: string, data: Pick<ConversionTableColumnData, "columns">, columnId?: string) => string;
+export interface ConversionRowDraft {
+    label: string;
+    /** Cell text per column id. Missing entries are treated as blank. */
+    cells: Record<string, string>;
+}
+/**
+ * Serialize an editor's (columns, rows) working state into storage shape.
+ * The single place the column-0 split is applied on write, and the reason the
+ * editor can add, rename, unit-annotate, reorder and delete columns without
+ * ever reasoning about which key a cell belongs in.
+ *
+ * A table whose only column is the plain implicit one is written WITHOUT a
+ * `columns` key, so it stays byte-identical to what the pre-multi-column editor
+ * produced — no schema churn on every table that doesn't use the feature. A
+ * single column that has been named or given a unit IS persisted: dropping it
+ * would silently discard the annotation.
+ */
+export declare const buildConversionTableColumnData: (columns: ConversionColumn[], rows: ConversionRowDraft[]) => ConversionTableColumnData;
+/** Storage shape back to editor working state. */
+export declare const toConversionRowDrafts: (data: ConversionTableColumnData) => ConversionRowDraft[];
+/** Convenience for pickers: every column's cell text for one row. */
+export declare const conversionRowCells: (data: ConversionTableColumnData, conversion: Conversion) => {
+    column: ConversionColumn;
+    value: string;
+}[];

package/dist/calculator/conversionTable.js

@@ -0,0 +1,170 @@
+import { toCanonical, unitDimension, } from './units.js';
+// ---------------------------------------------------------------------------
+// Multi-column conversion tables.
+//
+// A conversion table is a labelled lookup: the operator picks a ROW ("2x4",
+// "30-year architectural") and the calculator gets a number. With more than one
+// VALUE COLUMN, one selection carries several numbers — nominal vs. actual
+// dimensions, weight and price per unit, rise and run — and an equation binds
+// to a specific (field, column) pair rather than just the field.
+//
+// STORAGE (see types/firestore.ts): column 0's cell text lives in
+// `Conversion.value`, columns 1..n in `Conversion.values[columnId]`. That split
+// is not tidiness — `value` is the only key readers that predate this feature
+// know about (job grids, label tiles, template formulas), so keeping column 0
+// there means a table authored in a calculator still reads correctly
+// everywhere else. Nothing outside this module should apply the rule by hand:
+// go through `conversionCellValue` / `writeConversionCell`.
+//
+// UNITS: a column may declare the unit its cell text is written in. Cells then
+// convert to canonical (µm/µm²/µm³/deg) on the way into an equation, so a
+// column of inch values composes with measurement fields and with the unit
+// inference in expressionUnits.ts. A column with no unit stays a plain scalar,
+// which is exactly what a single-column table has always been.
+// ---------------------------------------------------------------------------
+/**
+ * Id of the implicit first column. Stable and reserved: a table that has never
+ * been given explicit columns is addressed by this id, so equations written
+ * against a single-column table keep resolving after columns are added (the
+ * editor preserves it as `columns[0].id`).
+ */
+export const DEFAULT_CONVERSION_COLUMN_ID = 'value';
+/** Name shown for the implicit first column. */
+export const DEFAULT_CONVERSION_COLUMN_NAME = 'Value';
+const IMPLICIT_COLUMN = {
+    id: DEFAULT_CONVERSION_COLUMN_ID,
+    name: DEFAULT_CONVERSION_COLUMN_NAME,
+};
+/**
+ * A table's value columns, always at least one. An absent or empty `columns`
+ * normalizes to the single implicit column, so callers never branch on shape.
+ */
+export const conversionColumns = (data) => data.columns && data.columns.length > 0 ? data.columns : [IMPLICIT_COLUMN];
+/** True when equations must name a column to be unambiguous. */
+export const hasMultipleConversionColumns = (data) => conversionColumns(data).length > 1;
+/**
+ * The column an equation variable binds to. An absent/unknown `columnId` is the
+ * first column: that is what a binding written before multi-column tables
+ * meant, and the only reading that keeps such equations computing.
+ */
+export const resolveConversionColumn = (data, columnId) => {
+    const columns = conversionColumns(data);
+    if (columnId == null)
+        return columns[0];
+    return columns.find((c) => c.id === columnId) ?? columns[0];
+};
+export const findConversionColumn = (data, columnId) => conversionColumns(data).find((c) => c.id === columnId);
+/** Raw cell text for one row/column, or '' when the cell was never filled. */
+export const conversionCellValue = (data, conversion, columnId) => {
+    const columns = conversionColumns(data);
+    return columnId === columns[0].id
+        ? conversion.value
+        : (conversion.values?.[columnId] ?? '');
+};
+/**
+ * `conversion` with one cell replaced, honouring the column-0-in-`value` rule.
+ * Returns a new object; `values` is omitted entirely when it would be empty so
+ * Firestore never receives a stray `{}`.
+ */
+export const writeConversionCell = (data, conversion, columnId, cell) => {
+    const columns = conversionColumns(data);
+    if (columnId === columns[0].id)
+        return { ...conversion, value: cell };
+    const values = { ...conversion.values, [columnId]: cell };
+    return { ...conversion, values };
+};
+/** The dimension a column's values carry — 'none' for an unannotated column. */
+export const conversionColumnDimension = (column) => column.unit != null ? unitDimension(column.unit) : 'none';
+/**
+ * The CANONICAL number a cell contributes to an equation, or null when the
+ * cell is blank or unparseable. Unit-less columns pass their value through
+ * unchanged (the historical meaning of a conversion factor); a column with a
+ * unit converts, so downstream code can treat it like any measurement value.
+ */
+export const conversionCellNumber = (data, conversion, columnId) => {
+    const column = resolveConversionColumn(data, columnId);
+    const parsed = parseFloat(conversionCellValue(data, conversion, column.id));
+    if (!Number.isFinite(parsed))
+        return null;
+    return column.unit != null ? toCanonical(parsed, column.unit) : parsed;
+};
+/** The row a selected label refers to. */
+export const findConversionRow = (data, label) => data.conversions.find((c) => c.label === label);
+/**
+ * How a column is named in a chip, a picker or a validation message. Falls back
+ * to the positional `[i]` form the column is otherwise anonymous — an unnamed
+ * column still has to be tellable apart from its neighbours.
+ */
+export const conversionColumnLabel = (data, columnId) => {
+    const columns = conversionColumns(data);
+    // An unknown id resolves to the first column, matching resolveConversionColumn
+    // — the label must name the column the equation will actually read.
+    const found = columnId == null ? -1 : columns.findIndex((c) => c.id === columnId);
+    const index = found < 0 ? 0 : found;
+    return columns[index].name.trim() !== '' ? columns[index].name : `[${index}]`;
+};
+/**
+ * Qualified name for a binding — what the formula builder puts on a chip and
+ * what validation quotes back. Single-column tables read as the bare field
+ * name, so nothing changes for the tables that already exist.
+ */
+export const conversionBindingLabel = (fieldName, data, columnId) => hasMultipleConversionColumns(data)
+    ? `${fieldName} · ${conversionColumnLabel(data, columnId)}`
+    : fieldName;
+/**
+ * True when a column carries nothing the implicit column doesn't already imply,
+ * so persisting it would only add a key. A named or unit-annotated column is
+ * NOT implicit even when it's the only one — that annotation is the difference
+ * between a table of inch values and a table of bare factors.
+ */
+const isImplicitColumn = (column) => column.id === DEFAULT_CONVERSION_COLUMN_ID &&
+    column.unit == null &&
+    (column.name.trim() === '' || column.name === DEFAULT_CONVERSION_COLUMN_NAME);
+/**
+ * Serialize an editor's (columns, rows) working state into storage shape.
+ * The single place the column-0 split is applied on write, and the reason the
+ * editor can add, rename, unit-annotate, reorder and delete columns without
+ * ever reasoning about which key a cell belongs in.
+ *
+ * A table whose only column is the plain implicit one is written WITHOUT a
+ * `columns` key, so it stays byte-identical to what the pre-multi-column editor
+ * produced — no schema churn on every table that doesn't use the feature. A
+ * single column that has been named or given a unit IS persisted: dropping it
+ * would silently discard the annotation.
+ */
+export const buildConversionTableColumnData = (columns, rows) => {
+    const effective = columns.length > 0 ? columns : [IMPLICIT_COLUMN];
+    const [first, ...rest] = effective;
+    const conversions = rows.map((row) => {
+        const values = {};
+        for (const column of rest) {
+            const cell = row.cells[column.id];
+            if (cell != null && cell !== '')
+                values[column.id] = cell;
+        }
+        return {
+            label: row.label,
+            value: row.cells[first.id] ?? '',
+            ...(Object.keys(values).length > 0 ? { values } : {}),
+        };
+    });
+    return effective.length === 1 && isImplicitColumn(effective[0])
+        ? { conversions }
+        : { conversions, columns: effective };
+};
+/** Storage shape back to editor working state. */
+export const toConversionRowDrafts = (data) => {
+    const columns = conversionColumns(data);
+    return data.conversions.map((conversion) => ({
+        label: conversion.label,
+        cells: Object.fromEntries(columns.map((column) => [
+            column.id,
+            conversionCellValue(data, conversion, column.id),
+        ])),
+    }));
+};
+/** Convenience for pickers: every column's cell text for one row. */
+export const conversionRowCells = (data, conversion) => conversionColumns(data).map((column) => ({
+    column,
+    value: conversionCellValue(data, conversion, column.id),
+}));

package/dist/calculator/evaluate.d.ts

@@ -16,8 +16,12 @@ export declare const evaluateExpression: (expression: string, scope: Record<stri
  * The canonical numeric value a field contributes to an equation scope, or
  * null when the field has no usable value. Select and instructions fields are
  * non-computational (validation rejects mapping them into equations).
+ *
+ * `columnId` selects which value column a conversion-table field yields; it is
+ * ignored for every other kind. Omitted means the first column, so a caller
+ * that predates multi-column tables reads exactly what it used to.
  */
-export declare const numericFieldValue: (field: CalculatorField, value: CalculatorFieldValue | undefined) => number | null;
+export declare const numericFieldValue: (field: CalculatorField, value: CalculatorFieldValue | undefined, columnId?: string) => number | null;
 export type EquationResult = {
     ok: true;
     value: number;

package/dist/calculator/evaluate.js

@@ -1,7 +1,9 @@
 import { create, all } from 'mathjs';
 import { ColumnType } from '../types/firestore.js';
-import { equationForField, findField } from './schema.js';
-import { fromCanonical, toCanonical } from './units.js';
+import { bindingUnitForBase, equationForField, fieldDimension, findField, } from './schema.js';
+import { conversionCellNumber, findConversionRow } from './conversionTable.js';
+import { deriveResultUnitForBase } from './expressionUnits.js';
+import { fromCanonical, isEquationBase, toCanonical, } from './units.js';
 // Trig in calculator equations works in DEGREES: angle fields are stored in
 // degrees canonically, and construction authors write `H = W * tan(A)`
 // expecting A in degrees. mathjs has no `angle` config option (evaluateFormula
@@ -77,8 +79,12 @@ export const evaluateExpression = (expression, scope) => {
  * The canonical numeric value a field contributes to an equation scope, or
  * null when the field has no usable value. Select and instructions fields are
  * non-computational (validation rejects mapping them into equations).
+ *
+ * `columnId` selects which value column a conversion-table field yields; it is
+ * ignored for every other kind. Omitted means the first column, so a caller
+ * that predates multi-column tables reads exactly what it used to.
  */
-export const numericFieldValue = (field, value) => {
+export const numericFieldValue = (field, value, columnId) => {
     switch (field.kind) {
         case ColumnType.Number:
         case ColumnType.Measurement:
@@ -87,21 +93,61 @@ export const numericFieldValue = (field, value) => {
             return typeof v === 'number' && Number.isFinite(v) ? v : null;
         }
         case ColumnType.ConversionTable: {
-            // Value is the selected conversion's label; the numeric factor comes
-            // from the matched entry (Conversion.value is a string app-wide).
+            // The stored value is the selected ROW's label; the number comes from
+            // that row's cell in the requested column (cells are strings app-wide,
+            // and a unit-annotated column converts to canonical on the way out).
             const label = value ?? field.defaultValue;
             if (typeof label !== 'string')
                 return null;
-            const entry = field.columnData.conversions.find((c) => c.label === label);
-            if (!entry)
+            const row = findConversionRow(field.columnData, label);
+            if (!row)
                 return null;
-            const parsed = parseFloat(entry.value);
-            return Number.isFinite(parsed) ? parsed : null;
+            return conversionCellNumber(field.columnData, row, columnId);
         }
         default:
             return null;
     }
 };
+// ---------------------------------------------------------------------------
+// Scope units.
+//
+// A base-anchored equation derives every unit from its base rather than
+// reading `variableUnits` / `resultUnit` off the document. Those fields are
+// still written (older app builds evaluate from them), but they are a cache of
+// this derivation — and trusting a cache over its source is exactly how a
+// stale entry silently rescales a live answer. So the evaluator recomputes.
+//
+// Equations with no base keep the legacy reading, byte for byte: saved
+// calculator instances freeze their definition, so pre-base equations must go
+// on evaluating exactly as they did the day they were saved.
+// ---------------------------------------------------------------------------
+/** The unit one variable's canonical value is re-expressed in before scoping. */
+const scopeUnitFor = (definition, equation, variable, fieldId) => {
+    if (!isEquationBase(equation.base)) {
+        return equation.variableUnits?.[variable] ?? null;
+    }
+    const field = findField(definition, fieldId);
+    if (!field)
+        return null;
+    return bindingUnitForBase(equation.base, field, equation.variableColumnIds?.[variable]);
+};
+/** The unit the expression's raw result carries, or null when it needs none. */
+const resultUnitFor = (definition, equation) => {
+    if (!isEquationBase(equation.base))
+        return equation.resultUnit ?? null;
+    const target = findField(definition, equation.targetFieldId);
+    // A number target takes the raw value — the whole point of evaluating in
+    // display units is that `area_in_ft² / 33` yields squares, not µm².
+    if (!target || fieldDimension(target) === 'none')
+        return null;
+    const derived = deriveResultUnitForBase(equation.base, definition.fields, equation);
+    if (derived.kind === 'unit')
+        return derived.unit;
+    if (derived.kind === 'none')
+        return null;
+    // Inference declined; the author's stored unit is the only information left.
+    return equation.resultUnit ?? null;
+};
 const evaluateEquationInContext = (equation, ctx) => {
     const cached = ctx.cache.get(equation.id);
     if (cached)
@@ -118,7 +164,7 @@ const evaluateEquationInContext = (equation, ctx) => {
         const scope = {};
         const missing = [];
         for (const [variable, fieldId] of Object.entries(equation.variableToFieldId)) {
-            const resolved = resolveFieldNumeric(fieldId, ctx);
+            const resolved = resolveFieldNumeric(fieldId, ctx, equation.variableColumnIds?.[variable]);
             if (!resolved.ok) {
                 if (resolved.reason === 'missing-inputs') {
                     missing.push(...resolved.missingFieldIds);
@@ -126,9 +172,9 @@ const evaluateEquationInContext = (equation, ctx) => {
                 }
                 return resolved;
             }
-            // Field values resolve canonically; a variable unit re-expresses the
-            // value in the author's chosen display unit before it enters the scope.
-            const unit = equation.variableUnits?.[variable];
+            // Field values resolve canonically; the scope unit re-expresses each one
+            // in the equation's own terms before it enters the expression.
+            const unit = scopeUnitFor(ctx.definition, equation, variable, fieldId);
             try {
                 scope[variable] =
                     unit != null ? fromCanonical(resolved.value, unit) : resolved.value;
@@ -158,11 +204,12 @@ const evaluateEquationInContext = (equation, ctx) => {
         else {
             // A result unit means the expression produced a display-unit value;
             // convert back so the returned value is canonical like everything else.
+            const resultUnit = resultUnitFor(ctx.definition, equation);
             try {
                 result = {
                     ok: true,
-                    value: equation.resultUnit != null
-                        ? toCanonical(evaluated.value, equation.resultUnit)
+                    value: resultUnit != null
+                        ? toCanonical(evaluated.value, resultUnit)
                         : evaluated.value,
                 };
             }
@@ -185,7 +232,9 @@ const evaluateEquationInContext = (equation, ctx) => {
 // computation is blocked on missing inputs but the user supplied a value for
 // the output directly (the two-way-solving posture), the supplied value is
 // used instead. Everything else resolves from `values`/defaults.
-const resolveFieldNumeric = (fieldId, ctx) => {
+const resolveFieldNumeric = (fieldId, ctx, 
+/** Conversion-table column the referencing variable binds to. */
+columnId) => {
     const field = findField(ctx.definition, fieldId);
     if (!field) {
         return {
@@ -200,13 +249,13 @@ const resolveFieldNumeric = (fieldId, ctx) => {
         if (computed.ok)
             return computed;
         if (computed.reason === 'missing-inputs') {
-            const supplied = numericFieldValue(field, ctx.values[fieldId]);
+            const supplied = numericFieldValue(field, ctx.values[fieldId], columnId);
             if (supplied != null)
                 return { ok: true, value: supplied };
         }
         return computed;
     }
-    const value = numericFieldValue(field, ctx.values[fieldId]);
+    const value = numericFieldValue(field, ctx.values[fieldId], columnId);
     if (value == null) {
         return { ok: false, reason: 'missing-inputs', missingFieldIds: [fieldId] };
     }

package/dist/calculator/expressionUnits.d.ts

@@ -1,6 +1,6 @@
 import { type MathNode } from 'mathjs';
 import type { CalculatorEquation, CalculatorField } from './schema.js';
-import { type CalculatorUnit, type FieldDimension } from './units.js';
+import { type CalculatorUnit, type EquationBase, type FieldDimension } from './units.js';
 /** Constants mathjs resolves without a scope entry. */
 export declare const MATHJS_CONSTANTS: Set<string>;
 export type ParseResult = {
@@ -39,6 +39,20 @@ export interface InferredExpressionUnit {
     unit: CalculatorUnit | null;
     /** Distinct base units among the variables carrying that dimension. */
     bases: string[];
+    /**
+     * Every distinct length-family base the variables contributed, whether or
+     * not the exponents survived to the result.
+     *
+     * Separate from `bases` because `bases` describes the RESULT, and a result
+     * can be dimensionless while its inputs still disagree: `(A_in * B_in) /
+     * C_ft²` cancels to a plain count, so `bases` is empty and `dimension` is
+     * 'none' — and the 144× scale error that ratio carries is invisible there.
+     * Tracked per axis, since a length and an angle in one expression is normal
+     * (trig consumes the angle) while two length bases never is.
+     */
+    lengthBases: string[];
+    /** Every distinct angle base the variables contributed ('deg' / 'rad'). */
+    angleBases: string[];
 }
 export type ExpressionUnitInference = ({
     ok: true;
@@ -50,7 +64,7 @@ export type ExpressionUnitInference = ({
  * 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;
+export declare const inferExpressionUnit: (fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "expression" | "variableToFieldId" | "variableColumnIds" | "variableUnits">) => ExpressionUnitInference;
 /**
  * True when an expression's raw value is already canonical, so omitting
  * `resultUnit` is correct rather than a 25400× mistake. Only the
@@ -70,13 +84,94 @@ export declare const unitScaleRatio: (declared: CalculatorUnit, actual: Calculat
  * (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;
+export declare const deriveResultUnit: (fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "expression" | "variableToFieldId" | "variableColumnIds" | "variableUnits" | "resultUnit">) => CalculatorUnit | null;
+/** The scope unit for every variable of a base-anchored equation. */
+export declare const deriveVariableUnits: (base: EquationBase, fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "variableToFieldId" | "variableColumnIds">) => Record<string, CalculatorUnit>;
+export type DerivedResultUnit = 
+/** The raw value carries this unit and must be converted back through it. */
+{
+    kind: 'unit';
+    unit: CalculatorUnit;
+}
+/**
+ * Inference succeeded and the raw value needs NO conversion: dimensionless,
+ * or an angle (degrees are already canonical).
+ */
+ | {
+    kind: 'none';
+}
+/**
+ * Inference declined — an unmodelled function, a non-integer power, a
+ * dimension this vocabulary can't name. The base says nothing useful here,
+ * so callers fall back to whatever unit the equation already carried. This
+ * is the escape hatch the authoring UI's manual result-unit picker fills.
+ */
+ | {
+    kind: 'unknown';
+};
+/** The unit a base-anchored expression's raw value carries. */
+export declare const deriveResultUnitForBase: (base: EquationBase, fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "expression" | "variableToFieldId" | "variableColumnIds">) => DerivedResultUnit;
+/** Where a migrated equation's base came from — reported by the migration. */
+export type EquationBaseSource = 
+/** A bound conversion column's declared unit. */
+'conversion-column'
+/** An existing authored `variableUnits` entry. */
+ | 'variable-unit'
+/** A bound measurement field's display unit. */
+ | 'field-default'
+/** Nothing length-valued to anchor to; the base is inert. */
+ | 'fallback'
+/** A variable is in a unit family no base can express — see `blockedBy`. */
+ | 'unanchorable';
+export interface DerivedEquationBase {
+    /** Null when the equation cannot be anchored without changing its meaning. */
+    base: EquationBase | null;
+    source: EquationBaseSource;
+    /**
+     * Distinct bases seen at the winning tier. More than one means the source
+     * disagreed with itself and `base` is the most common of them — the case a
+     * migration should surface rather than apply silently.
+     */
+    candidates: EquationBase[];
+    /**
+     * Units that blocked anchoring: cubic yards, liters, gallons — real units a
+     * field may hold, but outside the five families a base can name.
+     */
+    blockedBy?: CalculatorUnit[];
+}
+/** Inert default when an equation has no length-valued binding at all. */
+export declare const DEFAULT_EQUATION_BASE: EquationBase;
+/**
+ * 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 declare const deriveEquationBase: (fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "variableToFieldId" | "variableColumnIds" | "variableUnits">) => DerivedEquationBase;
 /**
- * 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.
+ * 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 declare const reconcileEquationUnits: (fields: readonly CalculatorField[], equations: readonly CalculatorEquation[]) => {
     equations: CalculatorEquation[];