@reekon-tools/boldr-utils 1.6.39 → 1.7.1

package/dist/calculator/solve.js

@@ -0,0 +1,227 @@
+import { ColumnType } from '../types/firestore.js';
+import { fieldDimension, findEquation, findField } from './schema.js';
+import { evaluateEquation, numericFieldValue } from './evaluate.js';
+// Generous: the alternating secant/bisection worst case over the widest
+// default bracket (volume, [0, 1e30]) needs ~170 halvings-equivalent.
+const DEFAULT_MAX_ITER = 256;
+const DEFAULT_SCAN_SAMPLES = 128;
+// Generous per-dimension fallback brackets so common monotonic equations
+// solve with zero authoring effort; author hints exist to isolate a specific
+// root, not as a prerequisite. Lengths/areas/volumes are non-negative (which
+// also picks the physical branch of even-power equations).
+const DEFAULT_BRACKETS = {
+    length: [0, 1e10], // 10 km in µm
+    area: [0, 1e20],
+    volume: [0, 1e30],
+    angle: [-360, 360],
+    none: [-1e12, 1e12],
+};
+// Convergence: bracket width below the dimension's absolute floor or a
+// relative epsilon of the estimate, whichever is larger.
+const ABS_TOL = {
+    length: 1e-3, // 1 nm — far below any display tolerance
+    area: 1e-3,
+    volume: 1e-3,
+    angle: 1e-9,
+    none: 1e-12,
+};
+const REL_TOL = 1e-12;
+/**
+ * Numerically solve a solvable field from its governing equation, given the
+ * equation's output value (and every other referenced value) in `values`.
+ */
+export const solveForField = ({ definition, fieldId, values, options, }) => {
+    const field = findField(definition, fieldId);
+    if (!field)
+        return { ok: false, failure: { kind: 'unknown-field' } };
+    if (field.kind !== ColumnType.Number &&
+        field.kind !== ColumnType.Measurement &&
+        field.kind !== ColumnType.Angle) {
+        return { ok: false, failure: { kind: 'not-solvable' } };
+    }
+    const hints = field.solve;
+    if (!hints?.solvable) {
+        return { ok: false, failure: { kind: 'not-solvable' } };
+    }
+    const equation = hints.governingEquationId
+        ? findEquation(definition, hints.governingEquationId)
+        : undefined;
+    if (!equation) {
+        return { ok: false, failure: { kind: 'no-governing-equation' } };
+    }
+    const targetField = findField(definition, equation.targetFieldId);
+    const targetValue = targetField
+        ? numericFieldValue(targetField, values[equation.targetFieldId])
+        : null;
+    if (targetValue == null) {
+        return {
+            ok: false,
+            failure: {
+                kind: 'missing-target',
+                targetFieldId: equation.targetFieldId,
+            },
+        };
+    }
+    // g(x) — forward value with the unknown pinned to x, minus the target.
+    // Returns null at points where the expression is undefined (e.g. a
+    // division by zero at x = 0); the search skips such points.
+    let lastError = null;
+    const g = (x) => {
+        const result = evaluateEquation({
+            definition,
+            equation,
+            values: { ...values, [fieldId]: x },
+        });
+        if (result.ok)
+            return result.value - targetValue;
+        if (result.reason === 'missing-inputs') {
+            // Missing something other than the unknown — not point-dependent, bail.
+            throw {
+                solveFailure: {
+                    kind: 'missing-inputs',
+                    missingFieldIds: result.missingFieldIds.filter((id) => id !== fieldId),
+                },
+            };
+        }
+        lastError = result.error;
+        return null;
+    };
+    const dimension = fieldDimension(field);
+    const [defaultLo, defaultHi] = DEFAULT_BRACKETS[dimension];
+    const lo0 = hints.min ?? defaultLo;
+    const hi0 = hints.max ?? defaultHi;
+    if (!Number.isFinite(lo0) || !Number.isFinite(hi0) || lo0 >= hi0) {
+        return { ok: false, failure: { kind: 'invalid-bracket' } };
+    }
+    const residualTol = Math.max(1e-9, Math.abs(targetValue) * 1e-9);
+    const absTol = ABS_TOL[dimension];
+    const converged = (lo, hi) => hi - lo <= Math.max(absTol, REL_TOL * Math.max(Math.abs(lo), Math.abs(hi)));
+    try {
+        // --- Find a sign-change bracket -------------------------------------
+        let lo = lo0;
+        let hi = hi0;
+        let gLo = g(lo);
+        let gHi = g(hi);
+        if (gLo != null && Math.abs(gLo) <= residualTol) {
+            return { ok: true, value: lo };
+        }
+        if (gHi != null && Math.abs(gHi) <= residualTol) {
+            return { ok: true, value: hi };
+        }
+        const straddles = (a, b) => a != null && b != null && Math.sign(a) !== Math.sign(b);
+        if (!straddles(gLo, gHi)) {
+            // Probe interior points (also around the Newton seed, if given) for an
+            // adjacent evaluable pair with opposite signs.
+            const samples = options?.scanSamples ?? DEFAULT_SCAN_SAMPLES;
+            let found = false;
+            let prevX = lo;
+            let prevG = gLo;
+            for (let i = 1; i <= samples; i++) {
+                const x = i === samples ? hi : lo0 + ((hi0 - lo0) * i) / samples;
+                const gx = g(x);
+                if (gx != null && Math.abs(gx) <= residualTol) {
+                    return { ok: true, value: x };
+                }
+                if (straddles(prevG, gx)) {
+                    lo = prevX;
+                    hi = x;
+                    gLo = prevG;
+                    gHi = gx;
+                    found = true;
+                    break;
+                }
+                if (gx != null) {
+                    prevX = x;
+                    prevG = gx;
+                }
+            }
+            if (!found) {
+                return lastError != null && gLo == null && gHi == null
+                    ? { ok: false, failure: { kind: 'eval-error', error: lastError } }
+                    : { ok: false, failure: { kind: 'no-sign-change' } };
+            }
+        }
+        // --- Root refinement: secant (regula falsi) fast-path guarded by ------
+        // bisection, so invertible/monotonic equations converge fast and
+        // anything pathological still halves the bracket every step.
+        const maxIter = options?.maxIter ?? DEFAULT_MAX_ITER;
+        for (let iter = 0; iter < maxIter; iter++) {
+            if (gLo == null || gHi == null)
+                break; // defensive; shouldn't happen
+            let x;
+            const denom = gHi - gLo;
+            if (denom !== 0) {
+                // Secant estimate, clamped to the interior of the bracket.
+                const secant = hi - (gHi * (hi - lo)) / denom;
+                const mid = (lo + hi) / 2;
+                x =
+                    secant > lo && secant < hi
+                        ? // Blend toward bisection to avoid regula-falsi stagnation on
+                            // one stuck endpoint.
+                            iter % 2 === 0
+                                ? secant
+                                : mid
+                        : mid;
+            }
+            else {
+                x = (lo + hi) / 2;
+            }
+            const gx = g(x);
+            if (gx == null) {
+                // Undefined interior point — fall back to plain midpoint stepping
+                // toward the evaluable side.
+                const mid = (lo + hi) / 2;
+                const gMid = x === mid ? gx : g(mid);
+                if (gMid == null) {
+                    return {
+                        ok: false,
+                        failure: {
+                            kind: 'eval-error',
+                            error: lastError ?? 'Expression undefined inside bracket',
+                        },
+                    };
+                }
+                x = mid;
+                if (Math.sign(gMid) === Math.sign(gLo)) {
+                    lo = x;
+                    gLo = gMid;
+                }
+                else {
+                    hi = x;
+                    gHi = gMid;
+                }
+            }
+            else {
+                if (Math.abs(gx) <= residualTol)
+                    return { ok: true, value: x };
+                if (Math.sign(gx) === Math.sign(gLo)) {
+                    lo = x;
+                    gLo = gx;
+                }
+                else {
+                    hi = x;
+                    gHi = gx;
+                }
+            }
+            if (converged(lo, hi)) {
+                return { ok: true, value: (lo + hi) / 2 };
+            }
+        }
+        return { ok: false, failure: { kind: 'non-convergent' } };
+    }
+    catch (err) {
+        if (err && typeof err === 'object' && 'solveFailure' in err) {
+            return {
+                ok: false,
+                failure: err.solveFailure,
+            };
+        }
+        return {
+            ok: false,
+            failure: {
+                kind: 'eval-error',
+                error: err instanceof Error ? err.message : String(err),
+            },
+        };
+    }
+};

