@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/browser/modules/formula/runtime/evaluator.js

@@ -0,0 +1,2291 @@
+/**
+ * Evaluator — Execute BoundExpr using the RuntimeValue system.
+ *
+ * The evaluator operates on BoundExpr (from the compile phase),
+ * WorkbookSnapshot (from the snapshot phase), and RuntimeValue
+ * (the value system).
+ */
+import { parseDefinedNameRange } from "../compile/address-utils.js";
+import { bind } from "../compile/binder.js";
+import { BoundExprKind } from "../compile/bound-ast.js";
+import { resolveStructuredRefRows, buildTableGeometry, resolveStructuredRefColumns } from "../compile/structured-ref-utils.js";
+import { snapshotCellKey, formulaCellKey, resolveDefinedName as resolveDefinedNameFromSnapshot } from "../integration/workbook-snapshot.js";
+import { parse } from "../syntax/parser.js";
+import { stripFunctionPrefix } from "../syntax/token-types.js";
+import { tokenize } from "../syntax/tokenizer.js";
+import { lookupFunction } from "./function-registry.js";
+import { RVKind, BLANK, ERRORS, rvNumber, rvString, rvBoolean, rvError, rvArray, rvRef, rvCellRef, rvLambda, isError, isScalar, isLambda, toNumberRV, toStringRV, toBooleanRV, topLeft, scalarEquals, compareScalarsSameKind, fromSnapshotValue } from "./values.js";
+/**
+ * Per-calculation mutable state.
+ */
+export class EvalSession {
+    constructor() {
+        /** Cells currently on the evaluation call stack (circular-ref detection). */
+        this.evaluating = new Set();
+        /**
+         * Unified formula result cache.
+         * Each entry holds both the scalar form (for dependents) and the raw form
+         * (for materialize). This replaces the previous separate cache/rawCache
+         * pattern with a single, self-documenting structure.
+         */
+        this.resultCache = new Map();
+        /** Cache for runtime name resolution (defined names that need parsing). */
+        this.nameCache = new Map();
+        /** Fallback values for circular references during iterative calculation. */
+        this.circularFallback = new Map();
+        /**
+         * Live spill map: cell key → (masterKey, row-offset, col-offset).
+         *
+         * Populated as soon as a dynamic-array formula is evaluated and yields
+         * an array result. Downstream formulas that read a cell inside the
+         * spill region look the master's cached array up via this map and
+         * return the correct element — even before materialize has written
+         * the ghost cells to the snapshot.
+         *
+         * This is the fix for "first-pass `=SUM(A1:A5)` over a `=SEQUENCE(5)`
+         * spill" — without the live map, `getCellValue("S", 2, 1)` returned
+         * BLANK and SUM only counted the master cell.
+         */
+        this.liveSpills = new Map();
+        /**
+         * Runtime dependency recorder — tracks cell accesses made during evaluation.
+         *
+         * When a formula with `hasDynamicRefs` (INDIRECT/OFFSET) is being evaluated,
+         * every `getCellValue` / `buildRangeArray` call records the accessed cell/range
+         * key here. After evaluation, these dynamic edges can be merged with the
+         * compiled static dependency set to produce a complete dependency graph.
+         *
+         * Key: formula cell key being evaluated → Set of accessed cell keys.
+         * Only populated for formulas that have `hasDynamicRefs === true`.
+         */
+        this.dynamicDeps = new Map();
+        /**
+         * The formula cell key currently being recorded (null if recording is off).
+         * Set before evaluating a formula with dynamic refs, cleared after.
+         */
+        this.recordingKey = null;
+        /**
+         * Current LAMBDA invocation depth. Guards against unbounded recursion
+         * (e.g. `LAMBDA(x, x(x))(LAMBDA(x, x(x)))`) that would otherwise overflow
+         * the JS call stack. Excel documents a recursion limit of ~256.
+         */
+        this.lambdaDepth = 0;
+        /**
+         * AST cache for INDIRECT re-parsing. INDIRECT receives a runtime string
+         * describing a reference; re-parsing it per invocation would be wasted
+         * work, so we memoise the `bound` expression keyed on the reference
+         * text. This belongs to the session (per-calculation lifetime) rather
+         * than the snapshot because the bindings depend on the evaluation
+         * context.
+         */
+        this.indirectAstCache = new Map();
+    }
+    makeKey(sheet, row, col) {
+        return formulaCellKey(sheet, row, col);
+    }
+    /**
+     * Record a cell access for the currently-recording formula.
+     */
+    recordAccess(sheet, row, col) {
+        if (this.recordingKey === null) {
+            return;
+        }
+        let deps = this.dynamicDeps.get(this.recordingKey);
+        if (!deps) {
+            deps = new Set();
+            this.dynamicDeps.set(this.recordingKey, deps);
+        }
+        deps.add(formulaCellKey(sheet, row, col));
+    }
+}
+// ============================================================================
+// Main Evaluate Function
+// ============================================================================
+/**
+ * Exhaustiveness helper — TypeScript narrows `never` here to prove that
+ * every discriminated-union variant was handled. At runtime this should be
+ * unreachable; if a new variant is added without a case, compilation fails.
+ */
+function assertNever(x) {
+    throw new Error(`unexpected variant: ${JSON.stringify(x)}`);
+}
+/**
+ * Evaluate a BoundExpr to produce a RuntimeValue.
+ */
+export function evaluate(expr, ctx, session) {
+    switch (expr.kind) {
+        case BoundExprKind.Literal:
+            return evaluateLiteral(expr);
+        case BoundExprKind.CellRef:
+            return evaluateCellRef(expr, ctx, session);
+        case BoundExprKind.AreaRef:
+            return evaluateAreaRef(expr, ctx, session);
+        case BoundExprKind.ColRangeRef:
+            return evaluateColRange(expr, ctx, session);
+        case BoundExprKind.RowRangeRef:
+            return evaluateRowRange(expr, ctx, session);
+        case BoundExprKind.Ref3D:
+            return evaluateRef3D(expr, ctx, session);
+        case BoundExprKind.BinaryOp:
+            return evaluateBinaryOp(expr.op, expr.left, expr.right, ctx, session);
+        case BoundExprKind.UnaryOp:
+            return evaluateUnaryOp(expr.op, expr.operand, ctx, session);
+        case BoundExprKind.Percent:
+            return evaluatePercent(expr.operand, ctx, session);
+        case BoundExprKind.Call:
+            return evaluateCall(expr, ctx, session);
+        case BoundExprKind.SpecialCall:
+            return evaluateSpecialCall(expr, ctx, session);
+        case BoundExprKind.Array:
+            return evaluateArrayLiteral(expr, ctx, session);
+        case BoundExprKind.NameExpr:
+            return evaluateNameExpr(expr, ctx, session);
+        case BoundExprKind.Lambda:
+            return evaluateLambdaExpr(expr, ctx);
+        case BoundExprKind.StructuredRef:
+            return evaluateStructuredRef(expr, ctx, session);
+        default:
+            return assertNever(expr);
+    }
+}
+// ============================================================================
+// Literal
+// ============================================================================
+function evaluateLiteral(expr) {
+    if (expr.errorCode) {
+        return rvError(expr.errorCode);
+    }
+    if (expr.value === null) {
+        return BLANK;
+    }
+    if (typeof expr.value === "number") {
+        return rvNumber(expr.value);
+    }
+    if (typeof expr.value === "string") {
+        return rvString(expr.value);
+    }
+    if (typeof expr.value === "boolean") {
+        return rvBoolean(expr.value);
+    }
+    return BLANK;
+}
+// ============================================================================
+// Cell Reference
+// ============================================================================
+function evaluateCellRef(expr, ctx, session) {
+    return rvCellRef(expr.sheet, expr.row, expr.col);
+}
+// ============================================================================
+// Area Reference → ReferenceValue
+// ============================================================================
+function evaluateAreaRef(expr, ctx, session) {
+    return rvRef(expr.sheet, expr.top, expr.left, expr.bottom, expr.right);
+}
+function evaluateColRange(expr, ctx, session) {
+    const ws = ctx.snapshot.worksheetsByName.get(expr.sheet.toLowerCase());
+    if (!ws || !ws.dimensions) {
+        return rvArray([]);
+    }
+    return rvRef(expr.sheet, ws.dimensions.top, expr.leftCol, ws.dimensions.bottom, expr.rightCol);
+}
+function evaluateRowRange(expr, ctx, session) {
+    const ws = ctx.snapshot.worksheetsByName.get(expr.sheet.toLowerCase());
+    if (!ws || !ws.dimensions) {
+        return rvArray([]);
+    }
+    return rvRef(expr.sheet, expr.topRow, ws.dimensions.left, expr.bottomRow, ws.dimensions.right);
+}
+function evaluateRef3D(expr, ctx, session) {
+    const areas = [];
+    for (const sheet of expr.sheets) {
+        if (expr.inner.kind === BoundExprKind.CellRef) {
+            areas.push({
+                sheet,
+                top: expr.inner.row,
+                left: expr.inner.col,
+                bottom: expr.inner.row,
+                right: expr.inner.col
+            });
+        }
+        else {
+            // For AreaRef: if the inner range is a whole-column or whole-row
+            // reference (top = 1 & bottom = 1048576, or left = 1 & right =
+            // 16384), clamp it against each sheet's actual used dimensions.
+            // Without this clamp, a 3D reference like `Sheet1:Sheet3!A:A`
+            // would allocate 3 × 1M rows of BLANK values and spend seconds
+            // (or OOM) before SUM even starts. The non-3D path already does
+            // this clamp in `evaluateColRange`; parity with that is what we
+            // want here.
+            let top = expr.inner.top;
+            let left = expr.inner.left;
+            let bottom = expr.inner.bottom;
+            let right = expr.inner.right;
+            const isWholeCol = top === 1 && bottom === 1048576;
+            const isWholeRow = left === 1 && right === 16384;
+            if (isWholeCol || isWholeRow) {
+                const ws = ctx.snapshot.worksheetsByName.get(sheet.toLowerCase());
+                const dims = ws?.dimensions;
+                if (dims) {
+                    if (isWholeCol) {
+                        top = dims.top;
+                        bottom = dims.bottom;
+                    }
+                    if (isWholeRow) {
+                        left = dims.left;
+                        right = dims.right;
+                    }
+                }
+            }
+            areas.push({ sheet, top, left, bottom, right });
+        }
+    }
+    return { kind: RVKind.Reference, areas };
+}
+// ============================================================================
+// Build Range Array from Snapshot
+// ============================================================================
+function buildRangeArray(ctx, session, sheet, top, left, bottom, right) {
+    // Hoist the worksheet lookup once for the entire range — avoids
+    // N redundant toLowerCase()/Map.get() calls inside the hot loop.
+    const ws = ctx.snapshot.worksheetsByName.get(sheet.toLowerCase());
+    const cells = ws?.cells;
+    const wsHiddenRows = ws?.hiddenRows;
+    const compiledFormulas = ctx.compiledFormulas;
+    const resultCache = session.resultCache;
+    // Hoist the recording guard — when not recording, skip recordAccess
+    // entirely in the loop instead of paying the function-call overhead.
+    const recording = session.recordingKey !== null;
+    const rows = [];
+    // Lazily-allocated masks: only materialized once we encounter a
+    // SUBTOTAL/AGGREGATE cell or a hidden row inside the range. For the
+    // common case (plain data range, no hidden rows) we never touch these
+    // and emit an ArrayValue without extra metadata.
+    let subtotalMask;
+    let hiddenRowMask;
+    const height = bottom - top + 1;
+    const width = right - left + 1;
+    for (let r = top; r <= bottom; r++) {
+        const row = [];
+        const ri = r - top;
+        // Record row visibility — SUBTOTAL 1xx / AGGREGATE opt 5/7 use it.
+        if (wsHiddenRows?.has(r)) {
+            if (!hiddenRowMask) {
+                hiddenRowMask = new Array(height).fill(false);
+            }
+            hiddenRowMask[ri] = true;
+        }
+        for (let c = left; c <= right; c++) {
+            if (recording) {
+                session.recordAccess(sheet, r, c);
+            }
+            // Missing worksheet: matches getCellValue's BLANK fallback.
+            if (!cells) {
+                row.push(BLANK);
+                continue;
+            }
+            const cell = cells.get(snapshotCellKey(r, c));
+            if (!cell) {
+                // No snapshot cell yet — might still be inside a live spill
+                // (e.g. reading A2..A5 while A1 = SEQUENCE(5) is still being
+                // materialized). See `readLiveSpill` for the lookup path.
+                const live = readLiveSpill(sheet, r, c, session);
+                row.push(live ? topLeft(live) : BLANK);
+                continue;
+            }
+            if (cell.formulaKind !== "none" && cell.formula) {
+                const fKey = formulaCellKey(sheet, r, c);
+                const compiled = compiledFormulas.get(fKey);
+                // Mark SUBTOTAL/AGGREGATE output cells so an outer SUBTOTAL /
+                // AGGREGATE over this range knows to skip them (Excel's
+                // no-double-count semantics).
+                if (compiled?.isSubtotalOutput) {
+                    if (!subtotalMask) {
+                        subtotalMask = new Array(height);
+                        for (let i = 0; i < height; i++) {
+                            subtotalMask[i] = new Array(width).fill(false);
+                        }
+                    }
+                    subtotalMask[ri][c - left] = true;
+                }
+                const cached = resultCache.get(fKey);
+                if (cached !== undefined) {
+                    row.push(topLeft(cached.scalar));
+                    continue;
+                }
+                if (compiled) {
+                    row.push(topLeft(evaluateFormula(compiled, ctx, session)));
+                    continue;
+                }
+            }
+            // Non-formula snapshot cell — but it might still be a ghost slot
+            // that a fresh dynamic-array spill is about to overwrite. Prefer
+            // the live value when a master is registered so this-pass SUM /
+            // LOOKUP / etc. see the new spill immediately.
+            const live = readLiveSpill(sheet, r, c, session);
+            if (live) {
+                row.push(topLeft(live));
+                continue;
+            }
+            row.push(topLeft(fromSnapshotValue(cell.value)));
+        }
+        rows.push(row);
+    }
+    return rvArray(rows, top, left, subtotalMask, hiddenRowMask);
+}
+// ============================================================================
+// Dereference: Reference → concrete value
+// ============================================================================
+/**
+ * Resolve a `ReferenceValue` to its concrete value (scalar or array).
+ * - Single-cell references (from CellRef nodes) resolve to a scalar.
+ * - Area references (even 1x1 from A1:A1) produce an array.
+ * - Multi-area references (from 3D refs) flatten all areas into one array.
+ * Non-reference values are returned unchanged.
+ */
+function dereferenceValue(v, ctx, session) {
+    if (v.kind !== RVKind.Reference) {
+        return v;
+    }
+    if (v.areas.length === 0) {
+        return BLANK;
+    }
+    // Single-cell references (from CellRef nodes) resolve to scalar
+    if (v.singleCell) {
+        const area = v.areas[0];
+        return getCellValue(area.sheet, area.top, area.left, ctx, session);
+    }
+    // Single area — build range array
+    if (v.areas.length === 1) {
+        const area = v.areas[0];
+        return buildRangeArray(ctx, session, area.sheet, area.top, area.left, area.bottom, area.right);
+    }
+    // Multi-area (3D reference) — flatten all areas into one array
+    const allRows = [];
+    let mergedSubtotal;
+    let mergedHidden;
+    for (const area of v.areas) {
+        const arr = buildRangeArray(ctx, session, area.sheet, area.top, area.left, area.bottom, area.right);
+        const startRow = allRows.length;
+        for (const row of arr.rows) {
+            allRows.push([...row]);
+        }
+        // Merge masks from this area into the flattened output. Only
+        // allocate the merged masks when the first masked area shows up —
+        // most multi-area refs have no masks and should pay no overhead.
+        if (arr.subtotalMask || arr.hiddenRowMask) {
+            const height = arr.height;
+            if (arr.subtotalMask) {
+                if (!mergedSubtotal) {
+                    mergedSubtotal = [];
+                    for (let i = 0; i < startRow; i++) {
+                        // Widths may differ across areas; mask rows use each area's
+                        // own width so an outer SUBTOTAL reads the right positions.
+                        mergedSubtotal.push([]);
+                    }
+                }
+                for (let r = 0; r < height; r++) {
+                    mergedSubtotal.push([...arr.subtotalMask[r]]);
+                }
+            }
+            else if (mergedSubtotal) {
+                // Pad with empty rows so indices stay aligned.
+                for (let r = 0; r < height; r++) {
+                    mergedSubtotal.push([]);
+                }
+            }
+            if (arr.hiddenRowMask) {
+                if (!mergedHidden) {
+                    mergedHidden = new Array(startRow).fill(false);
+                }
+                for (let r = 0; r < height; r++) {
+                    mergedHidden.push(arr.hiddenRowMask[r] ?? false);
+                }
+            }
+            else if (mergedHidden) {
+                for (let r = 0; r < height; r++) {
+                    mergedHidden.push(false);
+                }
+            }
+        }
+        else if (mergedSubtotal || mergedHidden) {
+            // An earlier area had masks; pad this area's rows with non-masked
+            // entries to keep row indices aligned.
+            const height = arr.height;
+            if (mergedSubtotal) {
+                for (let r = 0; r < height; r++) {
+                    mergedSubtotal.push([]);
+                }
+            }
+            if (mergedHidden) {
+                for (let r = 0; r < height; r++) {
+                    mergedHidden.push(false);
+                }
+            }
+        }
+    }
+    return rvArray(allRows, undefined, undefined, mergedSubtotal, mergedHidden);
+}
+// ============================================================================
+// Get Cell Value from Snapshot
+// ============================================================================
+function getCellValue(sheetName, row, col, ctx, session) {
+    // Record this access for runtime dependency tracking. Inline guard
+    // avoids the function call overhead in the common case where no
+    // recording is active (formulas without dynamic refs).
+    if (session.recordingKey !== null) {
+        session.recordAccess(sheetName, row, col);
+    }
+    const ws = ctx.snapshot.worksheetsByName.get(sheetName.toLowerCase());
+    if (!ws) {
+        return BLANK;
+    }
+    const cellKey = snapshotCellKey(row, col);
+    const cell = ws.cells.get(cellKey);
+    if (!cell) {
+        // The cell isn't in the snapshot, but we might still have a live
+        // spill value for it — look up the master formula and extract the
+        // right array element. Matters when a downstream formula like
+        // `SUM(A1:A5)` runs before materialize writes the ghost cells for
+        // `A1 = SEQUENCE(5)` into the snapshot.
+        return readLiveSpill(sheetName, row, col, session) ?? BLANK;
+    }
+    // If this cell has a formula, evaluate it
+    if (cell.formulaKind !== "none" && cell.formula) {
+        const fKey = formulaCellKey(sheetName, row, col);
+        // Check cache — return scalar form for dependency resolution
+        const cached = session.resultCache.get(fKey);
+        if (cached !== undefined) {
+            return cached.scalar;
+        }
+        // Get compiled formula
+        const compiled = ctx.compiledFormulas.get(fKey);
+        if (compiled) {
+            return evaluateFormula(compiled, ctx, session);
+        }
+    }
+    // Non-formula cell — but it might also be a ghost for a live spill
+    // (e.g. a value that exists in the snapshot from a previous calc
+    // cycle but is about to be overwritten by a fresh spill). Prefer the
+    // live value when a master is registered.
+    const spill = readLiveSpill(sheetName, row, col, session);
+    if (spill) {
+        return spill;
+    }
+    return fromSnapshotValue(cell.value);
+}
+/**
+ * Retrieve the spill-target value at (sheetName, row, col) from an
+ * already-evaluated dynamic-array master. Returns `undefined` when no
+ * master is registered for that cell — callers fall back to the
+ * snapshot value or BLANK.
+ */
+function readLiveSpill(sheetName, row, col, session) {
+    const key = session.makeKey(sheetName, row, col);
+    const spill = session.liveSpills.get(key);
+    if (!spill) {
+        return undefined;
+    }
+    const master = session.resultCache.get(spill.masterKey);
+    if (!master || master.raw.kind !== RVKind.Array) {
+        return undefined;
+    }
+    const arr = master.raw;
+    if (spill.rowOffset >= arr.height || spill.colOffset >= arr.width) {
+        return undefined;
+    }
+    return arr.rows[spill.rowOffset][spill.colOffset];
+}
+// ============================================================================
+// Evaluate a Compiled Formula
+// ============================================================================
+/**
+ * Shared implementation for evaluateFormula and evaluateFormulaRaw.
+ *
+ * Handles key computation, cache lookup, circular reference detection,
+ * expression evaluation, and result caching.
+ */
+function evaluateFormulaInner(compiled, ctx, session) {
+    const inst = compiled.instance;
+    const key = session.makeKey(inst.sheetName, inst.row, inst.col);
+    // Check cache
+    const cached = session.resultCache.get(key);
+    if (cached !== undefined) {
+        return cached;
+    }
+    // Circular reference detection. Under iterative calculation the driver
+    // (calculate-formulas-impl.ts) seeds `circularFallback` with the previous
+    // iteration's result so the re-entrant lookup receives a stable value.
+    // Outside of iterative mode the map is empty — we return 0 as the fallback,
+    // matching Excel's "iterate with 0 seed" convention. This keeps simple
+    // cycles like A1=A1+1 producing a number instead of an error, which is the
+    // established behaviour for this engine (tests depend on this). For strict
+    // circular-reference error reporting, enable iterative calculation and
+    // observe convergence failure, or configure a custom fallback value.
+    if (session.evaluating.has(key)) {
+        const fallback = session.circularFallback.get(key);
+        const val = fallback !== undefined ? fallback : rvNumber(0);
+        return { scalar: val, raw: val };
+    }
+    session.evaluating.add(key);
+    const prevAddress = ctx.currentAddress;
+    const prevSheet = ctx.currentSheet;
+    const prevRecording = session.recordingKey;
+    ctx.currentAddress = { sheet: inst.sheetName, row: inst.row, col: inst.col };
+    ctx.currentSheet = inst.sheetName;
+    // Enable runtime dependency recording for formulas with dynamic refs
+    if (compiled.hasDynamicRefs) {
+        session.recordingKey = key;
+    }
+    try {
+        const result = evaluate(compiled.bound, ctx, session);
+        const intersected = implicitIntersect(result, ctx);
+        const scalar = dereferenceValue(intersected, ctx, session);
+        const raw = dereferenceValue(result, ctx, session);
+        const entry = { scalar, raw };
+        session.resultCache.set(key, entry);
+        // Register the spill region if this is a dynamic-array formula
+        // whose result is a multi-cell array. Downstream formulas that
+        // read into the spill range (e.g. `=SUM(A1:A5)` over a
+        // `=SEQUENCE(5)` master) can now pick up the ghost-cell values
+        // before materialize writes them back to the snapshot.
+        const isDyn = compiled.instance.isDynamicArray || compiled.isDynamicArrayFunction;
+        if (isDyn && raw.kind === RVKind.Array && (raw.height > 1 || raw.width > 1)) {
+            for (let r = 0; r < raw.height; r++) {
+                for (let c = 0; c < raw.width; c++) {
+                    if (r === 0 && c === 0) {
+                        continue; // master cell already points to its own cache entry
+                    }
+                    const targetKey = session.makeKey(inst.sheetName, inst.row + r, inst.col + c);
+                    session.liveSpills.set(targetKey, {
+                        masterKey: key,
+                        rowOffset: r,
+                        colOffset: c
+                    });
+                }
+            }
+        }
+        return entry;
+    }
+    catch (err) {
+        // Cache a #CALC! sentinel so a re-entrant lookup for the same cell does
+        // not trigger repeated (exponentially growing) re-evaluation under
+        // iterative calc or dependent recomputation. The exception is re-thrown
+        // so the outer caller can still log / translate it into a sheet error.
+        const fallback = { scalar: ERRORS.CALC, raw: ERRORS.CALC };
+        session.resultCache.set(key, fallback);
+        throw err;
+    }
+    finally {
+        session.evaluating.delete(key);
+        ctx.currentAddress = prevAddress;
+        ctx.currentSheet = prevSheet;
+        session.recordingKey = prevRecording;
+    }
+}
+/**
+ * Evaluate a compiled formula and return its **scalar** result.
+ *
+ * This is the standard evaluation path for regular (non-array) formulas.
+ * The result is:
+ * 1. Evaluated from the bound expression tree
+ * 2. Implicit-intersected to a single value/reference
+ * 3. Dereferenced if it's a reference
+ * 4. Cached for subsequent lookups by dependent formulas
+ *
+ * Use `evaluateFormulaRaw` instead when the full array result is needed
+ * (dynamic array formulas, CSE formulas).
+ */
+export function evaluateFormula(compiled, ctx, session) {
+    return evaluateFormulaInner(compiled, ctx, session).scalar;
+}
+/**
+ * Evaluate a compiled formula and return the **raw** (possibly array) result.
+ *
+ * This is the evaluation path for dynamic array and CSE formulas where
+ * the full array shape must be preserved for spill/distribution.
+ *
+ * Semantics:
+ * - Both scalar and raw forms are stored in `session.resultCache` as a
+ *   `CachedResult{scalar, raw}`. Dependent scalar formulas see the scalar
+ *   form; the materialize layer retrieves the raw form.
+ * - The return value is the full dereferenced result — may be an ArrayValue
+ *   with height > 1 or width > 1.
+ */
+export function evaluateFormulaRaw(compiled, ctx, session) {
+    return evaluateFormulaInner(compiled, ctx, session).raw;
+}
+// ============================================================================
+// Binary Operations
+// ============================================================================
+function evaluateBinaryOp(op, leftExpr, rightExpr, ctx, session) {
+    // Intersection operator (whitespace between two refs). Must be handled
+    // BEFORE dereferencing so we can inspect the reference areas.
+    if (op === " ") {
+        return evaluateIntersection(leftExpr, rightExpr, ctx, session);
+    }
+    // Range operator `:` — union of two references into the bounding
+    // rectangle. Needed when one side is a function call (e.g.
+    // `B11:INDIRECT("B" & ROW()-1)`). Both sides must be references or
+    // coerce to references; otherwise Excel returns #REF!.
+    if (op === ":") {
+        return evaluateRangeUnion(leftExpr, rightExpr, ctx, session);
+    }
+    const left = dereferenceValue(evaluate(leftExpr, ctx, session), ctx, session);
+    const right = dereferenceValue(evaluate(rightExpr, ctx, session), ctx, session);
+    const lIsArr = left.kind === RVKind.Array;
+    const rIsArr = right.kind === RVKind.Array;
+    if (lIsArr || rIsArr) {
+        return broadcastBinaryOp(op, left, right);
+    }
+    return applyScalarBinaryOp(op, topLeft(left), topLeft(right));
+}
+/**
+ * Excel's intersection operator — a whitespace character separating two
+ * references (e.g. `A1:A10 B1:B10`).
+ *
+ * Semantics:
+ * - Both operands must evaluate to single-area references. Otherwise the
+ *   result is `#VALUE!` (matches Excel's behaviour when non-refs or
+ *   multi-area refs are intersected).
+ * - Intersection is the rectangle overlap of the two areas on the same
+ *   sheet.
+ * - If the areas do not overlap (or are on different sheets) the result
+ *   is `#NULL!`, Excel's canonical "empty intersection" error.
+ */
+function evaluateIntersection(leftExpr, rightExpr, ctx, session) {
+    const left = evaluate(leftExpr, ctx, session);
+    const right = evaluate(rightExpr, ctx, session);
+    if (isError(left)) {
+        return left;
+    }
+    if (isError(right)) {
+        return right;
+    }
+    if (left.kind !== RVKind.Reference || right.kind !== RVKind.Reference) {
+        return ERRORS.VALUE;
+    }
+    if (left.areas.length !== 1 || right.areas.length !== 1) {
+        return ERRORS.VALUE;
+    }
+    const la = left.areas[0];
+    const ra = right.areas[0];
+    if (la.sheet.toLowerCase() !== ra.sheet.toLowerCase()) {
+        return ERRORS.NULL;
+    }
+    const top = Math.max(la.top, ra.top);
+    const left_ = Math.max(la.left, ra.left);
+    const bottom = Math.min(la.bottom, ra.bottom);
+    const right_ = Math.min(la.right, ra.right);
+    if (top > bottom || left_ > right_) {
+        return ERRORS.NULL;
+    }
+    return rvRef(la.sheet, top, left_, bottom, right_);
+}
+/**
+ * Range operator `:` applied at runtime. Normally `A1:B2` is merged by
+ * the tokenizer, but patterns like `A1:INDIRECT("B5")` leave the colon
+ * as a standalone operator. Both operands must evaluate to references
+ * (single-cell or area); the result is the bounding rectangle of the
+ * two reference ranges on the same sheet.
+ *
+ * Semantics:
+ *   - Both sides must be references. Literal numbers / strings → #VALUE!.
+ *   - References must live on the same sheet → else #REF!.
+ *   - Multi-area references on either side → #REF! (Excel behavior).
+ */
+function evaluateRangeUnion(leftExpr, rightExpr, ctx, session) {
+    const left = evaluate(leftExpr, ctx, session);
+    const right = evaluate(rightExpr, ctx, session);
+    if (isError(left)) {
+        return left;
+    }
+    if (isError(right)) {
+        return right;
+    }
+    if (left.kind !== RVKind.Reference || right.kind !== RVKind.Reference) {
+        return ERRORS.VALUE;
+    }
+    if (left.areas.length !== 1 || right.areas.length !== 1) {
+        return ERRORS.REF;
+    }
+    const la = left.areas[0];
+    const ra = right.areas[0];
+    if (la.sheet.toLowerCase() !== ra.sheet.toLowerCase()) {
+        return ERRORS.REF;
+    }
+    // Bounding rectangle that spans both areas — this is the union /
+    // range-op semantics (Excel), distinct from intersection which uses
+    // min/max in the opposite direction.
+    const top = Math.min(la.top, ra.top);
+    const left_ = Math.min(la.left, ra.left);
+    const bottom = Math.max(la.bottom, ra.bottom);
+    const right_ = Math.max(la.right, ra.right);
+    return rvRef(la.sheet, top, left_, bottom, right_);
+}
+function applyScalarBinaryOp(op, left, right) {
+    if (isError(left)) {
+        return left;
+    }
+    if (isError(right)) {
+        return right;
+    }
+    // Concatenation
+    if (op === "&") {
+        const lStr = toStringRV(left);
+        const rStr = toStringRV(right);
+        return rvString(lStr + rStr);
+    }
+    // Comparison
+    if (op === "=" || op === "<>" || op === "<" || op === ">" || op === "<=" || op === ">=") {
+        return rvBoolean(compareScalars(left, right, op));
+    }
+    // Arithmetic
+    const lNum = toNumberRV(left);
+    if (isError(lNum)) {
+        return lNum;
+    }
+    const rNum = toNumberRV(right);
+    if (isError(rNum)) {
+        return rNum;
+    }
+    let result;
+    switch (op) {
+        case "+":
+            result = lNum.value + rNum.value;
+            break;
+        case "-":
+            result = lNum.value - rNum.value;
+            break;
+        case "*":
+            result = lNum.value * rNum.value;
+            break;
+        case "/":
+            if (rNum.value === 0) {
+                return ERRORS.DIV0;
+            }
+            result = lNum.value / rNum.value;
+            break;
+        case "^":
+            // Excel distinguishes `0 ^ n` for n < 0 (→ #DIV/0!, since it's
+            // semantically 1/0) from other overflows (→ #NUM!). The generic
+            // `isFinite` check below loses that distinction, so route the
+            // division-by-zero case explicitly first. 0^0 is conventionally 1
+            // (matches Excel and POWER()).
+            if (lNum.value === 0) {
+                if (rNum.value < 0) {
+                    return ERRORS.DIV0;
+                }
+                if (rNum.value === 0) {
+                    return rvNumber(1);
+                }
+            }
+            result = Math.pow(lNum.value, rNum.value);
+            if (Number.isNaN(result)) {
+                // `Math.pow(-1, 0.5)` etc. — complex result; Excel reports #NUM!.
+                return ERRORS.NUM;
+            }
+            break;
+        default:
+            return ERRORS.VALUE;
+    }
+    return !isFinite(result) ? ERRORS.NUM : rvNumber(result);
+}
+function compareScalars(left, right, op) {
+    // Normalize blanks to a neutral form of the opposing kind so formulas like
+    // `"" = A1` (where A1 is blank) compare equal. Without this normalisation
+    // Excel would route us to the cross-type tiebreak below.
+    const l = left.kind === RVKind.Blank
+        ? right.kind === RVKind.String
+            ? rvString("")
+            : right.kind === RVKind.Boolean
+                ? rvBoolean(false)
+                : rvNumber(0)
+        : left;
+    const r = right.kind === RVKind.Blank
+        ? left.kind === RVKind.String
+            ? rvString("")
+            : left.kind === RVKind.Boolean
+                ? rvBoolean(false)
+                : rvNumber(0)
+        : right;
+    let cmp;
+    if (l.kind === r.kind) {
+        cmp = compareScalarsSameKind(l, r);
+        if (!Number.isFinite(cmp)) {
+            cmp = 0;
+        }
+    }
+    else {
+        // Excel orders scalar kinds: Number < String < Boolean < Error/Blank.
+        const order = (v) => {
+            if (v.kind === RVKind.Number) {
+                return 0;
+            }
+            if (v.kind === RVKind.String) {
+                return 1;
+            }
+            if (v.kind === RVKind.Boolean) {
+                return 2;
+            }
+            return 3;
+        };
+        cmp = order(l) - order(r);
+    }
+    switch (op) {
+        case "=":
+            return cmp === 0;
+        case "<>":
+            return cmp !== 0;
+        case "<":
+            return cmp < 0;
+        case ">":
+            return cmp > 0;
+        case "<=":
+            return cmp <= 0;
+        case ">=":
+            return cmp >= 0;
+        default:
+            return false;
+    }
+}
+function broadcastBinaryOp(op, left, right) {
+    const lArr = left.kind === RVKind.Array ? left : null;
+    const rArr = right.kind === RVKind.Array ? right : null;
+    const lRows = lArr ? lArr.height : 1;
+    const lCols = lArr ? lArr.width : 1;
+    const rRows = rArr ? rArr.height : 1;
+    const rCols = rArr ? rArr.width : 1;
+    const outRows = Math.max(lRows, rRows);
+    const outCols = Math.max(lCols, rCols);
+    if ((lRows !== 1 && rRows !== 1 && lRows !== rRows) ||
+        (lCols !== 1 && rCols !== 1 && lCols !== rCols)) {
+        return ERRORS.VALUE;
+    }
+    // Guard against pathological broadcasts (e.g. A:A * 1:1 = ~17B cells).
+    // 10M cells is well beyond any legitimate array use case.
+    if (outRows * outCols > 10000000) {
+        return ERRORS.CALC;
+    }
+    // Precompute scalar-broadcast values once outside the hot cell loop.
+    // When one side is a non-array `RuntimeValue`, it expands to the same
+    // `ScalarValue` for every (r, c); repeating `topLeft(left)` inside the
+    // inner loop (outRows × outCols calls) was pure overhead.
+    const lScalarFallback = lArr ? undefined : topLeft(left);
+    const rScalarFallback = rArr ? undefined : topLeft(right);
+    const rows = [];
+    for (let r = 0; r < outRows; r++) {
+        const row = [];
+        for (let c = 0; c < outCols; c++) {
+            const lR = lRows === 1 ? 0 : r;
+            const lC = lCols === 1 ? 0 : c;
+            const rR = rRows === 1 ? 0 : r;
+            const rC = rCols === 1 ? 0 : c;
+            // Array values are rectangular (normalised by rvArray) so direct
+            // indexing is safe; the previous `?? BLANK` fallback was defensive
+            // code that never triggered in practice but cost an optional chain
+            // per cell in a hot loop.
+            const lVal = lArr ? lArr.rows[lR][lC] : lScalarFallback;
+            const rVal = rArr ? rArr.rows[rR][rC] : rScalarFallback;
+            row.push(applyScalarBinaryOp(op, lVal, rVal));
+        }
+        rows.push(row);
+    }
+    // Propagate origin metadata
+    const originRow = lArr?.originRow ?? rArr?.originRow;
+    const originCol = lArr?.originCol ?? rArr?.originCol;
+    return rvArray(rows, originRow, originCol);
+}
+// ============================================================================
+// Unary Operations
+// ============================================================================
+function evaluateUnaryOp(op, operandExpr, ctx, session) {
+    const rawVal = evaluate(operandExpr, ctx, session);
+    // @ implicit intersection
+    if (op === "@") {
+        const intersected = implicitIntersect(rawVal, ctx);
+        return dereferenceValue(intersected, ctx, session);
+    }
+    const val = dereferenceValue(rawVal, ctx, session);
+    if (val.kind === RVKind.Array) {
+        const rows = [];
+        for (const row of val.rows) {
+            rows.push(row.map(cell => applyScalarUnary(op, cell)));
+        }
+        return rvArray(rows, val.originRow, val.originCol);
+    }
+    return applyScalarUnary(op, topLeft(val));
+}
+function applyScalarUnary(op, val) {
+    if (isError(val)) {
+        return val;
+    }
+    const n = toNumberRV(val);
+    if (isError(n)) {
+        return n;
+    }
+    switch (op) {
+        case "-":
+            return rvNumber(-n.value);
+        case "+":
+            return n;
+        default:
+            return ERRORS.VALUE;
+    }
+}
+// ============================================================================
+// Percent
+// ============================================================================
+function evaluatePercent(operandExpr, ctx, session) {
+    const val = dereferenceValue(evaluate(operandExpr, ctx, session), ctx, session);
+    if (val.kind === RVKind.Array) {
+        const rows = [];
+        for (const row of val.rows) {
+            rows.push(row.map(cell => {
+                if (isError(cell)) {
+                    return cell;
+                }
+                const n = toNumberRV(cell);
+                if (isError(n)) {
+                    return n;
+                }
+                return rvNumber(n.value / 100);
+            }));
+        }
+        return rvArray(rows);
+    }
+    const scalar = topLeft(val);
+    if (isError(scalar)) {
+        return scalar;
+    }
+    const n = toNumberRV(scalar);
+    if (isError(n)) {
+        return n;
+    }
+    return rvNumber(n.value / 100);
+}
+// ============================================================================
+// Function Call (Eager)
+// ============================================================================
+function evaluateCall(expr, ctx, session) {
+    // Reference functions: ROW, COLUMN, ROWS, COLUMNS
+    // (Accept _XLFN. prefixed names transparently.)
+    const canonical = stripFunctionPrefix(expr.name);
+    const refResult = tryEvaluateRefFunction(canonical, expr.args, ctx);
+    if (refResult !== undefined) {
+        return refResult;
+    }
+    // Reference-producing functions like INDIRECT/OFFSET yield a
+    // ReferenceValue at runtime. ROW/COLUMN/ROWS/COLUMNS need to inspect
+    // the resulting reference's address rather than its dereferenced value,
+    // so we evaluate the argument *without* dereferencing and extract the
+    // geometry directly. Only the 1-arg reference-only forms go down this
+    // path; scalar/array arguments still fall through to the eager fallback
+    // below, which returns #VALUE! for ROW/COLUMN and the correct count for
+    // ROWS/COLUMNS.
+    if (expr.args.length === 1 && isSimpleRefFunction(canonical)) {
+        const raw = evaluate(expr.args[0], ctx, session);
+        if (raw.kind === RVKind.Reference && raw.areas.length > 0) {
+            const area = raw.areas[0];
+            switch (canonical) {
+                case "ROW":
+                    return rvNumber(area.top);
+                case "COLUMN":
+                    return rvNumber(area.left);
+                case "ROWS":
+                    return rvNumber(area.bottom - area.top + 1);
+                case "COLUMNS":
+                    return rvNumber(area.right - area.left + 1);
+            }
+        }
+    }
+    // ── Reference-aware functions (ISREF, CELL) ──
+    // These inspect the argument's reference-ness rather than its dereferenced
+    // value. Handled here so the raw BoundExpr / ReferenceValue is visible.
+    if (canonical === "ISREF") {
+        return evaluateISREF(expr.args, ctx, session);
+    }
+    if (canonical === "CELL") {
+        return evaluateCELL(expr.args, ctx, session);
+    }
+    // Evaluate all arguments eagerly and dereference references
+    const args = expr.args.map(arg => dereferenceValue(evaluate(arg, ctx, session), ctx, session));
+    // Look up function
+    const desc = lookupFunction(expr.name);
+    if (desc) {
+        // Validate arity — produce #VALUE! for wrong argument count
+        if (args.length < desc.minArity || args.length > desc.maxArity) {
+            return ERRORS.VALUE;
+        }
+        // Context-aware overrides for functions that need evaluator state
+        switch (canonical) {
+            case "SHEET": {
+                // SHEET() → current sheet number; SHEET(ref) → sheet number of ref
+                if (args.length === 0) {
+                    const idx = ctx.snapshot.worksheets.findIndex(ws => ws.name.toLowerCase() === ctx.currentSheet.toLowerCase());
+                    return rvNumber(idx >= 0 ? idx + 1 : 1);
+                }
+                return desc.invoke(args);
+            }
+            case "SHEETS": {
+                // SHEETS() → total sheet count
+                if (args.length === 0) {
+                    return rvNumber(ctx.snapshot.worksheets.length);
+                }
+                return desc.invoke(args);
+            }
+            case "ISFORMULA": {
+                // ISFORMULA requires a reference argument. When the raw argument is
+                // a CellRef/AreaRef we can look up the underlying cell's formulaKind.
+                // Any other shape (literal, computed value, etc.) yields #N/A per
+                // Excel's behavior for non-reference arguments.
+                const raw = expr.args[0];
+                if (raw && raw.kind === BoundExprKind.CellRef) {
+                    const ws = ctx.snapshot.worksheetsByName.get(raw.sheet.toLowerCase());
+                    if (!ws) {
+                        return ERRORS.REF;
+                    }
+                    const cell = ws.cells.get(snapshotCellKey(raw.row, raw.col));
+                    return rvBoolean(cell !== undefined && cell.formulaKind !== "none");
+                }
+                if (raw && raw.kind === BoundExprKind.AreaRef) {
+                    const ws = ctx.snapshot.worksheetsByName.get(raw.sheet.toLowerCase());
+                    if (!ws) {
+                        return ERRORS.REF;
+                    }
+                    // ISFORMULA on an area ref inspects the top-left cell.
+                    const cell = ws.cells.get(snapshotCellKey(raw.top, raw.left));
+                    return rvBoolean(cell !== undefined && cell.formulaKind !== "none");
+                }
+                return ERRORS.NA;
+            }
+            case "FORMULATEXT": {
+                // FORMULATEXT returns the formula source text at the referenced cell,
+                // or #N/A if the cell has no formula. Non-reference arguments also
+                // yield #N/A.
+                const raw = expr.args[0];
+                if (raw && raw.kind === BoundExprKind.CellRef) {
+                    const ws = ctx.snapshot.worksheetsByName.get(raw.sheet.toLowerCase());
+                    if (!ws) {
+                        return ERRORS.REF;
+                    }
+                    const cell = ws.cells.get(snapshotCellKey(raw.row, raw.col));
+                    if (cell && cell.formulaKind !== "none" && cell.formula !== undefined) {
+                        return rvString(`=${cell.formula}`);
+                    }
+                    return ERRORS.NA;
+                }
+                if (raw && raw.kind === BoundExprKind.AreaRef) {
+                    const ws = ctx.snapshot.worksheetsByName.get(raw.sheet.toLowerCase());
+                    if (!ws) {
+                        return ERRORS.REF;
+                    }
+                    const cell = ws.cells.get(snapshotCellKey(raw.top, raw.left));
+                    if (cell && cell.formulaKind !== "none" && cell.formula !== undefined) {
+                        return rvString(`=${cell.formula}`);
+                    }
+                    return ERRORS.NA;
+                }
+                return ERRORS.NA;
+            }
+            default:
+                return desc.invoke(args);
+        }
+    }
+    // Check if name resolves to a lambda (defined name or local binding)
+    const lambda = resolveLambdaName(expr.name, args, ctx, session);
+    if (lambda !== undefined) {
+        return lambda;
+    }
+    return ERRORS.NAME;
+}
+// ============================================================================
+// Special Form Call (Lazy)
+// ============================================================================
+function evaluateSpecialCall(expr, ctx, session) {
+    switch (expr.name) {
+        case "IF":
+            return evaluateIF(expr.args, ctx, session);
+        case "IFERROR":
+            return evaluateIFERROR(expr.args, ctx, session);
+        case "IFNA":
+            return evaluateIFNA(expr.args, ctx, session);
+        case "IFS":
+            return evaluateIFS(expr.args, ctx, session);
+        case "SWITCH":
+            return evaluateSWITCH(expr.args, ctx, session);
+        case "CHOOSE":
+            return evaluateCHOOSE(expr.args, ctx, session);
+        case "LET":
+            return evaluateLET(expr.args, ctx, session);
+        case "LAMBDA":
+            return evaluateLAMBDA(expr.args, ctx);
+        case "INDIRECT":
+            return evaluateINDIRECT(expr.args, ctx, session);
+        case "OFFSET":
+            return evaluateOFFSET(expr.args, ctx, session);
+        case "MAP":
+        case "REDUCE":
+        case "SCAN":
+        case "MAKEARRAY":
+        case "BYROW":
+        case "BYCOL":
+            return evaluateHigherOrder(expr.name, expr.args, ctx, session);
+        default:
+            return ERRORS.VALUE;
+    }
+}
+// ============================================================================
+// Special Forms Implementation
+// ============================================================================
+function evaluateIF(args, ctx, session) {
+    if (args.length < 2) {
+        return ERRORS.VALUE;
+    }
+    const condRaw = evalDeref(args[0], ctx, session);
+    // Array condition: element-wise IF. Excel's dynamic-array mode makes
+    // `IF({TRUE,FALSE,TRUE}, "Y", "N")` return `{"Y","N","Y"}`. The branches
+    // are evaluated eagerly — Excel does this too because array broadcasting
+    // requires both shapes to be known — and each cell in the output picks
+    // from the corresponding cell of the chosen branch (with scalar branches
+    // broadcasting to fill the condition array's shape).
+    if (condRaw.kind === RVKind.Array) {
+        const trueVal = evalDeref(args[1], ctx, session);
+        const falseVal = args.length > 2 ? evalDeref(args[2], ctx, session) : rvBoolean(false);
+        const rows = [];
+        for (let r = 0; r < condRaw.height; r++) {
+            const outRow = [];
+            for (let c = 0; c < condRaw.width; c++) {
+                const cell = condRaw.rows[r][c];
+                if (cell.kind === RVKind.Error) {
+                    outRow.push(cell);
+                    continue;
+                }
+                const b = toBooleanRV(cell);
+                if (b.kind === RVKind.Error) {
+                    outRow.push(b);
+                    continue;
+                }
+                const branch = b.value ? trueVal : falseVal;
+                outRow.push(pickCellBroadcast(branch, r, c));
+            }
+            rows.push(outRow);
+        }
+        return rvArray(rows);
+    }
+    const cond = topLeft(condRaw);
+    if (isError(cond)) {
+        return cond;
+    }
+    const bool = toBooleanRV(cond);
+    if (isError(bool)) {
+        return bool;
+    }
+    if (bool.value) {
+        return evaluate(args[1], ctx, session);
+    }
+    return args.length > 2 ? evaluate(args[2], ctx, session) : rvBoolean(false);
+}
+/**
+ * Pick a scalar from `branch` corresponding to grid position (r, c), with
+ * broadcasting: scalar branches are repeated; smaller arrays are indexed
+ * modulo their bounds (out-of-range → BLANK) matching Excel's array
+ * alignment rules for IF/IFS/etc.
+ */
+function pickCellBroadcast(branch, r, c) {
+    if (branch.kind !== RVKind.Array) {
+        return topLeft(branch);
+    }
+    const row = r < branch.height ? r : branch.height === 1 ? 0 : -1;
+    const col = c < branch.width ? c : branch.width === 1 ? 0 : -1;
+    if (row < 0 || col < 0) {
+        // Misaligned array branch (smaller than the condition, and not a
+        // broadcastable 1-row / 1-column shape). Excel fills the gaps with
+        // `#N/A` rather than BLANK, so downstream consumers can distinguish
+        // "branch didn't cover this cell" from "branch actually returned
+        // empty". (R6-P1-7)
+        return ERRORS.NA;
+    }
+    return branch.rows[row][col];
+}
+/**
+ * Shared array-aware error replacement used by IFERROR and IFNA. Scans `val`
+ * for cells matching `isMatch`; if any are found, replaces each with the
+ * top-left scalar of `replacement` (lazily evaluated). Scalar inputs follow
+ * the same match-or-pass-through logic.
+ */
+function replaceErrorsIn(val, args, ctx, session, isMatch) {
+    if (val.kind === RVKind.Array) {
+        let anyMatch = false;
+        for (const row of val.rows) {
+            for (const cell of row) {
+                if (cell.kind === RVKind.Error && isMatch(cell)) {
+                    anyMatch = true;
+                    break;
+                }
+            }
+            if (anyMatch) {
+                break;
+            }
+        }
+        if (!anyMatch) {
+            return val;
+        }
+        const replaceScalar = topLeft(evalDeref(args[1], ctx, session));
+        const rows = [];
+        for (const row of val.rows) {
+            const newRow = [];
+            for (const cell of row) {
+                newRow.push(cell.kind === RVKind.Error && isMatch(cell) ? replaceScalar : cell);
+            }
+            rows.push(newRow);
+        }
+        return rvArray(rows);
+    }
+    return isError(val) && isMatch(val) ? evalDeref(args[1], ctx, session) : val;
+}
+function evaluateIFERROR(args, ctx, session) {
+    if (args.length < 2) {
+        return ERRORS.VALUE;
+    }
+    const val = evalDeref(args[0], ctx, session);
+    return replaceErrorsIn(val, args, ctx, session, () => true);
+}
+function evaluateIFNA(args, ctx, session) {
+    if (args.length < 2) {
+        return ERRORS.VALUE;
+    }
+    const val = evalDeref(args[0], ctx, session);
+    return replaceErrorsIn(val, args, ctx, session, err => err.code === "#N/A");
+}
+function evaluateIFS(args, ctx, session) {
+    if (args.length < 2) {
+        return ERRORS.VALUE;
+    }
+    // Excel requires IFS args to come in test/value pairs. Odd-length
+    // arg lists imply a trailing test with no value and are #N/A.
+    if (args.length % 2 !== 0) {
+        return ERRORS.NA;
+    }
+    for (let i = 0; i < args.length - 1; i += 2) {
+        const cond = topLeft(evalDeref(args[i], ctx, session));
+        if (isError(cond)) {
+            return cond;
+        }
+        const bool = toBooleanRV(cond);
+        if (isError(bool)) {
+            return bool;
+        }
+        if (bool.value) {
+            return evaluate(args[i + 1], ctx, session);
+        }
+    }
+    return ERRORS.NA;
+}
+function evaluateSWITCH(args, ctx, session) {
+    if (args.length < 3) {
+        return ERRORS.VALUE;
+    }
+    const expr = topLeft(evalDeref(args[0], ctx, session));
+    if (isError(expr)) {
+        return expr;
+    }
+    for (let i = 1; i < args.length - 1; i += 2) {
+        const caseVal = topLeft(evalDeref(args[i], ctx, session));
+        if (scalarEquals(expr, caseVal)) {
+            return evaluate(args[i + 1], ctx, session);
+        }
+    }
+    if (args.length % 2 === 0) {
+        return evaluate(args[args.length - 1], ctx, session);
+    }
+    return ERRORS.NA;
+}
+function evaluateCHOOSE(args, ctx, session) {
+    if (args.length < 2) {
+        return ERRORS.VALUE;
+    }
+    const idxVal = topLeft(evalDeref(args[0], ctx, session));
+    if (isError(idxVal)) {
+        return idxVal;
+    }
+    const num = toNumberRV(idxVal);
+    if (isError(num)) {
+        return num;
+    }
+    const idx = Math.floor(num.value);
+    if (idx < 1 || idx >= args.length) {
+        return ERRORS.VALUE;
+    }
+    return evaluate(args[idx], ctx, session);
+}
+function evaluateLET(args, ctx, session) {
+    if (args.length < 3 || args.length % 2 !== 1) {
+        return ERRORS.VALUE;
+    }
+    const prevBindings = ctx.localBindings;
+    const newBindings = new Map(prevBindings);
+    try {
+        const pairCount = (args.length - 1) / 2;
+        for (let i = 0; i < pairCount; i++) {
+            const nameExpr = args[i * 2];
+            const valueExpr = args[i * 2 + 1];
+            if (nameExpr.kind !== BoundExprKind.NameExpr) {
+                return ERRORS.VALUE;
+            }
+            ctx.localBindings = newBindings;
+            const val = evaluate(valueExpr, ctx, session);
+            newBindings.set(nameExpr.upperName, val);
+        }
+        ctx.localBindings = newBindings;
+        return evaluate(args[args.length - 1], ctx, session);
+    }
+    finally {
+        ctx.localBindings = prevBindings;
+    }
+}
+function evaluateLAMBDA(args, ctx) {
+    if (args.length < 1) {
+        return ERRORS.VALUE;
+    }
+    const paramExprs = args.slice(0, -1);
+    const bodyExpr = args[args.length - 1];
+    const params = [];
+    for (const p of paramExprs) {
+        if (p.kind !== BoundExprKind.NameExpr) {
+            return ERRORS.VALUE;
+        }
+        params.push(p.upperName);
+    }
+    return rvLambda(params, bodyExpr, ctx.localBindings ? new Map(ctx.localBindings) : undefined);
+}
+function evaluateINDIRECT(args, ctx, session) {
+    if (args.length < 1) {
+        return ERRORS.VALUE;
+    }
+    const refArg = evalDeref(args[0], ctx, session);
+    const refText = toStringRV(topLeft(refArg));
+    if (!refText) {
+        return ERRORS.REF;
+    }
+    let a1 = true;
+    if (args.length >= 2) {
+        const a1Val = topLeft(evalDeref(args[1], ctx, session));
+        a1 =
+            !(a1Val.kind === RVKind.Boolean && !a1Val.value) &&
+                !(a1Val.kind === RVKind.Number && a1Val.value === 0);
+    }
+    if (!a1) {
+        // R1C1 — delegate to runtime R1C1 parser
+        return resolveR1C1(refText, ctx, session);
+    }
+    // A1 style — parse and bind at runtime
+    try {
+        // Use NUL (U+0000) as the separator so sheet names containing `__`
+        // can't collide with distinct INDIRECT call sites. Neither formula
+        // text nor an Excel sheet name is allowed to contain `\0`, so the
+        // key is unambiguous. (R6-P1-12)
+        const cacheKey = `${ctx.currentSheet}\u0000${refText}`;
+        let bound = session.indirectAstCache.get(cacheKey);
+        if (bound) {
+            // LRU touch: delete-then-set moves the hit entry to the Map's
+            // insertion-order tail so the oldest entry is always `keys().next()`.
+            session.indirectAstCache.delete(cacheKey);
+            session.indirectAstCache.set(cacheKey, bound);
+        }
+        else {
+            const tokens = tokenize(refText);
+            const ast = parse(tokens);
+            const bindCtx = { snapshot: ctx.snapshot, currentSheet: ctx.currentSheet };
+            bound = bind(ast, bindCtx);
+            // Bound the cache so an adversarial formula that generates a fresh
+            // INDIRECT string every call can't grow session memory unbounded.
+            // The cap matches `astCache` in calculate-formulas-impl.ts. (R6
+            // architectural note #6)
+            if (session.indirectAstCache.size >= 10000) {
+                const oldestKey = session.indirectAstCache.keys().next().value;
+                if (oldestKey !== undefined) {
+                    session.indirectAstCache.delete(oldestKey);
+                }
+            }
+            session.indirectAstCache.set(cacheKey, bound);
+        }
+        return evaluate(bound, ctx, session);
+    }
+    catch {
+        return ERRORS.REF;
+    }
+}
+function evaluateOFFSET(args, ctx, session) {
+    if (args.length < 3) {
+        return ERRORS.VALUE;
+    }
+    const refExpr = args[0];
+    let baseRow;
+    let baseCol;
+    let baseSheet;
+    // Remember the base reference's shape — Excel's OFFSET uses it as the
+    // default height/width when those optional arguments are omitted.
+    let baseHeight;
+    let baseWidth;
+    if (refExpr.kind === BoundExprKind.CellRef) {
+        baseRow = refExpr.row;
+        baseCol = refExpr.col;
+        baseSheet = refExpr.sheet;
+        baseHeight = 1;
+        baseWidth = 1;
+    }
+    else if (refExpr.kind === BoundExprKind.AreaRef) {
+        baseRow = refExpr.top;
+        baseCol = refExpr.left;
+        baseSheet = refExpr.sheet;
+        baseHeight = refExpr.bottom - refExpr.top + 1;
+        baseWidth = refExpr.right - refExpr.left + 1;
+    }
+    else {
+        return ERRORS.VALUE;
+    }
+    const rowsVal = topLeft(evalDeref(args[1], ctx, session));
+    const rowsNum = toNumberRV(rowsVal);
+    if (isError(rowsNum)) {
+        return rowsNum;
+    }
+    const colsVal = topLeft(evalDeref(args[2], ctx, session));
+    const colsNum = toNumberRV(colsVal);
+    if (isError(colsNum)) {
+        return colsNum;
+    }
+    // Excel truncates fractional rows/cols toward zero (not floor). Without
+    // the `Math.trunc`, `OFFSET(A5, -0.7, 0)` would resolve to row 4.3 and
+    // then fail the Map lookup silently, returning BLANK instead of A5.
+    const newRow = baseRow + Math.trunc(rowsNum.value);
+    const newCol = baseCol + Math.trunc(colsNum.value);
+    if (newRow < 1 || newCol < 1 || newRow > 1048576 || newCol > 16384) {
+        return ERRORS.REF;
+    }
+    // Default height / width come from the base reference itself. OFFSET
+    // only shrinks/expands when the caller passes an explicit non-missing
+    // fourth/fifth argument. A `MissingNode` (compile-time "omitted
+    // argument") binds to a `null`-valued literal; we treat that the same
+    // as "no argument provided" so `OFFSET(A1:C3, 0, 0, , )` keeps the
+    // 3-row × 3-col span instead of collapsing to #REF! with `height = 0`.
+    const isOmitted = (a) => a.kind === BoundExprKind.Literal && a.value === null && a.errorCode === undefined;
+    let height = baseHeight;
+    let width = baseWidth;
+    if (args.length > 3 && !isOmitted(args[3])) {
+        const h = toNumberRV(topLeft(evalDeref(args[3], ctx, session)));
+        if (isError(h)) {
+            return h;
+        }
+        height = Math.trunc(h.value);
+        if (height === 0) {
+            return ERRORS.REF;
+        }
+    }
+    if (args.length > 4 && !isOmitted(args[4])) {
+        const w = toNumberRV(topLeft(evalDeref(args[4], ctx, session)));
+        if (isError(w)) {
+            return w;
+        }
+        width = Math.trunc(w.value);
+        if (width === 0) {
+            return ERRORS.REF;
+        }
+    }
+    // Resolve range coordinates — negative height/width extend upward/leftward
+    let top = newRow;
+    let bottom = newRow + height - 1;
+    if (height < 0) {
+        top = newRow + height + 1;
+        bottom = newRow;
+    }
+    let left = newCol;
+    let right = newCol + width - 1;
+    if (width < 0) {
+        left = newCol + width + 1;
+        right = newCol;
+    }
+    if (top < 1 || left < 1 || bottom > 1048576 || right > 16384) {
+        return ERRORS.REF;
+    }
+    if (top === bottom && left === right) {
+        return getCellValue(baseSheet, top, left, ctx, session);
+    }
+    return buildRangeArray(ctx, session, baseSheet, top, left, bottom, right);
+}
+// ============================================================================
+// Higher-Order Functions
+// ============================================================================
+function evaluateHigherOrder(name, args, ctx, session) {
+    switch (name) {
+        case "MAP":
+            return evaluateMAP(args, ctx, session);
+        case "REDUCE":
+            return evaluateREDUCE(args, ctx, session);
+        case "SCAN":
+            return evaluateSCAN(args, ctx, session);
+        case "MAKEARRAY":
+            return evaluateMAKEARRAY(args, ctx, session);
+        case "BYROW":
+            return evaluateBYROW(args, ctx, session);
+        case "BYCOL":
+            return evaluateBYCOL(args, ctx, session);
+        default:
+            return ERRORS.VALUE;
+    }
+}
+function invokeLambda(lambda, lambdaArgs, ctx, session) {
+    if (lambdaArgs.length !== lambda.params.length) {
+        return ERRORS.VALUE;
+    }
+    if (session.lambdaDepth >= 256) {
+        return ERRORS.NUM;
+    }
+    session.lambdaDepth++;
+    try {
+        const prevBindings = ctx.localBindings;
+        const newBindings = new Map(lambda.closureBindings);
+        for (let i = 0; i < lambda.params.length; i++) {
+            newBindings.set(lambda.params[i], lambdaArgs[i]);
+        }
+        ctx.localBindings = newBindings;
+        try {
+            return dereferenceValue(evaluate(lambda.body, ctx, session), ctx, session);
+        }
+        finally {
+            ctx.localBindings = prevBindings;
+        }
+    }
+    finally {
+        session.lambdaDepth--;
+    }
+}
+function evaluateMAP(args, ctx, session) {
+    if (args.length < 2) {
+        return ERRORS.VALUE;
+    }
+    const arrVal = evalDeref(args[0], ctx, session);
+    const lambdaVal = evalDeref(args[args.length - 1], ctx, session);
+    if (!isLambda(lambdaVal)) {
+        return ERRORS.VALUE;
+    }
+    if (arrVal.kind !== RVKind.Array) {
+        return invokeLambda(lambdaVal, [arrVal], ctx, session);
+    }
+    const rows = [];
+    for (const row of arrVal.rows) {
+        const outRow = [];
+        for (const cell of row) {
+            outRow.push(topLeft(invokeLambda(lambdaVal, [cell], ctx, session)));
+        }
+        rows.push(outRow);
+    }
+    return rvArray(rows);
+}
+function evaluateREDUCE(args, ctx, session) {
+    if (args.length < 3) {
+        return ERRORS.VALUE;
+    }
+    let acc = evalDeref(args[0], ctx, session);
+    const arrVal = evalDeref(args[1], ctx, session);
+    const lambdaVal = evalDeref(args[2], ctx, session);
+    if (!isLambda(lambdaVal)) {
+        return ERRORS.VALUE;
+    }
+    if (arrVal.kind === RVKind.Array) {
+        for (const row of arrVal.rows) {
+            for (const cell of row) {
+                acc = invokeLambda(lambdaVal, [topLeft(acc), cell], ctx, session);
+            }
+        }
+    }
+    else {
+        // Scalar input: Excel treats the scalar as a 1×1 array and invokes the
+        // reducer exactly once. Previously we returned `init` unchanged, which
+        // silently broke `REDUCE(0, some_scalar, lambda)` callers.
+        acc = invokeLambda(lambdaVal, [topLeft(acc), topLeft(arrVal)], ctx, session);
+    }
+    return acc;
+}
+function evaluateSCAN(args, ctx, session) {
+    if (args.length < 3) {
+        return ERRORS.VALUE;
+    }
+    let acc = evalDeref(args[0], ctx, session);
+    const arrVal = evalDeref(args[1], ctx, session);
+    const lambdaVal = evalDeref(args[2], ctx, session);
+    if (!isLambda(lambdaVal)) {
+        return ERRORS.VALUE;
+    }
+    const rows = [];
+    if (arrVal.kind === RVKind.Array) {
+        for (const row of arrVal.rows) {
+            const outRow = [];
+            for (const cell of row) {
+                acc = invokeLambda(lambdaVal, [topLeft(acc), cell], ctx, session);
+                outRow.push(topLeft(acc));
+            }
+            rows.push(outRow);
+        }
+        return rows.length > 0 ? rvArray(rows) : ERRORS.CALC;
+    }
+    // Scalar input: emit a single-cell array containing the one accumulated
+    // value. Previously we returned #CALC! here, which was an artefact of the
+    // array-only implementation path.
+    const result = invokeLambda(lambdaVal, [topLeft(acc), topLeft(arrVal)], ctx, session);
+    return rvArray([[topLeft(result)]]);
+}
+function evaluateMAKEARRAY(args, ctx, session) {
+    if (args.length < 3) {
+        return ERRORS.VALUE;
+    }
+    const rowsNum = toNumberRV(topLeft(evalDeref(args[0], ctx, session)));
+    if (isError(rowsNum)) {
+        return rowsNum;
+    }
+    const colsNum = toNumberRV(topLeft(evalDeref(args[1], ctx, session)));
+    if (isError(colsNum)) {
+        return colsNum;
+    }
+    const lambdaVal = evalDeref(args[2], ctx, session);
+    if (!isLambda(lambdaVal)) {
+        return ERRORS.VALUE;
+    }
+    // Truncate toward zero and reject non-positive / overflow sizes.
+    // Without the cell-count cap the engine can silently allocate billions
+    // of scalars before blowing the heap; matching the broadcast limit
+    // keeps MAKEARRAY in line with the rest of the array pipeline.
+    const rCount = Math.trunc(rowsNum.value);
+    const cCount = Math.trunc(colsNum.value);
+    if (rCount < 1 || cCount < 1) {
+        return ERRORS.VALUE;
+    }
+    if (rCount * cCount > 10000000) {
+        return ERRORS.NUM;
+    }
+    const rows = [];
+    for (let r = 1; r <= rCount; r++) {
+        const outRow = [];
+        for (let c = 1; c <= cCount; c++) {
+            outRow.push(topLeft(invokeLambda(lambdaVal, [rvNumber(r), rvNumber(c)], ctx, session)));
+        }
+        rows.push(outRow);
+    }
+    return rvArray(rows);
+}
+function evaluateBYROW(args, ctx, session) {
+    if (args.length < 2) {
+        return ERRORS.VALUE;
+    }
+    const arrVal = evalDeref(args[0], ctx, session);
+    const lambdaVal = evalDeref(args[1], ctx, session);
+    if (!isLambda(lambdaVal)) {
+        return ERRORS.VALUE;
+    }
+    if (arrVal.kind !== RVKind.Array) {
+        return invokeLambda(lambdaVal, [rvArray([[topLeft(arrVal)]])], ctx, session);
+    }
+    const rows = [];
+    for (const row of arrVal.rows) {
+        const rowArr = rvArray([row.map(c => c)]);
+        rows.push([topLeft(invokeLambda(lambdaVal, [rowArr], ctx, session))]);
+    }
+    return rvArray(rows);
+}
+function evaluateBYCOL(args, ctx, session) {
+    if (args.length < 2) {
+        return ERRORS.VALUE;
+    }
+    const arrVal = evalDeref(args[0], ctx, session);
+    const lambdaVal = evalDeref(args[1], ctx, session);
+    if (!isLambda(lambdaVal)) {
+        return ERRORS.VALUE;
+    }
+    if (arrVal.kind !== RVKind.Array) {
+        return invokeLambda(lambdaVal, [rvArray([[topLeft(arrVal)]])], ctx, session);
+    }
+    const numCols = arrVal.width;
+    const outRow = [];
+    for (let c = 0; c < numCols; c++) {
+        const colArr = rvArray(arrVal.rows.map(row => [row[c]]));
+        outRow.push(topLeft(invokeLambda(lambdaVal, [colArr], ctx, session)));
+    }
+    return rvArray([outRow]);
+}
+// ============================================================================
+// Reference Functions (ROW, COLUMN, ROWS, COLUMNS)
+// ============================================================================
+/** Whether `name` is one of the four "inspect a reference's geometry" builtins. */
+function isSimpleRefFunction(name) {
+    return name === "ROW" || name === "COLUMN" || name === "ROWS" || name === "COLUMNS";
+}
+function tryEvaluateRefFunction(name, args, ctx) {
+    switch (name) {
+        case "ROW":
+            if (args.length === 0) {
+                return ctx.currentAddress ? rvNumber(ctx.currentAddress.row) : ERRORS.VALUE;
+            }
+            if (args[0].kind === BoundExprKind.CellRef) {
+                return rvNumber(args[0].row);
+            }
+            if (args[0].kind === BoundExprKind.AreaRef) {
+                return rvNumber(args[0].top);
+            }
+            return undefined;
+        case "COLUMN":
+            if (args.length === 0) {
+                return ctx.currentAddress ? rvNumber(ctx.currentAddress.col) : ERRORS.VALUE;
+            }
+            if (args[0].kind === BoundExprKind.CellRef) {
+                return rvNumber(args[0].col);
+            }
+            if (args[0].kind === BoundExprKind.AreaRef) {
+                return rvNumber(args[0].left);
+            }
+            return undefined;
+        case "ROWS":
+            if (args.length > 0 && args[0].kind === BoundExprKind.AreaRef) {
+                return rvNumber(args[0].bottom - args[0].top + 1);
+            }
+            if (args.length > 0 && args[0].kind === BoundExprKind.CellRef) {
+                return rvNumber(1);
+            }
+            return undefined;
+        case "COLUMNS":
+            if (args.length > 0 && args[0].kind === BoundExprKind.AreaRef) {
+                return rvNumber(args[0].right - args[0].left + 1);
+            }
+            if (args.length > 0 && args[0].kind === BoundExprKind.CellRef) {
+                return rvNumber(1);
+            }
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+// ============================================================================
+// Reference-aware: ISREF
+// ============================================================================
+/**
+ * ISREF(value) → TRUE if `value` is a reference; FALSE otherwise.
+ *
+ * Excel's rule is syntactic + runtime: any `CellRef` / `AreaRef` / 3-D ref /
+ * `ColRangeRef` / `RowRangeRef` is a reference, and any call that *produces*
+ * a `ReferenceValue` (INDIRECT, OFFSET) is also a reference. Errors in the
+ * sub-expression are suppressed (Excel returns FALSE for `ISREF(INDIRECT("xx"))`
+ * where INDIRECT returns `#REF!`).
+ */
+function evaluateISREF(args, ctx, session) {
+    if (args.length !== 1) {
+        return ERRORS.VALUE;
+    }
+    const arg = args[0];
+    // Purely syntactic reference forms — always TRUE without evaluating.
+    if (arg.kind === BoundExprKind.CellRef ||
+        arg.kind === BoundExprKind.AreaRef ||
+        arg.kind === BoundExprKind.ColRangeRef ||
+        arg.kind === BoundExprKind.RowRangeRef ||
+        arg.kind === BoundExprKind.Ref3D) {
+        return rvBoolean(true);
+    }
+    // Otherwise evaluate without dereferencing. INDIRECT/OFFSET yield a
+    // ReferenceValue when successful; anything else (error, scalar, array)
+    // is not a reference. Per Excel, ISREF suppresses errors to FALSE.
+    const raw = evaluate(arg, ctx, session);
+    return rvBoolean(raw.kind === RVKind.Reference);
+}
+// ============================================================================
+// Reference-aware: CELL
+// ============================================================================
+/**
+ * Resolve a CELL(..., ref) argument to a concrete {sheet,row,col} triple.
+ * CELL always inspects the *top-left* cell of the referenced area.
+ * Returns an error value if the argument cannot be resolved to a reference.
+ */
+function resolveCellRefArg(arg, ctx, session) {
+    // Syntactic reference forms — extract top-left directly.
+    if (arg.kind === BoundExprKind.CellRef) {
+        return { sheet: arg.sheet, row: arg.row, col: arg.col };
+    }
+    if (arg.kind === BoundExprKind.AreaRef) {
+        return { sheet: arg.sheet, row: arg.top, col: arg.left };
+    }
+    if (arg.kind === BoundExprKind.ColRangeRef) {
+        const ws = ctx.snapshot.worksheetsByName.get(arg.sheet.toLowerCase());
+        const top = ws?.dimensions?.top ?? 1;
+        return { sheet: arg.sheet, row: top, col: arg.leftCol };
+    }
+    if (arg.kind === BoundExprKind.RowRangeRef) {
+        const ws = ctx.snapshot.worksheetsByName.get(arg.sheet.toLowerCase());
+        const left = ws?.dimensions?.left ?? 1;
+        return { sheet: arg.sheet, row: arg.topRow, col: left };
+    }
+    if (arg.kind === BoundExprKind.Ref3D) {
+        const first = arg.sheets[0];
+        if (first === undefined) {
+            return ERRORS.VALUE;
+        }
+        if (arg.inner.kind === BoundExprKind.CellRef) {
+            return { sheet: first, row: arg.inner.row, col: arg.inner.col };
+        }
+        return { sheet: first, row: arg.inner.top, col: arg.inner.left };
+    }
+    // Fall back to evaluating — INDIRECT/OFFSET etc. may produce a ReferenceValue.
+    const raw = evaluate(arg, ctx, session);
+    if (raw.kind === RVKind.Error) {
+        return raw;
+    }
+    if (raw.kind === RVKind.Reference && raw.areas.length > 0) {
+        const area = raw.areas[0];
+        return { sheet: area.sheet, row: area.top, col: area.left };
+    }
+    // Non-reference argument — Excel returns #VALUE! for CELL.
+    return ERRORS.VALUE;
+}
+/** Convert a 1-based column number to its letter form (1 → "A", 27 → "AA"). */
+function colNumberToLetter(colNum) {
+    let col = "";
+    let cv = colNum;
+    while (cv > 0) {
+        cv--;
+        col = String.fromCharCode(65 + (cv % 26)) + col;
+        cv = Math.floor(cv / 26);
+    }
+    return col;
+}
+/**
+ * CELL(info_type, [reference]) — limited, workbook-internal subset.
+ *
+ * Supported info types:
+ * - `"address"`   → "$A$1"-style absolute reference (no sheet name)
+ * - `"row"`       → 1-based row number of the top-left cell
+ * - `"col"`       → 1-based column number of the top-left cell
+ * - `"contents"`  → value of the top-left cell
+ * - `"type"`      → "b" (blank), "l" (label/text), "v" (value/other)
+ * - `"width"`     → 8 (column width is not tracked in the snapshot)
+ * - `"filename"`  → "" (no file path available)
+ *
+ * Any other info type yields `#N/A`, matching Excel's treatment of
+ * workbook-state-dependent info in contexts where the data is unavailable.
+ *
+ * When `reference` is omitted, the current formula's own cell is used —
+ * if that cannot be determined, `#VALUE!` is returned.
+ */
+function evaluateCELL(args, ctx, session) {
+    if (args.length < 1 || args.length > 2) {
+        return ERRORS.VALUE;
+    }
+    // Resolve info_type — this is a plain string expression, evaluate normally.
+    const infoRV = dereferenceValue(evaluate(args[0], ctx, session), ctx, session);
+    if (infoRV.kind === RVKind.Error) {
+        return infoRV;
+    }
+    const infoScalar = topLeft(infoRV);
+    if (infoScalar.kind === RVKind.Error) {
+        return infoScalar;
+    }
+    if (infoScalar.kind !== RVKind.String) {
+        return ERRORS.VALUE;
+    }
+    const info = infoScalar.value.toLowerCase();
+    // Resolve reference: explicit arg, or the current formula cell.
+    let target;
+    if (args.length === 2) {
+        const resolved = resolveCellRefArg(args[1], ctx, session);
+        if ("kind" in resolved) {
+            return resolved;
+        }
+        target = resolved;
+    }
+    else {
+        if (!ctx.currentAddress) {
+            return ERRORS.VALUE;
+        }
+        target = {
+            sheet: ctx.currentSheet,
+            row: ctx.currentAddress.row,
+            col: ctx.currentAddress.col
+        };
+    }
+    switch (info) {
+        case "address": {
+            return rvString(`$${colNumberToLetter(target.col)}$${target.row}`);
+        }
+        case "row":
+            return rvNumber(target.row);
+        case "col":
+        case "column":
+            return rvNumber(target.col);
+        case "contents": {
+            return getCellValue(target.sheet, target.row, target.col, ctx, session);
+        }
+        case "type": {
+            const val = getCellValue(target.sheet, target.row, target.col, ctx, session);
+            if (val.kind === RVKind.Blank) {
+                return rvString("b");
+            }
+            if (val.kind === RVKind.String) {
+                return rvString("l");
+            }
+            // Numbers, booleans, errors — all classified as "value".
+            return rvString("v");
+        }
+        case "width":
+            // Column width is not captured in the snapshot — return Excel's default.
+            return rvNumber(8);
+        case "filename":
+            // No file path is available to the calculation engine.
+            return rvString("");
+        default:
+            return ERRORS.NA;
+    }
+}
+// ============================================================================
+// Name Expression
+// ============================================================================
+function evaluateNameExpr(expr, ctx, session) {
+    // Check local bindings first (LET variables)
+    if (ctx.localBindings?.has(expr.upperName)) {
+        return ctx.localBindings.get(expr.upperName);
+    }
+    // Try snapshot defined name resolution (for formula-based names).
+    // Respects scope precedence: sheet-local > workbook-global.
+    const dn = resolveDefinedNameFromSnapshot(ctx.snapshot.definedNames, expr.name, ctx.currentSheet);
+    if (dn && dn.ranges.length > 0) {
+        if (dn.ranges.length > 1) {
+            return ERRORS.VALUE;
+        }
+        const rangeStr = dn.ranges[0];
+        const parsed = parseDefinedNameRange(rangeStr);
+        if (parsed) {
+            if (parsed.startRow === parsed.endRow && parsed.startCol === parsed.endCol) {
+                return getCellValue(parsed.sheet, parsed.startRow, parsed.startCol, ctx, session);
+            }
+            return buildRangeArray(ctx, session, parsed.sheet, Math.min(parsed.startRow, parsed.endRow), Math.min(parsed.startCol, parsed.endCol), Math.max(parsed.startRow, parsed.endRow), Math.max(parsed.startCol, parsed.endCol));
+        }
+        // Formula expression — parse and evaluate via shared helper
+        const nameResult = evaluateFormulaName(expr.upperName, rangeStr, ctx, session);
+        return nameResult ?? ERRORS.NAME;
+    }
+    return ERRORS.NAME;
+}
+// ============================================================================
+// Formula-based Defined Name Evaluation (shared helper)
+// ============================================================================
+/**
+ * Evaluate a formula-based defined name expression, with caching.
+ * Cache key includes name + sheet + cell address to handle position-dependent
+ * formulas like ROW()/COLUMN().
+ *
+ * Returns the evaluated result, or undefined if parsing/evaluation fails.
+ */
+function evaluateFormulaName(upperName, formulaExpr, ctx, session) {
+    const addr = ctx.currentAddress;
+    const cacheKey = addr
+        ? `__NAME__${upperName}__${ctx.currentSheet}__${addr.row}:${addr.col}`
+        : `__NAME__${upperName}__${ctx.currentSheet}`;
+    const cached = session.nameCache.get(cacheKey);
+    if (cached !== undefined) {
+        return cached;
+    }
+    // Guard against recursion through a defined name that references itself.
+    // Uses a dedicated prefix so it cannot collide with formula-cell guard keys.
+    const guardKey = `__NAMEEVAL__${upperName}`;
+    if (session.evaluating.has(guardKey)) {
+        return ERRORS.CALC;
+    }
+    session.evaluating.add(guardKey);
+    try {
+        const tokens = tokenize(formulaExpr);
+        const ast = parse(tokens);
+        const bindCtx = { snapshot: ctx.snapshot, currentSheet: ctx.currentSheet };
+        const bound = bind(ast, bindCtx);
+        const result = evaluate(bound, ctx, session);
+        session.nameCache.set(cacheKey, result);
+        return result;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        session.evaluating.delete(guardKey);
+    }
+}
+// ============================================================================
+// Lambda Expression
+// ============================================================================
+function evaluateLambdaExpr(expr, ctx) {
+    return rvLambda([...expr.params], expr.body, ctx.localBindings ? new Map(ctx.localBindings) : undefined);
+}
+// ============================================================================
+// Structured Reference (runtime resolution)
+// ============================================================================
+function evaluateStructuredRef(expr, ctx, session) {
+    const snapshot = ctx.snapshot;
+    const addr = ctx.currentAddress;
+    // Find the table
+    let tableName = expr.tableName;
+    let tableSheet = null;
+    let tableInfo = null;
+    if (tableName === "") {
+        // Implicit table — find the table containing the current cell
+        if (!addr) {
+            return ERRORS.REF;
+        }
+        // Sheet names are case-insensitive in Excel. Comparing the literal
+        // `ws.name !== addr.sheet` would miss tables when the formula-cell's
+        // address records its sheet in a different case than the workbook's
+        // canonical name (possible after rename / import flows).
+        const addrSheetLower = addr.sheet.toLowerCase();
+        for (const ws of snapshot.worksheets) {
+            if (ws.name.toLowerCase() !== addrSheetLower) {
+                continue;
+            }
+            for (const t of ws.tables) {
+                const g = buildTableGeometry(t);
+                const width = t.columns.length;
+                if (addr.row >= g.dataRowStart &&
+                    addr.row <= g.dataRowEnd &&
+                    addr.col >= t.topLeft.col &&
+                    addr.col < t.topLeft.col + width) {
+                    tableInfo = t;
+                    tableSheet = ws.name;
+                    tableName = t.name;
+                    break;
+                }
+            }
+            if (tableInfo) {
+                break;
+            }
+        }
+    }
+    else {
+        // Named table — use the pre-built index for O(1) lookup
+        const resolved = snapshot.tablesByName.get(tableName.toLowerCase());
+        if (resolved) {
+            tableInfo = resolved.table;
+            tableSheet = resolved.sheetName;
+        }
+    }
+    if (!tableInfo || !tableSheet) {
+        return ERRORS.REF;
+    }
+    const geo = buildTableGeometry(tableInfo);
+    // Strict column resolution — unknown column names surface as #REF!
+    const colRange = resolveStructuredRefColumns(expr.columns, tableInfo, "strict");
+    if (colRange === "error") {
+        return ERRORS.REF;
+    }
+    const rowRange = resolveStructuredRefRows(expr.specials, geo);
+    let rowTop;
+    let rowBottom;
+    if (rowRange === "error") {
+        return ERRORS.REF;
+    }
+    else if (rowRange === "thisRow") {
+        if (addr) {
+            rowTop = addr.row;
+            rowBottom = addr.row;
+        }
+        else {
+            return ERRORS.VALUE;
+        }
+    }
+    else {
+        rowTop = rowRange.rowTop;
+        rowBottom = rowRange.rowBottom;
+    }
+    // Single cell — return as single-cell ReferenceValue
+    if (rowTop === rowBottom && colRange.colLeft === colRange.colRight) {
+        return rvCellRef(tableSheet, rowTop, colRange.colLeft);
+    }
+    // Range — return as area ReferenceValue
+    return rvRef(tableSheet, rowTop, colRange.colLeft, rowBottom, colRange.colRight);
+}
+// ============================================================================
+// Array Literal
+// ============================================================================
+function evaluateArrayLiteral(expr, ctx, session) {
+    const rows = [];
+    for (const row of expr.rows) {
+        const evalRow = [];
+        for (const elem of row) {
+            evalRow.push(topLeft(evalDeref(elem, ctx, session)));
+        }
+        rows.push(evalRow);
+    }
+    return rvArray(rows);
+}
+// ============================================================================
+// Implicit Intersection
+// ============================================================================
+export function implicitIntersect(val, ctx) {
+    if (isScalar(val)) {
+        return val;
+    }
+    if (val.kind === RVKind.Lambda) {
+        return val;
+    }
+    if (val.kind === RVKind.Reference) {
+        // Implicit intersection on a reference: resolve using formula cell's row/col
+        if (val.areas.length === 0) {
+            return BLANK;
+        }
+        const area = val.areas[0];
+        const isSingleCell = area.top === area.bottom && area.left === area.right;
+        if (isSingleCell) {
+            return val; // Single cell ref — keep as-is, will be dereferenced at use site
+        }
+        // Multi-cell reference — apply implicit intersection
+        const addr = ctx.currentAddress;
+        if (!addr) {
+            return val;
+        }
+        // Single column — pick row
+        if (area.left === area.right && addr.row >= area.top && addr.row <= area.bottom) {
+            return rvCellRef(area.sheet, addr.row, area.left);
+        }
+        // Single row — pick column
+        if (area.top === area.bottom && addr.col >= area.left && addr.col <= area.right) {
+            return rvCellRef(area.sheet, area.top, addr.col);
+        }
+        // Both row and col
+        if (addr.row >= area.top &&
+            addr.row <= area.bottom &&
+            addr.col >= area.left &&
+            addr.col <= area.right) {
+            return rvCellRef(area.sheet, addr.row, addr.col);
+        }
+        return val;
+    }
+    if (val.kind !== RVKind.Array) {
+        return val;
+    }
+    const arr = val;
+    if (arr.height === 0 || arr.width === 0) {
+        return BLANK;
+    }
+    if (arr.height === 1 && arr.width === 1) {
+        return arr.rows[0][0];
+    }
+    const addr = ctx.currentAddress;
+    if (!addr) {
+        return arr.rows[0][0];
+    }
+    // Single row — pick column by offset
+    if (arr.height === 1) {
+        if (arr.originCol !== undefined) {
+            const colIdx = addr.col - arr.originCol;
+            if (colIdx >= 0 && colIdx < arr.width) {
+                return arr.rows[0][colIdx];
+            }
+        }
+        return arr.rows[0][0];
+    }
+    // Single column — pick row by offset
+    if (arr.width === 1) {
+        if (arr.originRow !== undefined) {
+            const rowIdx = addr.row - arr.originRow;
+            if (rowIdx >= 0 && rowIdx < arr.height) {
+                return arr.rows[rowIdx][0];
+            }
+        }
+        return arr.rows[0][0];
+    }
+    // Multi-row, multi-column
+    if (arr.originRow !== undefined && arr.originCol !== undefined) {
+        const rowIdx = addr.row - arr.originRow;
+        const colIdx = addr.col - arr.originCol;
+        if (rowIdx >= 0 && rowIdx < arr.height && colIdx >= 0 && colIdx < arr.width) {
+            return arr.rows[rowIdx][colIdx];
+        }
+    }
+    return arr.rows[0][0];
+}
+// ============================================================================
+// R1C1 Reference Resolution
+// ============================================================================
+function resolveR1C1(refText, ctx, session) {
+    const upper = refText.toUpperCase().trim();
+    // Check for range separator
+    let depth = 0;
+    let sepIdx = -1;
+    for (let i = 0; i < upper.length; i++) {
+        if (upper[i] === "[") {
+            depth++;
+        }
+        else if (upper[i] === "]") {
+            depth--;
+        }
+        else if (upper[i] === ":" && depth === 0) {
+            sepIdx = i;
+            break;
+        }
+    }
+    if (sepIdx !== -1) {
+        const s = parseR1C1Single(upper.slice(0, sepIdx), ctx);
+        const e = parseR1C1Single(upper.slice(sepIdx + 1), ctx);
+        if (!s || !e) {
+            return ERRORS.REF;
+        }
+        const top = Math.min(s.row, e.row);
+        const bottom = Math.max(s.row, e.row);
+        const left = Math.min(s.col, e.col);
+        const right = Math.max(s.col, e.col);
+        return rvRef(ctx.currentSheet, top, left, bottom, right);
+    }
+    const ref = parseR1C1Single(upper, ctx);
+    if (!ref || ref.row < 1 || ref.col < 1) {
+        return ERRORS.REF;
+    }
+    return rvCellRef(ctx.currentSheet, ref.row, ref.col);
+}
+function parseR1C1Single(text, ctx) {
+    const re = /^R(\[(-?\d+)\]|(\d+))C(\[(-?\d+)\]|(\d+))$/;
+    const m = re.exec(text);
+    if (!m) {
+        return null;
+    }
+    const addr = ctx.currentAddress;
+    const row = m[2] !== undefined ? (addr?.row ?? 1) + parseInt(m[2], 10) : parseInt(m[3], 10);
+    const col = m[5] !== undefined ? (addr?.col ?? 1) + parseInt(m[5], 10) : parseInt(m[6], 10);
+    return { row, col };
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Evaluate a BoundExpr and dereference any resulting ReferenceValue.
+ * Use this whenever a concrete (non-reference) value is needed.
+ */
+function evalDeref(expr, ctx, session) {
+    return dereferenceValue(evaluate(expr, ctx, session), ctx, session);
+}
+function resolveLambdaName(name, args, ctx, session) {
+    // Check local bindings
+    if (ctx.localBindings?.has(name)) {
+        const val = ctx.localBindings.get(name);
+        if (isLambda(val)) {
+            return invokeLambda(val, args, ctx, session);
+        }
+    }
+    // Check defined names that resolve to lambdas (via snapshot, scope-aware)
+    const dn = resolveDefinedNameFromSnapshot(ctx.snapshot.definedNames, name, ctx.currentSheet);
+    if (dn && dn.ranges.length === 1) {
+        const rangeStr = dn.ranges[0];
+        const parsed = parseDefinedNameRange(rangeStr);
+        if (parsed && parsed.startRow === parsed.endRow && parsed.startCol === parsed.endCol) {
+            const cellVal = getCellValue(parsed.sheet, parsed.startRow, parsed.startCol, ctx, session);
+            if (isLambda(cellVal)) {
+                return invokeLambda(cellVal, args, ctx, session);
+            }
+        }
+        // Formula-based name — evaluate via shared helper
+        if (!parsed) {
+            const nameVal = evaluateFormulaName(name.toUpperCase(), rangeStr, ctx, session);
+            if (nameVal !== undefined && isLambda(nameVal)) {
+                return invokeLambda(nameVal, args, ctx, session);
+            }
+        }
+    }
+    return undefined;
+}