# UnifiedSpread dev-21.0.0 FormulaEngineFoundation

This milestone separates formula evaluation from `NativeGridModel` into `NativeGridFormulaEngine`.

## Scope

- FormulaEngine module separation under `scripts/engines/nativegrid/`.
- Safe evaluation path for arithmetic expressions after reference substitution.
- Dependency graph generation for formula cells.
- Cross-sheet references such as `Sheet2!A1` and `'Sales 2026'!A1:B5`.
- Workbook-level named range foundation.
- Extended function registry.

## Added function groups

- Aggregates: `SUM`, `AVERAGE`, `AVG`, `MIN`, `MAX`, `COUNT`, `COUNTA`, `PRODUCT`.
- Math: `ABS`, `SQRT`, `INT`, `ROUND`.
- Logic: `IF`, `AND`, `OR`, `NOT`.
- Text: `CONCAT`, `CONCATENATE`, `LEN`, `LEFT`, `RIGHT`, `MID`, `TRIM`, `UPPER`, `LOWER`.
- Date: `DATE`, `YEAR`, `MONTH`, `DAY`, `TODAY`, `NOW`.
- Lookup foundation: `INDEX`, `MATCH`, `VLOOKUP`.

## Design notes

Formula results are calculated on demand and are not written back into `cell.v` by default. This preserves formula source and avoids losing calculation intent during `.uspdx` save, XLSX export and undo/redo.

The dependency graph currently supports diagnostics and regression tests. It records formula-cell to referenced-cell edges and will become the basis for incremental recalculation later.

Named ranges are persisted in workbook-level `config.namedRanges` and saved in `.uspdx` via `workbook.json` and `shared/names.json`.

## Known limitations

This is not yet a complete Excel-compatible formula engine. Array formulas, structured table references, volatile recalculation scheduling, full text/date formatting functions and advanced lookup modes remain future work.