package/dist/calculator/units.d.ts

@@ -0,0 +1,50 @@
+import { DecimalTolerance, FractionalTolerance, Units } from '../types/firestore.js';
+export type MeasurementDimension = 'length' | 'area' | 'volume';
+export type FieldDimension = MeasurementDimension | 'angle' | 'none';
+export type AreaUnit = 'sq_mm' | 'sq_cm' | 'sq_m' | 'sq_in' | 'sq_ft' | 'sq_yd';
+export type VolumeUnit = 'cu_mm' | 'cu_cm' | 'cu_m' | 'cu_in' | 'cu_ft' | 'cu_yd' | 'liter' | 'gallon';
+export type AngleUnit = 'deg' | 'rad';
+/** Every unit a calculator field may display in. Length reuses `Units`. */
+export type CalculatorUnit = Units | AreaUnit | VolumeUnit | AngleUnit;
+export interface CalculatorUnitInfo {
+    dimension: FieldDimension;
+    /**
+     * Real math.js unit token used for conversion. The fractional/composite
+     * length units (`in_frac`, `ft_in_*`) are display-only and collapse to
+     * their real unit here (mirrors normalizeUnitForMathJS in evaluateFormula).
+     */
+    mathUnit: string;
+    /** Short display label, e.g. 'ft³'. */
+    label: string;
+}
+export declare const CALCULATOR_UNIT_INFO: Record<CalculatorUnit, CalculatorUnitInfo>;
+/** The math.js token for a dimension's canonical unit. '' for dimensionless. */
+export declare const canonicalMathUnit: (dimension: FieldDimension) => string;
+export declare const unitDimension: (unit: CalculatorUnit) => FieldDimension;
+export declare const unitsForDimension: (dimension: FieldDimension) => CalculatorUnit[];
+/** Short label for a unit ('ft³', 'in', '°'). */
+export declare const calculatorUnitLabel: (unit: CalculatorUnit) => string;
+/** Convert a display-unit numeric value to the dimension's canonical unit. */
+export declare const toCanonical: (value: number, unit: CalculatorUnit) => number;
+/** Convert a canonical value to a display-unit numeric value. */
+export declare const fromCanonical: (value: number, unit: CalculatorUnit) => number;
+/**
+ * Parse user input in a display unit into a canonical value. Accepts plain
+ * numbers, fractions and mixed numbers ("12 1/2"). Length units additionally
+ * accept a trailing unit token (delegated to parseMeasurement). Returns null
+ * on unparseable input.
+ */
+export declare const parseToCanonical: (input: string, unit: CalculatorUnit) => number | null;
+export interface FormatTolerances {
+    fractionalTolerance?: FractionalTolerance;
+    decimalTolerance?: DecimalTolerance;
+}
+/**
+ * Format a canonical value for display in the given unit. Lengths delegate to
+ * convertMicrometers (the one place that renders fractional-inch / feet-inch
+ * strings); other dimensions format decimally per the decimal tolerance.
+ */
+export declare const formatCanonical: (value: number | null | undefined, unit: CalculatorUnit, tolerances?: FormatTolerances) => {
+    value: string;
+    unit: string;
+};

