@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/cjs/modules/formula/integration/calculate-formulas-impl.js

@@ -0,0 +1,619 @@
+"use strict";
+/**
+ * Formula Calculation Implementation
+ *
+ * The pipeline that implements the snapshot → compile → evaluate →
+ * materialize → apply architecture.
+ *
+ * ## Pipeline Steps
+ *
+ * 1. **Snapshot** — `buildWorkbookSnapshot()` creates an immutable snapshot
+ *    of the entire workbook.
+ * 2. **Normalize** — `collectFormulaInstances()` extracts all formula cells
+ *    into uniform `FormulaInstance` objects.
+ * 3. **Parse** — Each formula's source text is tokenized and parsed into an AST.
+ * 4. **Compile** — The binder transforms each AST into a `BoundExpr` tree,
+ *    resolving names, structured references, and sheet references.
+ * 5. **Dependency Analysis** — Static dependencies are extracted from bound
+ *    expressions and a topological evaluation order is computed.
+ * 6. **Evaluate** — Formulas are evaluated in dependency order using the
+ *    evaluator which operates on `BoundExpr` and produces `RuntimeValue`.
+ * 7. **Materialize** — Evaluation results are converted into a `WritebackPlan`.
+ * 8. **Apply** — The plan is applied to the live workbook.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateFormulasImpl = calculateFormulasImpl;
+const address_utils_1 = require("../compile/address-utils");
+const binder_1 = require("../compile/binder");
+const compiled_formula_1 = require("../compile/compiled-formula");
+const dependency_analysis_1 = require("../compile/dependency-analysis");
+const _date_context_1 = require("../functions/_date-context");
+const build_writeback_plan_1 = require("../materialize/build-writeback-plan");
+const spill_engine_1 = require("../materialize/spill-engine");
+const evaluator_1 = require("../runtime/evaluator");
+const values_1 = require("../runtime/values");
+const parser_1 = require("../syntax/parser");
+const tokenizer_1 = require("../syntax/tokenizer");
+const apply_writeback_plan_1 = require("./apply-writeback-plan");
+const formula_instance_1 = require("./formula-instance");
+const workbook_adapter_1 = require("./workbook-adapter");
+const workbook_snapshot_1 = require("./workbook-snapshot");
+// ============================================================================
+// Persistent Caches (keyed by workbook — survive across invocations)
+// ============================================================================
+/**
+ * Persistent AST cache: formula text → parsed AstNode.
+ * Since AST is a pure function of formula text, this is safe to cache
+ * across calculation cycles. Keyed by workbook to allow GC.
+ *
+ * The inner `Map` is bounded by `AST_CACHE_MAX_ENTRIES` using simple LRU
+ * eviction (least-recently-used key removed when full). This prevents a
+ * long-lived workbook that churns through unique formula texts — e.g.
+ * templated generation that embeds timestamps — from growing the cache
+ * without bound. See `parseFormulaText` for the hit-path bookkeeping.
+ */
+const AST_CACHE_MAX_ENTRIES = 10000;
+const persistentAstCache = new WeakMap();
+function getPersistentAstCache(workbook) {
+    let cache = persistentAstCache.get(workbook);
+    if (!cache) {
+        cache = new Map();
+        persistentAstCache.set(workbook, cache);
+    }
+    return cache;
+}
+// ============================================================================
+// Main: Formula Calculation Implementation
+// ============================================================================
+/**
+ * Recalculate all formula cells using the new pipeline.
+ *
+ * This implements the full snapshot → compile → evaluate → materialize → apply
+ * architecture. The workbook is mutated only at the final apply step.
+ */
+function calculateFormulasImpl(workbook) {
+    // ── Step 1: Snapshot ──
+    const snapshot = (0, workbook_adapter_1.buildWorkbookSnapshot)(workbook);
+    // Propagate the workbook-wide `date1904` mode to the module-local date
+    // context used by date/time/financial/text formula functions. Those
+    // functions have a context-free `NativeFn` signature and cannot receive
+    // the flag through an argument, so we thread it via a setter instead.
+    // See functions/_date-context.ts for the threading rationale and the
+    // concurrency caveat.
+    (0, _date_context_1.setDate1904)(snapshot.properties.date1904 ?? false);
+    // ── Step 2: Normalize ──
+    const instances = (0, formula_instance_1.collectFormulaInstances)(snapshot);
+    if (instances.length === 0) {
+        // Clean up stale spills even when there are no formulas
+        cleanupStaleSpillsIfNeeded(workbook, snapshot);
+        return;
+    }
+    // ── Step 3: Parse ──
+    // Use persistent AST cache — formula text → AST is a pure function,
+    // so parsed ASTs can be safely reused across calculation cycles.
+    const astCache = getPersistentAstCache(workbook);
+    for (const inst of instances) {
+        parseFormulaText(inst.sourceText, astCache);
+    }
+    // ── Step 4: Compile (Bind) ──
+    const compiledMap = new Map();
+    const results = new Map();
+    for (const inst of instances) {
+        const compiled = compileFormula(inst, astCache, snapshot);
+        const key = (0, workbook_snapshot_1.formulaCellKey)(inst.sheetName, inst.row, inst.col);
+        if ("reason" in compiled) {
+            // Parse or bind failure — produce an explicit error result.
+            // #CALC! for engine-level failures, #NAME? for parse errors that
+            // may indicate an unsupported construct.
+            results.set(key, compiled.reason === "parse" ? values_1.ERRORS.NAME : values_1.ERRORS.CALC);
+        }
+        else {
+            compiledMap.set(key, compiled);
+        }
+    }
+    // ── Step 5: Dependency Analysis + Topological Sort ──
+    // Build a producer map so that formulas depending on cells that are:
+    //   (a) CSE target range slaves, or
+    //   (b) previous-cycle spill ghost cells
+    // correctly get ordered after their producing formula.
+    const producerMap = new Map();
+    // CSE: distribute targetRef across all slave cells → master key
+    for (const [masterKey, cf] of compiledMap) {
+        const inst = cf.instance;
+        if (inst.kind === "cse" && inst.targetRef) {
+            const rng = (0, address_utils_1.parseRefRange)(inst.targetRef);
+            if (rng) {
+                for (let r = rng.top; r <= rng.bottom; r++) {
+                    for (let c = rng.left; c <= rng.right; c++) {
+                        const slaveKey = (0, workbook_snapshot_1.formulaCellKey)(inst.sheetName, r, c);
+                        if (slaveKey !== masterKey) {
+                            producerMap.set(slaveKey, masterKey);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Dynamic array spill: use previous-cycle spill regions as static hint
+    // for dependency ordering. The actual spill may differ this cycle — if the
+    // master formula is no longer a dynamic-array producer, skip it so stale
+    // ghost cells don't introduce false edges.
+    const persistentSpills = (0, spill_engine_1.getPersistentSpillMap)(workbook);
+    for (const [, region] of persistentSpills) {
+        const ws = snapshot.worksheetsById.get(region.worksheetId);
+        if (!ws) {
+            continue;
+        }
+        const masterKey = (0, workbook_snapshot_1.formulaCellKey)(ws.name, region.sourceRow, region.sourceCol);
+        const masterCf = compiledMap.get(masterKey);
+        if (!masterCf) {
+            continue; // source formula no longer exists
+        }
+        // Only remap if the master is still a dynamic-array formula this cycle
+        const isStillDynamic = masterCf.instance.isDynamicArray || masterCf.isDynamicArrayFunction;
+        if (!isStillDynamic) {
+            continue;
+        }
+        for (let r = 0; r < region.rows; r++) {
+            for (let c = 0; c < region.cols; c++) {
+                if (r === 0 && c === 0) {
+                    continue; // skip source
+                }
+                const ghostKey = (0, workbook_snapshot_1.formulaCellKey)(ws.name, region.sourceRow + r, region.sourceCol + c);
+                if (!producerMap.has(ghostKey)) {
+                    producerMap.set(ghostKey, masterKey);
+                }
+            }
+        }
+    }
+    // Build the dependency graph with producer remapping.
+    let graph = (0, dependency_analysis_1.buildDependencyGraphFromDeps)(compiledMap, producerMap);
+    let evalOrder = (0, dependency_analysis_1.topologicalSort)(graph);
+    // ── Step 6: Evaluate ──
+    const session = new evaluator_1.EvalSession();
+    const ctx = {
+        snapshot,
+        compiledFormulas: compiledMap,
+        currentSheet: snapshot.worksheets[0]?.name ?? ""
+    };
+    // Evaluate in topological order
+    evaluateInOrder(evalOrder, compiledMap, results, ctx, session);
+    // ── Step 6b: Merge dynamic dependencies and re-evaluate if needed ──
+    // After the first pass, formulas with INDIRECT/OFFSET have recorded their
+    // actual runtime cell accesses in session.dynamicDeps. Merge these edges
+    // into the graph and re-evaluate any formulas whose dependencies changed.
+    if (session.dynamicDeps.size > 0) {
+        const mergeResult = (0, dependency_analysis_1.mergeDynamicDeps)(graph, session.dynamicDeps);
+        if (mergeResult.changed) {
+            const prevCircularKeys = graph.circularKeys;
+            graph = mergeResult.graph;
+            evalOrder = (0, dependency_analysis_1.topologicalSort)(graph);
+            // Collect formulas that gained new deps AND their transitive dependents.
+            // Without clearing dependents, downstream cells could see stale values.
+            const toClear = new Set();
+            const queue = [];
+            for (const [formulaKey] of session.dynamicDeps) {
+                if (!toClear.has(formulaKey)) {
+                    toClear.add(formulaKey);
+                    queue.push(formulaKey);
+                }
+            }
+            // If the merge introduced new circular refs, include all new members too
+            for (const key of graph.circularKeys) {
+                if (!prevCircularKeys.has(key) && !toClear.has(key)) {
+                    toClear.add(key);
+                    queue.push(key);
+                }
+            }
+            // BFS through reverse edges to find all transitive dependents
+            let head = 0;
+            while (head < queue.length) {
+                const key = queue[head++];
+                const deps = graph.dependedBy.get(key);
+                if (deps) {
+                    for (const depKey of deps) {
+                        if (!toClear.has(depKey)) {
+                            toClear.add(depKey);
+                            queue.push(depKey);
+                        }
+                    }
+                }
+            }
+            // Clear all affected formulas
+            for (const key of toClear) {
+                session.resultCache.delete(key);
+                results.delete(key);
+            }
+            // Formula-based name results may depend on cell values that just changed
+            session.nameCache.clear();
+            // Re-evaluate the full order (evaluateInOrder skips already-computed cells)
+            evaluateInOrder(evalOrder, compiledMap, results, ctx, session);
+        }
+    }
+    // ── Iterative Calculation for Circular References ──
+    const iterateEnabled = snapshot.calcProperties.iterate === true;
+    if (iterateEnabled && graph.circularKeys.size > 0) {
+        runIterativeCalc(evalOrder, graph, compiledMap, results, ctx, session, snapshot);
+        reevaluateDownstreamOfCircular(evalOrder, graph, compiledMap, results, ctx, session);
+    }
+    // ── Step 7: Materialize (Build Writeback Plan) ──
+    const previousSpills = (0, spill_engine_1.getPersistentSpillMap)(workbook);
+    const previousGhosts = (0, spill_engine_1.getGhostSnapshots)(workbook);
+    const plan = (0, build_writeback_plan_1.buildWritebackPlan)(snapshot, [...compiledMap.values()], results, previousSpills, previousGhosts);
+    // ── Step 8: Apply ──
+    (0, apply_writeback_plan_1.applyWritebackPlan)(workbook, plan);
+}
+// ============================================================================
+// Helper: Evaluate Formulas in Order
+// ============================================================================
+/**
+ * Evaluate compiled formulas in the given topological order.
+ *
+ * For each formula in `evalOrder`:
+ * - If already in `results` (from a previous pass or compile failure), skip.
+ * - Volatile formulas always re-evaluate (bypass scalar cache).
+ * - CSE / dynamic array formulas use `evaluateFormulaRaw`.
+ * - Normal scalar formulas use `evaluateFormula` with cache.
+ */
+function evaluateInOrder(evalOrder, compiledMap, results, ctx, session) {
+    for (const key of evalOrder) {
+        // Skip if already computed (e.g. compile failure → #CALC!, or previous pass)
+        if (results.has(key)) {
+            continue;
+        }
+        const compiled = compiledMap.get(key);
+        if (!compiled) {
+            continue;
+        }
+        const inst = compiled.instance;
+        const isCSE = inst.kind === "cse" && inst.targetRef;
+        const isDynamic = inst.isDynamicArray || compiled.isDynamicArrayFunction;
+        // Volatile formulas always re-evaluate — bypass cache
+        if (compiled.isVolatile) {
+            session.resultCache.delete(key);
+        }
+        if (isCSE || isDynamic) {
+            try {
+                const raw = (0, evaluator_1.evaluateFormulaRaw)(compiled, ctx, session);
+                results.set(key, raw);
+                if (isCSE && inst.targetRef) {
+                    populateCSECache(inst, raw, session);
+                }
+            }
+            catch {
+                results.set(key, values_1.ERRORS.CALC);
+            }
+        }
+        else {
+            if (!compiled.isVolatile) {
+                const cachedResult = session.resultCache.get(key);
+                if (cachedResult !== undefined) {
+                    results.set(key, cachedResult.scalar);
+                    continue;
+                }
+            }
+            try {
+                const scalar = (0, evaluator_1.evaluateFormula)(compiled, ctx, session);
+                results.set(key, scalar);
+            }
+            catch {
+                results.set(key, values_1.ERRORS.CALC);
+            }
+        }
+    }
+}
+// ============================================================================
+// Helper: Parse Formula Text
+// ============================================================================
+// Sentinel cached in the AST map to record a failed parse. Using a distinct
+// object means callers that do an explicit identity check against this value
+// can short-circuit before any truthy branch; it is never exposed outside the
+// cache so cannot be mistaken for a real AST by downstream consumers.
+const PARSE_FAILED_SENTINEL = {};
+/**
+ * Touch a cache entry to move it to the MRU (most-recently-used) position.
+ * Relies on `Map`'s guaranteed insertion-order iteration: delete + re-set
+ * pushes the entry to the end of the iteration order without changing its
+ * value identity. Only called on cache hits.
+ */
+function touchAstCacheEntry(astCache, formula, ast) {
+    astCache.delete(formula);
+    astCache.set(formula, ast);
+}
+/**
+ * Insert a new entry into the AST cache, evicting the least-recently-used
+ * entry if the cache is at capacity. The LRU entry is the first key returned
+ * by `Map.keys()` iteration, which corresponds to the oldest insertion/touch.
+ */
+function insertAstCacheEntry(astCache, formula, ast) {
+    if (astCache.size >= AST_CACHE_MAX_ENTRIES) {
+        // Evict one entry before adding the new one. `Map.keys().next().value`
+        // is the least-recently-inserted (or -touched) key — O(1) access.
+        const oldestKey = astCache.keys().next().value;
+        if (oldestKey !== undefined) {
+            astCache.delete(oldestKey);
+        }
+    }
+    astCache.set(formula, ast);
+}
+function parseFormulaText(formula, astCache) {
+    const cached = astCache.get(formula);
+    if (cached === PARSE_FAILED_SENTINEL) {
+        // Touch so that a repeatedly-evaluated failing formula doesn't get
+        // evicted and re-parsed (and re-failed) every cycle.
+        touchAstCacheEntry(astCache, formula, PARSE_FAILED_SENTINEL);
+        return null;
+    }
+    if (cached) {
+        touchAstCacheEntry(astCache, formula, cached);
+        return cached;
+    }
+    try {
+        const tokens = (0, tokenizer_1.tokenize)(formula);
+        const ast = (0, parser_1.parse)(tokens);
+        insertAstCacheEntry(astCache, formula, ast);
+        return ast;
+    }
+    catch {
+        insertAstCacheEntry(astCache, formula, PARSE_FAILED_SENTINEL);
+        return null;
+    }
+}
+function compileFormula(inst, astCache, snapshot) {
+    const ast = astCache.get(inst.sourceText);
+    if (!ast) {
+        return { reason: "parse", formula: inst.sourceText };
+    }
+    const bindCtx = {
+        snapshot,
+        currentSheet: inst.sheetName
+    };
+    try {
+        const bound = (0, binder_1.bind)(ast, bindCtx);
+        // Build a name resolver that parses formula-based defined names
+        // so their deps and dynamic-ref flags propagate to the outer formula.
+        const nameDepCache = new Map();
+        const nameResolver = upperName => {
+            // Include sheet in cache key for scope-aware resolution
+            const cacheKey = `${upperName}\0${inst.sheetName}`;
+            if (nameDepCache.has(cacheKey)) {
+                return nameDepCache.get(cacheKey);
+            }
+            // Prevent infinite recursion
+            nameDepCache.set(cacheKey, undefined);
+            // Use scope-aware resolution (sheet-local → workbook-global)
+            const dn = (0, workbook_snapshot_1.resolveDefinedName)(snapshot.definedNames, upperName, inst.sheetName);
+            if (!dn || dn.ranges.length !== 1) {
+                return undefined;
+            }
+            const rangeStr = dn.ranges[0];
+            // Only process formula-based names (not cell/range refs)
+            if ((0, address_utils_1.parseRefRange)(rangeStr)) {
+                return undefined;
+            }
+            try {
+                const nameTokens = (0, tokenizer_1.tokenize)(rangeStr);
+                const nameAst = (0, parser_1.parse)(nameTokens);
+                const nameBound = (0, binder_1.bind)(nameAst, { snapshot, currentSheet: inst.sheetName });
+                const nameDeps = (0, compiled_formula_1.extractStaticDeps)(nameBound, snapshot, nameResolver);
+                const nameAnalysis = (0, compiled_formula_1.analyzeExpr)(nameBound, nameResolver);
+                const result = {
+                    deps: nameDeps,
+                    hasDynamicRefs: nameAnalysis.hasDynamicRefs,
+                    // Propagate volatility so a defined-name body containing NOW()/
+                    // RAND() correctly invalidates the outer formula's session
+                    // cache on every calculation pass.
+                    isVolatile: nameAnalysis.isVolatile
+                };
+                nameDepCache.set(cacheKey, result);
+                return result;
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const staticDeps = (0, compiled_formula_1.extractStaticDeps)(bound, snapshot, nameResolver);
+        const analysis = (0, compiled_formula_1.analyzeExpr)(bound, nameResolver);
+        return {
+            instance: inst,
+            bound,
+            staticDeps,
+            isVolatile: analysis.isVolatile,
+            hasDynamicRefs: analysis.hasDynamicRefs,
+            containsLambda: analysis.containsLambda,
+            isDynamicArrayFunction: (0, compiled_formula_1.detectDynamicArrayFunction)(ast, bound),
+            isSubtotalOutput: (0, compiled_formula_1.detectSubtotalOutput)(ast, bound)
+        };
+    }
+    catch {
+        return { reason: "bind", formula: inst.sourceText, sheet: inst.sheetName };
+    }
+}
+// ============================================================================
+// Helper: Cleanup Stale Spills
+// ============================================================================
+function cleanupStaleSpillsIfNeeded(workbook, snapshot) {
+    const previousSpills = (0, spill_engine_1.getPersistentSpillMap)(workbook);
+    if (previousSpills.size === 0) {
+        return;
+    }
+    // No formula cells → all spills are stale
+    const plan = (0, build_writeback_plan_1.buildWritebackPlan)(snapshot, [], new Map(), previousSpills, (0, spill_engine_1.getGhostSnapshots)(workbook));
+    (0, apply_writeback_plan_1.applyWritebackPlan)(workbook, plan);
+}
+// ============================================================================
+// Helper: Populate CSE Session Cache
+// ============================================================================
+/**
+ * For CSE array formulas, immediately populate the session cache for all
+ * cells in the target range. This ensures that when other formulas reference
+ * cells within a CSE range, they see the correct distributed values instead
+ * of re-evaluating independently.
+ */
+function populateCSECache(inst, result, session) {
+    const ref = inst.targetRef;
+    if (!ref) {
+        return;
+    }
+    const range = (0, address_utils_1.parseRefRange)(ref);
+    if (!range) {
+        return;
+    }
+    const { top, left, bottom, right } = range;
+    const numRows = bottom - top + 1;
+    const numCols = right - left + 1;
+    if (result.kind === 5 /* RVKind.Array */) {
+        for (let r = 0; r < numRows; r++) {
+            for (let c = 0; c < numCols; c++) {
+                const cellKey = (0, workbook_snapshot_1.formulaCellKey)(inst.sheetName, top + r, left + c);
+                const val = result.rows[r]?.[c];
+                const sv = val ?? values_1.BLANK;
+                session.resultCache.set(cellKey, { scalar: sv, raw: sv });
+            }
+        }
+    }
+    else {
+        // Scalar — fill entire range
+        const scalar = result.kind === 4 /* RVKind.Error */ ||
+            result.kind === 1 /* RVKind.Number */ ||
+            result.kind === 2 /* RVKind.String */ ||
+            result.kind === 3 /* RVKind.Boolean */
+            ? result
+            : values_1.BLANK;
+        for (let r = 0; r < numRows; r++) {
+            for (let c = 0; c < numCols; c++) {
+                const cellKey = (0, workbook_snapshot_1.formulaCellKey)(inst.sheetName, top + r, left + c);
+                session.resultCache.set(cellKey, { scalar, raw: scalar });
+            }
+        }
+    }
+}
+// ============================================================================
+// Iterative calculation (for circular references)
+// ============================================================================
+/**
+ * Drive the iterative-calculation loop for the cells that participate in
+ * cycles. Pre-computes the transitive downstream set once, then on each
+ * iteration:
+ *   1. invalidates the cached result of circular cells and their descendants;
+ *   2. seeds `circularFallback` from the previous iteration's numbers;
+ *   3. re-evaluates each circular cell and tracks the maximum absolute change.
+ *
+ * Exits early when all cells converge within `iterateDelta`, or after
+ * `iterateCount` iterations. The `circularFallback` map is cleared on exit
+ * so subsequent (non-iterative) evaluation paths revert to the zero-seed
+ * fallback behaviour.
+ */
+function runIterativeCalc(evalOrder, graph, compiledMap, results, ctx, session, snapshot) {
+    const maxIter = snapshot.calcProperties.iterateCount ?? 100;
+    const delta = snapshot.calcProperties.iterateDelta ?? 0.001;
+    const circularKeys = [];
+    for (const key of evalOrder) {
+        if (graph.circularKeys.has(key)) {
+            circularKeys.push(key);
+        }
+    }
+    // Transitive downstream of circularKeys — cells upstream of every cycle
+    // are stable across iterations, so their cached values remain valid.
+    const circularAndDownstream = new Set(graph.circularKeys);
+    const downstreamQueue = [...graph.circularKeys];
+    let downstreamHead = 0;
+    while (downstreamHead < downstreamQueue.length) {
+        const key = downstreamQueue[downstreamHead++];
+        const deps = graph.dependedBy.get(key);
+        if (!deps) {
+            continue;
+        }
+        for (const depKey of deps) {
+            if (!circularAndDownstream.has(depKey)) {
+                circularAndDownstream.add(depKey);
+                downstreamQueue.push(depKey);
+            }
+        }
+    }
+    for (let iter = 0; iter < maxIter; iter++) {
+        let maxChange = 0;
+        // Clear only circular cells and their transitive downstream.
+        for (const key of circularAndDownstream) {
+            session.resultCache.delete(key);
+        }
+        // Defined-name cache: cleared wholesale because formula-based names may
+        // indirectly reference circular cells, and tracking which names touch
+        // which cells would complicate the engine substantially.
+        session.nameCache.clear();
+        // Seed fallback from previous results
+        for (const key of circularKeys) {
+            const compiled = compiledMap.get(key);
+            if (!compiled) {
+                continue;
+            }
+            const prev = results.get(key);
+            if (prev !== undefined && prev.kind !== 4 /* RVKind.Error */) {
+                session.circularFallback.set(key, prev);
+            }
+            else {
+                session.circularFallback.set(key, (0, values_1.rvNumber)(0));
+            }
+        }
+        for (const key of circularKeys) {
+            const compiled = compiledMap.get(key);
+            if (!compiled) {
+                continue;
+            }
+            try {
+                const oldResult = results.get(key);
+                const newResult = (0, evaluator_1.evaluateFormula)(compiled, ctx, session);
+                results.set(key, newResult);
+                session.circularFallback.set(key, newResult);
+                if (oldResult && oldResult.kind === 1 /* RVKind.Number */ && newResult.kind === 1 /* RVKind.Number */) {
+                    maxChange = Math.max(maxChange, Math.abs(newResult.value - oldResult.value));
+                }
+            }
+            catch {
+                // Iterative evaluation threw — set error and continue convergence.
+                results.set(key, values_1.ERRORS.CALC);
+            }
+        }
+        if (maxChange <= delta) {
+            break;
+        }
+    }
+    session.circularFallback.clear();
+}
+/**
+ * After iterative calculation has converged, cells that sit on the non-
+ * circular side but depend transitively on a circular cell still hold stale
+ * values from the first pass (which used the fallback zero-seed). Find them
+ * and re-evaluate, preserving topological order.
+ */
+function reevaluateDownstreamOfCircular(evalOrder, graph, compiledMap, results, ctx, session) {
+    const affected = new Set();
+    const queue = [...graph.circularKeys];
+    let head = 0;
+    while (head < queue.length) {
+        const key = queue[head++];
+        const deps = graph.dependedBy.get(key);
+        if (!deps) {
+            continue;
+        }
+        for (const depKey of deps) {
+            if (!graph.circularKeys.has(depKey) && !affected.has(depKey)) {
+                affected.add(depKey);
+                queue.push(depKey);
+            }
+        }
+    }
+    if (affected.size === 0) {
+        return;
+    }
+    for (const key of affected) {
+        session.resultCache.delete(key);
+        results.delete(key);
+    }
+    session.nameCache.clear();
+    // Only re-evaluate the affected subset; filtering preserves the
+    // topological ordering within that subset while skipping the (already
+    // computed) non-affected cells entirely.
+    const filteredOrder = evalOrder.filter(k => affected.has(k));
+    evaluateInOrder(filteredOrder, compiledMap, results, ctx, session);
+}

package/dist/cjs/modules/formula/integration/calculate-formulas.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Formula Calculation Engine
+ *
+ * Provides `calculateFormulas()` as the primary function-style entry
+ * point. The same work runs when a host calls
+ * `Workbook.calculateFormulas()` — both paths dispatch through the
+ * engine registered via `installFormulaEngine()`.
+ *
+ * ## Architecture
+ *
+ * 1. **Snapshot** — immutable capture of all workbook state
+ * 2. **Normalize** — uniform FormulaInstance objects
+ * 3. **Parse** — tokenize → AST
+ * 4. **Compile** — bind AST → BoundExpr (resolve names, structured refs, sheets)
+ * 5. **Dependency Analysis** — topological sort
+ * 6. **Evaluate** — execute BoundExpr with RuntimeValue system
+ * 7. **Materialize** — build declarative WritebackPlan
+ * 8. **Apply** — write plan to live workbook
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateFormulas = calculateFormulas;
+const calculate_formulas_impl_1 = require("./calculate-formulas-impl");
+/**
+ * Recalculate all formula cells in a workbook.
+ *
+ * Evaluates every formula cell using the built-in calculation engine
+ * and updates each cell's `result` value. Formulas are evaluated lazily
+ * with recursive dependency resolution, memoization, and circular
+ * reference detection.
+ *
+ * All evaluation state is scoped to this invocation — concurrent calls
+ * for different workbooks are safe.
+ *
+ * **Supported formula features:**
+ * - Cell references: `A1`, `$B$2`, `Sheet1!A1`, `'Sheet Name'!A1:B10`
+ * - Operators: `+ - * / ^`, `& (concat)`, `= <> < > <= >=`, `%`
+ * - 433 built-in functions across math, text, logical, date, lookup,
+ *   statistical, financial, dynamic-array, database and engineering
+ *   categories.
+ * - Shared formulas, array constants, nested expressions
+ * - Dynamic array spill: FILTER, SORT, UNIQUE, SORTBY results are
+ *   written to adjacent cells. #SPILL! error if target cells are occupied.
+ * - CSE array formulas: `{=formula}` with a ref range distribute results
+ *   across the designated range.
+ * - Array arithmetic broadcasting: `{1,2,3} + {4;5;6}` produces a 3x3 matrix.
+ * - Implicit intersection: range references in scalar context pick the
+ *   value from the formula cell's row or column.
+ *
+ * **Unsupported formula behavior:**
+ * - If a formula uses a function the engine does not implement, the engine
+ *   returns `#NAME?`. However, if the cell already has a cached result
+ *   (e.g., pre-computed by Excel when the XLSX was saved), that cached
+ *   result is **preserved** — the engine will not overwrite usable data.
+ * - If no cached result exists, the cell's result becomes `#NAME?`.
+ *
+ * **Volatile functions:**
+ * - `RAND`, `RANDBETWEEN`, `NOW`, `TODAY` are re-evaluated on every call.
+ *   This is intentional — these functions are expected to produce fresh values.
+ *
+ * **Side effects:**
+ * - This function **mutates** the workbook by updating formula cells' `result`
+ *   property in-place. For dynamic array formulas, adjacent cells are also
+ *   written with spill results. If you need the original cached results
+ *   preserved, clone the workbook before calling this function.
+ *
+ * @param workbook - The workbook whose formulas should be recalculated
+ */
+function calculateFormulas(workbook) {
+    (0, calculate_formulas_impl_1.calculateFormulasImpl)(workbook);
+}