package/dist/calculator/units.js

@@ -0,0 +1,137 @@
+import { create, all } from 'mathjs';
+import { DecimalTolerance, FractionalTolerance, Units, convertUnitsToReadableShort, } from '../types/firestore.js';
+import { convertMicrometers } from '../utils/micrometersToUnit.js';
+import { parseMeasurement } from '../utils/parseMeasurement.js';
+const math = create(all);
+const LENGTH_UNIT_INFO = {
+    [Units.Millimeters]: { dimension: 'length', mathUnit: 'mm', label: 'mm' },
+    [Units.Centimeters]: { dimension: 'length', mathUnit: 'cm', label: 'cm' },
+    [Units.Meters]: { dimension: 'length', mathUnit: 'm', label: 'm' },
+    [Units.Inches]: { dimension: 'length', mathUnit: 'in', label: 'in' },
+    [Units.FractionalInches]: {
+        dimension: 'length',
+        mathUnit: 'in',
+        label: 'in',
+    },
+    [Units.Feet]: { dimension: 'length', mathUnit: 'ft', label: 'ft' },
+    [Units.FeetInchesDecimal]: {
+        dimension: 'length',
+        mathUnit: 'ft',
+        label: 'ft-in',
+    },
+    [Units.FeetInchesFractional]: {
+        dimension: 'length',
+        mathUnit: 'ft',
+        label: 'ft-in',
+    },
+};
+export const CALCULATOR_UNIT_INFO = {
+    ...LENGTH_UNIT_INFO,
+    sq_mm: { dimension: 'area', mathUnit: 'mm^2', label: 'mm²' },
+    sq_cm: { dimension: 'area', mathUnit: 'cm^2', label: 'cm²' },
+    sq_m: { dimension: 'area', mathUnit: 'm^2', label: 'm²' },
+    sq_in: { dimension: 'area', mathUnit: 'in^2', label: 'in²' },
+    sq_ft: { dimension: 'area', mathUnit: 'ft^2', label: 'ft²' },
+    sq_yd: { dimension: 'area', mathUnit: 'yd^2', label: 'yd²' },
+    cu_mm: { dimension: 'volume', mathUnit: 'mm^3', label: 'mm³' },
+    cu_cm: { dimension: 'volume', mathUnit: 'cm^3', label: 'cm³' },
+    cu_m: { dimension: 'volume', mathUnit: 'm^3', label: 'm³' },
+    cu_in: { dimension: 'volume', mathUnit: 'in^3', label: 'in³' },
+    cu_ft: { dimension: 'volume', mathUnit: 'ft^3', label: 'ft³' },
+    cu_yd: { dimension: 'volume', mathUnit: 'yd^3', label: 'yd³' },
+    liter: { dimension: 'volume', mathUnit: 'L', label: 'L' },
+    gallon: { dimension: 'volume', mathUnit: 'gal', label: 'gal' },
+    deg: { dimension: 'angle', mathUnit: 'deg', label: '°' },
+    rad: { dimension: 'angle', mathUnit: 'rad', label: 'rad' },
+};
+/** The math.js token for a dimension's canonical unit. '' for dimensionless. */
+export const canonicalMathUnit = (dimension) => {
+    switch (dimension) {
+        case 'length':
+            return 'um';
+        case 'area':
+            return 'um^2';
+        case 'volume':
+            return 'um^3';
+        case 'angle':
+            return 'deg';
+        case 'none':
+            return '';
+    }
+};
+export const unitDimension = (unit) => CALCULATOR_UNIT_INFO[unit]?.dimension ?? 'none';
+export const unitsForDimension = (dimension) => Object.keys(CALCULATOR_UNIT_INFO).filter((u) => CALCULATOR_UNIT_INFO[u].dimension === dimension);
+/** Short label for a unit ('ft³', 'in', '°'). */
+export const calculatorUnitLabel = (unit) => {
+    const lengthLabel = convertUnitsToReadableShort(unit);
+    return CALCULATOR_UNIT_INFO[unit]?.label ?? lengthLabel ?? String(unit);
+};
+// All units here are pure scale factors relative to their canonical unit
+// (no affine offsets like °F), so conversion is a cached multiply.
+const factorCache = new Map();
+const canonicalFactor = (unit) => {
+    const cached = factorCache.get(unit);
+    if (cached != null)
+        return cached;
+    const info = CALCULATOR_UNIT_INFO[unit];
+    if (!info)
+        throw new Error(`Unknown calculator unit: ${unit}`);
+    const canonical = canonicalMathUnit(info.dimension);
+    const factor = canonical === '' ? 1 : math.unit(1, info.mathUnit).toNumber(canonical);
+    factorCache.set(unit, factor);
+    return factor;
+};
+/** Convert a display-unit numeric value to the dimension's canonical unit. */
+export const toCanonical = (value, unit) => value * canonicalFactor(unit);
+/** Convert a canonical value to a display-unit numeric value. */
+export const fromCanonical = (value, unit) => value / canonicalFactor(unit);
+const decimalPlaces = (tolerance) => 
+// '0.5' -> 1, '0.01' -> 2, ... (the string-length trick used app-wide).
+tolerance.length - 2;
+// "12 1/2" -> "12 + 1/2" (same normalization parseMeasurement applies).
+const normalizeMixedFraction = (input) => input.trim().replace(/(\d+)\s+(\d+)\/(\d+)/g, '$1 + $2/$3');
+/**
+ * Parse user input in a display unit into a canonical value. Accepts plain
+ * numbers, fractions and mixed numbers ("12 1/2"). Length units additionally
+ * accept a trailing unit token (delegated to parseMeasurement). Returns null
+ * on unparseable input.
+ */
+export const parseToCanonical = (input, unit) => {
+    const info = CALCULATOR_UNIT_INFO[unit];
+    if (!info || input.trim() === '')
+        return null;
+    if (info.dimension === 'length') {
+        // parseMeasurement already returns micrometers (canonical).
+        return parseMeasurement(input, info.mathUnit);
+    }
+    try {
+        const result = math.evaluate(normalizeMixedFraction(input));
+        if (typeof result !== 'number' || !Number.isFinite(result))
+            return null;
+        return toCanonical(result, unit);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Format a canonical value for display in the given unit. Lengths delegate to
+ * convertMicrometers (the one place that renders fractional-inch / feet-inch
+ * strings); other dimensions format decimally per the decimal tolerance.
+ */
+export const formatCanonical = (value, unit, tolerances) => {
+    const fractional = tolerances?.fractionalTolerance ?? FractionalTolerance.Sixteenth;
+    const decimal = tolerances?.decimalTolerance ?? DecimalTolerance.Hundredth;
+    const info = CALCULATOR_UNIT_INFO[unit];
+    if (value == null || Number.isNaN(value) || !info) {
+        return { value: 'NaN', unit: info?.label ?? '' };
+    }
+    if (info.dimension === 'length') {
+        return convertMicrometers(value, unit, fractional, decimal);
+    }
+    const display = fromCanonical(value, unit);
+    return {
+        value: display.toFixed(decimalPlaces(decimal)),
+        unit: info.label,
+    };
+};

package/dist/calculator/validate.d.ts

@@ -0,0 +1,192 @@
+import { z } from 'zod';
+import { ColumnType, DecimalTolerance, FractionalTolerance } from '../types/firestore.js';
+export declare const calculatorDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    version: z.ZodNumber;
+    name: z.ZodString;
+    description: z.ZodString;
+    folderId: z.ZodNullable<z.ZodString>;
+    fields: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<ColumnType.Number>;
+        defaultValue: z.ZodOptional<z.ZodNumber>;
+        solve: z.ZodOptional<z.ZodObject<{
+            solvable: z.ZodBoolean;
+            governingEquationId: z.ZodOptional<z.ZodString>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            guess: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<{
+            input: "input";
+            output: "output";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        binding: z.ZodOptional<z.ZodObject<{
+            hotspotId: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ColumnType.Measurement>;
+        unit: z.ZodObject<{
+            dimension: z.ZodEnum<{
+                length: "length";
+                area: "area";
+                volume: "volume";
+            }>;
+            defaultUnit: z.ZodString;
+            allowedUnits: z.ZodArray<z.ZodString>;
+            fractionalTolerance: z.ZodOptional<z.ZodEnum<typeof FractionalTolerance>>;
+            decimalTolerance: z.ZodOptional<z.ZodEnum<typeof DecimalTolerance>>;
+        }, z.core.$strip>;
+        defaultValue: z.ZodOptional<z.ZodNumber>;
+        solve: z.ZodOptional<z.ZodObject<{
+            solvable: z.ZodBoolean;
+            governingEquationId: z.ZodOptional<z.ZodString>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            guess: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<{
+            input: "input";
+            output: "output";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        binding: z.ZodOptional<z.ZodObject<{
+            hotspotId: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ColumnType.Angle>;
+        angleUnit: z.ZodOptional<z.ZodEnum<{
+            deg: "deg";
+            rad: "rad";
+        }>>;
+        defaultValue: z.ZodOptional<z.ZodNumber>;
+        solve: z.ZodOptional<z.ZodObject<{
+            solvable: z.ZodBoolean;
+            governingEquationId: z.ZodOptional<z.ZodString>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            guess: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<{
+            input: "input";
+            output: "output";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        binding: z.ZodOptional<z.ZodObject<{
+            hotspotId: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ColumnType.SingleSelect>;
+        columnData: z.ZodObject<{
+            options: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        defaultValue: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<{
+            input: "input";
+            output: "output";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        binding: z.ZodOptional<z.ZodObject<{
+            hotspotId: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ColumnType.MultiSelect>;
+        columnData: z.ZodObject<{
+            options: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        defaultValue: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<{
+            input: "input";
+            output: "output";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        binding: z.ZodOptional<z.ZodObject<{
+            hotspotId: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ColumnType.ConversionTable>;
+        columnData: z.ZodObject<{
+            conversions: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                value: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        defaultValue: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<{
+            input: "input";
+            output: "output";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        binding: z.ZodOptional<z.ZodObject<{
+            hotspotId: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ColumnType.Instructions>;
+        columnData: z.ZodObject<{
+            text: z.ZodString;
+            textColor: z.ZodString;
+            backgroundColor: z.ZodString;
+        }, z.core.$strip>;
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<{
+            input: "input";
+            output: "output";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        binding: z.ZodOptional<z.ZodObject<{
+            hotspotId: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>], "kind">>;
+    equations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        targetFieldId: z.ZodString;
+        expression: z.ZodString;
+        variableToFieldId: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+    diagramFileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    isPublic: z.ZodBoolean;
+    sharedUserIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sharedOrgIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    createdBy: z.ZodOptional<z.ZodObject<{
+        userId: z.ZodString;
+        firstName: z.ZodOptional<z.ZodString>;
+        lastName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    createdAt: z.ZodOptional<z.ZodUnknown>;
+    updatedAt: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type IssueSeverity = 'error' | 'warning';
+export interface ValidationIssue {
+    code: string;
+    path: string;
+    message: string;
+    severity: IssueSeverity;
+}
+export interface ValidationResult {
+    /** True when there are no error-severity issues (warnings allowed). */
+    ok: boolean;
+    issues: ValidationIssue[];
+}
+/** Free variables of an expression (function names and constants excluded). */
+export declare const expressionSymbols: (expression: string) => {
+    ok: true;
+    symbols: string[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare const validateCalculatorDefinition: (input: unknown) => ValidationResult;