@sheetxl/sdk 0.7.27 → 0.7.28-beta.1

package/types/src/calculation/formula/FormulaBlock.d.ts

@@ -0,0 +1,207 @@
+import { FormulaError, IFormulaContext, Scalar, IRange, IFunction } from '@sheetxl/primitives';
+import { ICalculation } from '../ICalculation';
+import { CalcScope } from '../state';
+import { CompiledFormula } from '../compiler';
+import { ASTNode, FunctionNode } from '../compiler/ASTTypes';
+import { NamedReference, StructuredReference, ReferenceCoords, SetReferenceOptions } from '../Types';
+import { LambdaValue } from './LambdaValue';
+import { IFormulaBlock } from './IFormulaBlock';
+/**
+ * Optional resolver callbacks injected by `Calculation` at construction time.
+ *
+ * @remarks
+ * When a callback is absent the corresponding reference type falls back to a
+ * formula error (`#NAME?` for named, `#REF!` for table).  This allows the
+ * formula engine to operate without a full workbook context (e.g. in tests).
+ */
+export interface FormulaBlockResolvers {
+    /**
+     * Resolves a table structured reference to absolute coordinates.
+     *
+     * @param structuredReference Structured reference object.
+     * @param row Formula anchor row (needed for implicit table detection when `tableId` is empty).
+     * @param column Formula anchor column (same as `row`).
+     */
+    getStructureReferenceCoords?(structuredReference: StructuredReference, row: number, column: number, gridId: string | null): IRange.FixableCoords | FormulaError.Known;
+    /**
+     * Resolves a nameId to its shared compiled body — the named formula's virtual-grid
+     * block at (0,0). The caller evaluates / precedent-resolves this body at its own anchor
+     * (Design 3, apply-at-eval). Returns `null` when the name is unresolved.
+     */
+    getNamedFormulaBlock?(nameId: string): IFormulaBlock | null;
+}
+export declare class FormulaBlock implements IFormulaBlock {
+    protected _compiled: CompiledFormula;
+    protected _context: IFormulaContext;
+    protected _calcScope: CalcScope;
+    protected _gridId: string | null;
+    protected _getEntireCoords: () => IRange.Coords;
+    /**
+     * Optional resolver callbacks supplied by `Calculation` (or a test harness).
+     * Used to resolve table and named references to absolute coordinates at runtime.
+     * When `null` both reference types return formula errors.
+     */
+    protected _resolvers: FormulaBlockResolvers | null;
+    constructor(compiled: CompiledFormula, context: IFormulaContext, scope: CalcScope, gridId: string | null, getEntireCoords: () => IRange.Coords, resolvers?: FormulaBlockResolvers | null);
+    /** @inheritdoc IFormulaBlock.getTextAt */
+    getTextAt(row: number, column: number, r1c1?: boolean, formulaTransform?: ICalculation.FormulaTransform, evalIndex?: number, canonical?: boolean): string;
+    /**
+     * The display (non-canonical) locale: separators from the workbook locale (Plane 1) and boolean/
+     * error/specifier literals from the active spreadsheet-language pack (Plane 3). Resolved per call so
+     * a live locale/language switch is reflected without recompiling. Only its `localize*` face is used
+     * on the emit path; the parse callbacks and raw word-lists go unused here.
+     */
+    private _displayLocale;
+    /** @inheritdoc IFormulaBlock.getTokensAt */
+    getTokensAt(row: number, column: number, evalIndex?: number): ICalculation.FormulaToken[];
+    /** @inheritdoc IFormulaBlock.getError */
+    getError(): any;
+    /** @inheritdoc IFormulaBlock.getNamedIds */
+    getNamedIds(): string[];
+    /** @inheritdoc IFormulaBlock.getReferencedSymbolIds */
+    getReferencedSymbolIds(): string[];
+    /** @inheritdoc IFormulaBlock.hasTotals */
+    hasTotals(): boolean;
+    /** @inheritdoc IFormulaBlock.isReferenceOnly */
+    isReferenceOnly(): boolean;
+    /** @inheritdoc IFormulaBlock.isEquals */
+    isEquals(other: IFormulaBlock): boolean;
+    /** @inheritdoc IFormulaBlock.getReferences */
+    getReferences(row: number, column: number): ReferenceCoords[];
+    /** @inheritdoc IFormulaBlock.getReferenceAt */
+    getReferenceAt(row: number, column: number, index: number): ReferenceCoords;
+    /** @inheritdoc IFormulaBlock.setReferenceAt */
+    setReferenceAt(index: number, reference: ReferenceCoords, options?: SetReferenceOptions): this;
+    /** @inheritdoc IFormulaBlock.reanchorReferences */
+    reanchorReferences(scopeFrom: string, force?: boolean): this;
+    /** @inheritdoc IFormulaBlock.replaceSheetReferences */
+    replaceSheetReferences(fromSheetDisplay: string, toSheetDisplay: string): this;
+    /**
+     * Resolves a named reference by evaluating its shared body at the caller's anchor
+     * (Design 3, apply-at-eval). The body value is taken **raw** (no finalize) so a
+     * range / multi-area body survives as a reference for the consuming operator or
+     * function. Cycle-guarded via `calcScope.activeNames` (a plain name re-entering itself
+     * is `#REF!`); `depth` is tracked for the future LAMBDA recursion limit. Scope
+     * (`gridId`/`rowIndex`/`colIndex`) is saved and restored around the descent so the
+     * caller's remaining reference resolution is unaffected; `node` (the owner) is left
+     * intact so the body's cell reads attribute to the outermost caller.
+     */
+    protected _evaluateNamed(namedReference: NamedReference, row: number, column: number): any;
+    /**
+     * Resolves the precedents of a named reference: the named formula's body cells, resolved
+     * at the caller's anchor (apply-at-eval, Step 12). Returned as an array that the caller's
+     * `resolvedPrecedentsAt` **flattens** into its own precedents (static edges) — so a name
+     * contributes its real input cells, not a virtual-cell edge. Cycle-guarded via
+     * `activeNames` (a recursive name contributes no static precedents → eval returns `#REF!`).
+     */
+    protected _resolveNamedPrecedents(named: NamedReference, row: number, column: number): readonly (Readonly<IRange.FixableCoords> | FormulaError.Known)[] | FormulaError.Known;
+    /**
+     * Resolves {@link StructuredReference} to absolute coordinates.
+     *
+     * @remarks
+     * - Delegates to {@link FormulaBlockResolvers.getStructureReferenceCoords}.
+     * - Returns `FormulaError.Name` when no resolver is registered.
+     */
+    protected _resolveStructuredRef(structuredReference: StructuredReference, row: number, column: number, reuse?: IRange.Coords): IRange.FixableCoords | FormulaError.Known;
+    /** @inheritdoc IFormulaBlock.resolvedPrecedentsAt */
+    resolvedPrecedentsAt(row: number, column: number, includeInvalidIntersect?: boolean, verticalAbs?: boolean[], horizontalAbs?: boolean[]): readonly (Readonly<IRange.FixableCoords> | FormulaError.Known)[];
+    /** @inheritdoc IFormulaBlock.evaluateAt */
+    evaluateAt(row: number, column: number, evalIndex?: number): Scalar | Promise<Scalar>;
+    /** @inheritdoc IFormulaBlock.wrapImplicit */
+    wrapImplicit(rowIndex: number, colIndex: number, setSpills: Set<string>): this;
+    /**
+     * Executes one AST node against a register file.
+     *
+     * @param node The node (its inputs' values are already in `regs`).
+     * @param regs The register file — `compiled.evaluations` on the eager path, a private
+     * ACTIVATION copy during a lambda apply (`_evaluateBody`). Extracted from `evaluateAt`'s old
+     * closure so both paths run the identical semantics.
+     * @param row The anchor the formula is being evaluated at (lambda values record it).
+     * @param column The anchor column.
+     */
+    protected _executeNode(node: ASTNode, regs: any[], row: number, column: number): any;
+    /**
+     * Closes a `LAMBDA` node over the current registers — the node's whole evaluation (design §3.3).
+     *
+     * @param frame The lambda-parameter frame in scope at the creation site — `null` at an eager
+     * site, the enclosing activation's frame when a nested lambda is created during an apply
+     * (`LAMBDA(x,LAMBDA(y,x+y))` — the inner value must see `x`).
+     *
+     * @remarks
+     * The registers are SNAPSHOTTED (copied), not shared: a recursive named lambda re-evaluates the
+     * shared named-body block at every level, and only a copy keeps an outer activation's captured
+     * environment intact underneath it. See `LambdaValue`.
+     */
+    protected _createLambdaValue(node: FunctionNode, regs: any[], frame: ReadonlyMap<number, any> | null, row: number, column: number): LambdaValue;
+    /**
+     * The callee verdicts + apply for a `Call` node (design §3.4, §1.1):
+     *
+     * - a lambda value → arity check, bind, evaluate the body;
+     * - a function value (eta `SUM`) → dispatch to the function itself;
+     * - a reference that is not a lambda → `#REF!` (Excel resolved it and failed to CALL it);
+     * - any other value → `#VALUE!` (a failed coercion, same class as `="a"+1`).
+     *
+     * All three error rows are MEASURED (probe-lambda-call.ps1; Excel Online
+     * `FunctionDispatcher.applyOperatorOrFunction` agrees structurally).
+     */
+    protected _applyCallee(callee: any, node: ASTNode, regs: any[]): any;
+    /**
+     * Apply over VALUES — the marshalled-callable twin of {@link _applyCallee}'s lambda branch
+     * (design §4). Reached through {@link LambdaValue.makeCallable} while a CONSUMER's body
+     * (`BYROW`, `REDUCE`, …) is running; the arguments are plain engine values, so binding needs no
+     * argument nodes. `undefined` is the callable's spelling for an unsupplied argument — it binds
+     * the OMITTED sentinel at an OPTIONAL parameter and is `#VALUE!` at a required one, mirroring
+     * the spelled-call rule (§2.6).
+     */
+    _applyValues(callee: LambdaValue, args: readonly any[]): any;
+    /**
+     * Evaluates a lambda's body segment for one application — the deferred half of the carve-out
+     * (design §3.3/§3.4). `this` is the lambda's OWNER block (the body's nodes belong to its
+     * compiled formula).
+     *
+     * @param lambda The value being applied.
+     * @param frame slot → argument value for this activation (already includes any captured
+     * enclosing frame — see `_applyCallee`).
+     *
+     * @remarks
+     * The walker mirrors the eager pipeline exactly: literals and eagerly-resolved references read
+     * from the activation registers (a copy of the creation snapshot), operators and functions
+     * execute through the same `_executeNode`, and a node's result lands in its register before the
+     * parent reads it. Only three things differ from eager evaluation — a bound name may read the
+     * FRAME (a lambda parameter has no register), an unbound name resolves NOW at the creation
+     * anchor (`deferredResolve`), and a nested `LAMBDA` closes over this activation.
+     *
+     * Recursion arrives only via a defined name cycling back through a deferred resolve, and
+     * `depth` is the budget that bounds it. NOTE the engine's eager `IF` makes a terminating
+     * recursion still BURN to the depth limit before unwinding (the un-taken branch is evaluated,
+     * bottoms out at `#NUM!`, and the selector discards it) — correct results at O(limit) cost;
+     * Excel Online avoids the cost with a lazy `Conditional` term. Recorded in the plan.
+     */
+    protected _evaluateBody(lambda: LambdaValue, frame: ReadonlyMap<number, any>): any;
+    /**
+     * Calls a function.
+     *
+     * @param context The context to use.
+     * @param fnName The name of the function to call.
+     * @param args The args to pass to the function.
+     */
+    protected _callFunction(node: FunctionNode, argsValues: any[], argsLength: number): any;
+    /**
+     * The dispatch half of {@link _callFunction} — invoke a RESOLVED function over evaluated
+     * arguments. Split out so eta application (`FunctionValue` — `LET(f,SUM,f(1,2))`) can dispatch
+     * a function it already holds, with no node to resolve or cache on.
+     */
+    protected _dispatchFunction(fn: IFunction, argsValues: any[], argsLength: number): any;
+    /** @inheritdoc IFormulaBlock.finalizeValue */
+    finalizeValue(retValue: any): Scalar | Scalar[];
+    /** @inheritdoc IFormulaBlock.finalizeValueForCell */
+    finalizeValueForCell(retValue: any): Scalar;
+    toString(): string;
+    get [Symbol.toStringTag](): string;
+}
+/**
+ * Similar to AddressUtils.toAbsoluteRange but
+ * does not set the $fixed flags
+ */
+export declare function toSimpleAbsoluteRange(fixable: IRange.FixableCoords, positionRow: number, positionCol: number, reuseRange: IRange.FixableCoords): IRange.Coords;
+//# sourceMappingURL=FormulaBlock.d.ts.map

package/types/src/calculation/formula/IFormulaBlock.d.ts

@@ -0,0 +1,181 @@
+import { IRange, FormulaError } from '@sheetxl/primitives';
+import { ICalculation } from '../ICalculation';
+import { ReferenceCoords, SetReferenceOptions } from '../Types';
+export interface IFormulaBlock {
+    /**
+     * This is the eval used internally by graph.
+     * precedents must be an array of either IRange or Scalar.
+     *
+     * @param row The row of the cell to evaluate.
+     * @param column The column of the cell to evaluate.
+     * @param evalIndex The index of the evaluation to use from the tokens.
+     *
+     * @remarks
+     * The precedents can be passed in as a performance optimization graph caches them as it calculates.
+     */
+    evaluateAt(row: number, column: number, evalIndex?: number): any;
+    /**
+     * Finalizes a raw value from {@link evaluateAt} for RETURN to a caller: collapses a range to
+     * its anchor scalar (implicit intersection) and prepares a spillable range. A multi-area
+     * result (`=(A1:A3,C1:C3)`, or a name whose body is a comma union) stays an **array**, one
+     * finalized area per element, so an API caller receives every area. Applied by the return
+     * sites (`IFormula.evaluate()`, `ICalculation.evaluate()`) — `evaluateAt` itself returns the
+     * raw value so a consumer (e.g. a named reference used by a function) sees the reference intact.
+     *
+     * @see {@link finalizeValueForCell} for the write-to-a-grid variant.
+     */
+    finalizeValue(value: any): any;
+    /**
+     * {@link finalizeValue} plus the one rule that is specific to STORING a result in a single
+     * grid cell: a cell has no representation for a multi-area union, so an array of areas
+     * becomes `#VALUE!`. Applied by the executor when committing to a grid; returning a
+     * multi-area through the API is legal and uses {@link finalizeValue} instead.
+     */
+    finalizeValueForCell(value: any): any;
+    /**
+     * Return the formula as an array of formula token values.
+     *
+     * @param row The row of the cell to evaluate.
+     * @param column The column of the cell to evaluate.
+     * @param evalIndex The index of the evaluation to use from the tokens.
+     * @remarks
+     * These can be used by advanced editors.
+     */
+    getTokensAt(row: number, column: number, evalIndex?: number): ICalculation.FormulaToken[];
+    /**
+     * Return the formula string.
+     *
+     * @param row The row of the cell to evaluate.
+     * @param column The column of the cell to evaluate.
+     * @param r1c1 If 'true' then returns string as r1c1
+     * @param formulaTransform An {@link ICalculation.FormulaTransform} applied structurally to
+     * the compiled AST before imaging (runs once per block; an all-void transform costs no
+     * recompile) — how a format exporter (io-xlsx `LegacyFormula`) applies its dialect spellings.
+     */
+    getTextAt(row: number, column: number, r1c1?: boolean, formulaTransform?: ICalculation.FormulaTransform, evalIndex?: number, 
+    /**
+     * Serialize function names in CANONICAL (English) form — the persistence/internal
+     * representation (files, undo snapshots, re-parses). Default `false` = display form
+     * (localized via the active language pack).
+     */
+    canonical?: boolean): string;
+    /**
+     * Returns a new formula block with the reference at `index` replaced.
+     *
+     * @param index The index of the reference to replace (aligned to {@link getReferences}).
+     * @param reference The new reference — the {@link ReferenceCoords} TYPE carries the shape intent:
+     *   - an {@link IRange.FixableCellCoords} (single cell) collapses an existing range to a lone cell
+     *     (`A1:B2` → `A1`, dropping the `:`);
+     *   - an {@link IRange.FixableCoords} (range, or degenerate 1×1) PRESERVES the existing shape, so a
+     *     single-cell *range* `A1:A1` stays a range (this is what F4 `$`-cycle / handle-resize pass);
+     *   - a {@link NamedReference} replaces a named ref with another named ref;
+     *   - a {@link FormulaError.Ref} injects a `#REF!`; `null` clears.
+     * @param options See {@link SetReferenceOptions}.
+     */
+    setReferenceAt(index: number, reference: ReferenceCoords, options?: SetReferenceOptions): this;
+    /**
+     * Reanchors the formula by updating the precedent at an index with a new reference.
+     *
+     * @param scopeFrom The scope from which to reanchor.
+     * @param force If `true`, forces re-anchoring even if the scope matches the current grid id.
+     * @returns The formula block with updated precedents.
+     *
+     * @remarks
+     * This is used for moving formulas between grids and requires the formula block to be able to update all of its precedents based on the new and old grid ids.
+     * This is required for cut/paste and drag fill between sheets.
+     */
+    reanchorReferences(scopeFrom: string, force?: boolean): this;
+    /**
+     * Replaces all refs explicitly qualified to `fromSheetDisplay` with `toSheetDisplay`.
+     * Unlike reanchorReferences, unqualified refs are left untouched.
+     * Used when moving data cross-sheet so explicit same-sheet refs follow the data.
+     */
+    replaceSheetReferences(fromSheetDisplay: string, toSheetDisplay: string): this;
+    /**
+     * Returns all references used by the formula.
+     * Named references are {@link NamedReference} objects (detect via `'nameId' in ref`);
+     * cell/range references are {@link IRange.FixableCoords}; unresolvable refs are `null`.
+     */
+    getReferences(row: number, column: number): ReferenceCoords[];
+    /**
+     * Returns the reference at `index`, or `null` if out of range.
+     * Convenience single-slot accessor aligned to {@link getReferences}.
+     */
+    getReferenceAt(row: number, column: number, index: number): ReferenceCoords;
+    /**
+     * Returns the absolute ranges that provide data to a formula.
+     *
+     * @param row The row of the formula.
+     * @param column The column of the formula.
+     * @param includeInvalidIntersect If `true` then invalid ranges will be included in the result.
+     * @param verticalAbs If provided the array will be populated with flags if a vertical absolute is detected
+     * @param horizontalAbs If provided the array will be populated with flags if a horizontal absolute is detected
+     *
+     * @remarks
+     * * `[]` if no precedents are present; either because it has no formula or a formula with no inputs.
+     * * Precedents are the logical ranges and may different the inputs into the formula.
+     * * includeInvalidIntersect is required to manage dependencies for invalid intersections in shared formulas.
+     * * Returns as absolute coordinates.
+     */
+    resolvedPrecedentsAt(row: number, column: number, includeInvalidIntersect?: boolean, verticalAbs?: boolean[], horizontalAbs?: boolean[]): readonly (Readonly<IRange.FixableCoords> | FormulaError.Known)[];
+    /**
+     * Wraps the formula in an implicit reference operator if hasSpill returns true and the formula
+     * expects a spill.
+     *
+     * @param rowIndex The row index of the formula.
+     * @param colIndex The column index of the formula.
+     * @param setSpillCells A1 notation for all of the cells that contains spills.
+     *
+     * @remarks
+     * This is used for importing Excel as it doesn't always add '@' for backward compatibility.
+     */
+    wrapImplicit(rowIndex: number, colIndex: number, setSpillCells: Set<string>): this;
+    /**
+     * @see
+     * { @link ICalculation.IFormula.isReferenceOnly }
+     */
+    isReferenceOnly(): boolean;
+    /**
+     * Return an error with the formula.
+     *
+     * @remarks
+     * This is not a value error but that the formula is unable to resolve.
+     */
+    getError(): FormulaError.Parse | null;
+    /**
+     * Returns the distinct stable nameIds of the named references in this formula
+     * (see `collectNamedIds`). Direct only, never descends into a name's body —
+     * transitivity is carried by the dependency graph. Used by `recompileNamed`'s all3D
+     * scan to find the formulas to invalidate when a named formula changes.
+     */
+    getNamedIds(): string[];
+    /**
+     * Returns the distinct stable fake ids of the direct indirect-symbol references in this formula —
+     * named formulas AND tables. Superset of {@link getNamedIds}.
+     *
+     * @remarks
+     * Used to reverse-invalidate dependents when a name/table's resolution changes (add/heal, delete,
+     * rename), matched against `IndirectSymbolProvider.reconcile()`. Catches unresolved (`#NAME?`/
+     * `#REF!`) references that a precedent-range markDirty would miss.
+     */
+    getReferencedSymbolIds(): string[];
+    /**
+     * Whether the formula calls `SUBTOTAL` or `AGGREGATE` anywhere in its tree.
+     *
+     * @remarks
+     * Read straight off the compiled cache — see `CompiledFormula.hasTotals`. What
+     * `IFormulaContext.filterTotals` asks of every formula block overlapping a total's range
+     * argument, so that a nested total can be excluded from the enclosing one.
+     *
+     * A property of the BLOCK, not of a cell within it: every cell of a block shares one AST, so
+     * either all of them call a total function or none do.
+     */
+    hasTotals(): boolean;
+    /**
+     * If the formula is logically equal to another formula.
+     *
+     * @param other The other formula block to compare to.
+     */
+    isEquals(other: IFormulaBlock): boolean;
+}
+//# sourceMappingURL=IFormulaBlock.d.ts.map

package/types/src/calculation/formula/LambdaValue.d.ts

@@ -0,0 +1,166 @@
+import { IFunction } from '@sheetxl/primitives';
+import { ASTNode } from '../compiler/ASTTypes';
+import { CompiledFormula } from '../compiler/Types';
+import { IFormulaBlock } from './IFormulaBlock';
+/**
+ * The plain JS callable `TypedFunction` hands a lambda-typed parameter — apply over VALUES
+ * (design §4). The consumer's body invokes it once per element; errors come back as VALUES
+ * (they embed as members of the output), never as throws.
+ *
+ * `checkArity` is the family's shared verdict input (`BYROW` asks 1, `MAKEARRAY` 2, `MAP` one per
+ * array): a mismatch is `#VALUE!` for the WHOLE call, decided by the consumer before any element
+ * runs. The properties are read STRUCTURALLY by `formulas` bodies, which cannot import this
+ * calculation-private module.
+ */
+export interface LambdaCallable {
+    (...args: any[]): any;
+    /** Marks a marshalled function value. */
+    isLambdaCallable: true;
+    /** Whether the value can be applied with `count` arguments. */
+    checkArity(count: number): boolean;
+    /** Declared parameter count (`-1` when flexible — an eta-reduced function). */
+    paramCount: number;
+}
+/**
+ * One parameter of a {@link LambdaValue}, as the binder declared it.
+ */
+export interface LambdaParam {
+    /** The parameter's binding slot (an index into `CompiledFormula.bindings`). */
+    readonly slot: number;
+    /** The declared spelling — for arity messages and (later) the wizard signature. */
+    readonly name: string;
+    /**
+     * Declared optional (`[b]`). Always `false` until P2.5 lands the `[b]` parse; the apply arity
+     * rule is already written against it.
+     */
+    readonly optional: boolean;
+}
+/**
+ * The engine value a `LAMBDA(…)` node evaluates to — a first-class result that flows through any
+ * untyped slot (design §1).
+ *
+ * @remarks
+ * CALCULATION-PRIVATE, like stable ids: nothing here reaches a public API. The one boundary rule
+ * is the cell's — an unconsumed lambda renders `#CALC!` (`finalizeValue`), and every consumer that
+ * needs a scalar or a location fails to COERCE it with `#VALUE!` (the `isLambda` brand is what the
+ * coercion sites check, the same structural pattern as `isIRange`).
+ *
+ * A lambda closes over its creation context by SNAPSHOT, not by reference: `regs` is a copy of the
+ * creating formula's register file at the moment the `LAMBDA` node evaluated. The copy is what
+ * makes recursion sound — a self-recursive named lambda re-evaluates the SHARED named body block
+ * at every level, clobbering the block's live registers, and only a captured copy keeps an outer
+ * activation's environment intact underneath it.
+ */
+export declare class LambdaValue {
+    /** The declared parameters, in order. */
+    readonly params: readonly LambdaParam[];
+    /** The body subtree (excluded from the eager execution list — design §3.3). */
+    readonly body: ASTNode;
+    /** The block that created this value — apply evaluates the body through it. */
+    readonly owner: IFormulaBlock;
+    /** The owner's compiled formula (for `bindings` and node prefills). */
+    readonly compiled: CompiledFormula;
+    /** SNAPSHOT of the owner's register file at creation (see the class remarks). */
+    readonly regs: any[];
+    /**
+     * The lambda-parameter frame in scope at creation — slot → value. `null` at an eager creation
+     * site; a nested `LAMBDA` created during an apply captures the enclosing activation's frame,
+     * which is what makes `LAMBDA(x,LAMBDA(y,x+y))(1)(2)` see `x`.
+     */
+    readonly frame: ReadonlyMap<number, any> | null;
+    /** The anchor the owner was being evaluated at — deferred name resolution re-uses it. */
+    readonly anchorRow: number;
+    readonly anchorCol: number;
+    /**
+     * The function-value brand, shared with {@link FunctionValue} — checked structurally by the
+     * coercion sites (`coerceScalar`, `addCoercedValue`, the operators), which cannot import this
+     * calculation-private module.
+     */
+    readonly isLambda: true;
+    constructor(
+    /** The declared parameters, in order. */
+    params: readonly LambdaParam[], 
+    /** The body subtree (excluded from the eager execution list — design §3.3). */
+    body: ASTNode, 
+    /** The block that created this value — apply evaluates the body through it. */
+    owner: IFormulaBlock, 
+    /** The owner's compiled formula (for `bindings` and node prefills). */
+    compiled: CompiledFormula, 
+    /** SNAPSHOT of the owner's register file at creation (see the class remarks). */
+    regs: any[], 
+    /**
+     * The lambda-parameter frame in scope at creation — slot → value. `null` at an eager creation
+     * site; a nested `LAMBDA` created during an apply captures the enclosing activation's frame,
+     * which is what makes `LAMBDA(x,LAMBDA(y,x+y))(1)(2)` see `x`.
+     */
+    frame: ReadonlyMap<number, any> | null, 
+    /** The anchor the owner was being evaluated at — deferred name resolution re-uses it. */
+    anchorRow: number, anchorCol: number);
+    /**
+     * Marshals this value into a {@link LambdaCallable} — how a lambda-typed parameter receives it
+     * (`TypedFunction`, design §4). The callable applies through the OWNER block's value-apply,
+     * which shares `_evaluateBody` (and the recursion budget) with the spelled `Call` path.
+     */
+    makeCallable(): LambdaCallable;
+    get [Symbol.toStringTag](): string;
+}
+/**
+ * An eta-reduced function reference — `SUM` in `BYROW(r,SUM)`, on disk `_xleta.SUM` — the value a
+ * bare built-in (or UDF) name resolves to (design §1, the bare-name NODE half).
+ *
+ * @remarks
+ * Shares the `isLambda` brand: both are function values, and every non-callee consumer treats them
+ * identically (cell → `#CALC!`, coercion → `#VALUE!`). Apply dispatches to the function itself.
+ */
+export declare class FunctionValue {
+    /** The referenced function. */
+    readonly fn: IFunction;
+    /** @see LambdaValue.isLambda */
+    readonly isLambda: true;
+    constructor(
+    /** The referenced function. */
+    fn: IFunction);
+    /**
+     * @see LambdaValue.makeCallable
+     *
+     * Eta dispatch — `BYROW(r,SUM)`: the function's own marshalling owns arity and coercion, so
+     * `checkArity` defers (`SCAN(0,r,BYROW)` fails inside the dispatch, not before it) and a thrown
+     * arity/coercion error comes back as a value, embedding per element like any other result.
+     */
+    makeCallable(): LambdaCallable;
+    get [Symbol.toStringTag](): string;
+}
+/**
+ * The sentinel apply binds for an absent or explicitly-skipped OPTIONAL parameter (design §3.5).
+ *
+ * @remarks
+ * `ISOMITTED(x)` answers TRUE for it and FALSE for everything else; EVERY other consumer reads it
+ * as BLANK. The sentinel never escapes a frame: reads coerce it to blank at the use site
+ * (`readFrameValue`), except in the argument slot of `ISOMITTED` itself. Unreachable until P2.5
+ * lands the `[b]` optional-parameter parse — no declaration can mark a parameter optional yet.
+ */
+export declare const OMITTED: unique symbol;
+/**
+ * A frame read, with the OMITTED → blank rule applied — the single place the sentinel is allowed
+ * to convert, so it cannot leak (plan risk 2).
+ */
+export declare const readFrameValue: (value: any) => any;
+/**
+ * The recursion budget apply enforces via `CalcScope.depth`.
+ *
+ * @remarks
+ * Excel Online configures `maxLambdaDepth: 1000` (plus a tail-call carve-out we do not implement
+ * and a separate `maxLambdaCalls: 10000`). DESKTOP measured (probe-lambda-eval block A,
+ * 2026-08-21): its cap sits between 5,000 and 100,000, and the error at it IS `#NUM!` — the
+ * error Microsoft's own LAMBDA documentation names for runaway recursion.
+ *
+ * 512 rather than Online's 1000: each apply level costs a dozen JS frames, and past ~1000 levels a
+ * BROWSER stack dies first — not as a catchable `RangeError` at the recursion site, but as
+ * arbitrary near-exhaustion failures deep inside the engine (a regex compile inside the number
+ * parser was the observed one), which inner catch sites convert to `#VALUE!` values. The budget
+ * has to keep the engine comfortably inside every platform's stack; raising it toward the measured
+ * desktop number needs the lazy-`IF` (Conditional) carve-out first, since eager `IF` makes every
+ * terminating recursion burn to this cap before unwinding.
+ */
+export declare const MAX_LAMBDA_DEPTH = 512;
+//# sourceMappingURL=LambdaValue.d.ts.map

package/types/src/calculation/formula/TokenUtils.d.ts

@@ -0,0 +1,26 @@
+import { FormulaError, IRange } from '@sheetxl/primitives';
+import { ISymbolRegistry } from '../symbol';
+import { ICalculation } from '../ICalculation';
+import { CompilerLocale } from '../compiler/CompilerLocale';
+/**
+ * Resolves all stable IDs in a token array to their display names.
+ *
+ * @remarks
+ * `generateFormulaTokens` is called on an AST that has already been through
+ * `linkSymbols`, so symbol-bearing tokens carry stable UUIDs rather than the
+ * names the user typed.  This function post-processes those tokens into
+ * display-safe values so callers do not need to carry the registry.
+ *
+ * When `symbols` is absent (no registry was used at compile time) the tokens
+ * already hold display names and are returned as-is.
+ */
+export declare function resolveTokenSymbols(tokens: ICalculation.FormulaToken[], symbols: ISymbolRegistry | null | undefined, canonical?: boolean): ICalculation.FormulaToken[];
+/**
+ * Token Utils used by FormulaBlock
+ */
+export declare function tokensToString(tokens: ICalculation.FormulaToken[], entireCoords: IRange.Coords, isR1C1?: boolean, rowIndex?: number, colIndex?: number, locale?: CompilerLocale): string;
+export declare function tokensToR1C1(tokens: ICalculation.FormulaToken[], entireCoords: IRange.Coords, locale?: CompilerLocale): string;
+export declare function tokensToA1(tokens: ICalculation.FormulaToken[], entireCoords: IRange.Coords, rowIndex?: number, colIndex?: number, locale?: CompilerLocale): string;
+export declare function tokensToPosition(tokens: ICalculation.FormulaToken[], rowIndex?: number, colIndex?: number): ICalculation.FormulaToken[];
+export declare function referencesToPosition(references: readonly (IRange.FixableCoords | string | FormulaError.Known)[], rowIndex?: number, colIndex?: number): (IRange.FixableCoords | string | FormulaError.Known)[];
+//# sourceMappingURL=TokenUtils.d.ts.map

package/types/src/calculation/formula/index.d.ts

@@ -0,0 +1,4 @@
+export * from './Formula';
+export * from './IFormulaBlock';
+export * from './FormulaBlock';
+//# sourceMappingURL=index.d.ts.map

package/types/src/calculation/functions/Operators.d.ts

@@ -0,0 +1,30 @@
+import { FormulaError, IReferenceRange, IRange, IFormulaContext } from '@sheetxl/primitives';
+export declare const Infix: {
+    '+': (context: IFormulaContext, valueA: any, valueB: any) => number | IRange | FormulaError.Known;
+    '-': (context: IFormulaContext, valueA: any, valueB: any) => number | IRange | FormulaError.Known;
+    '*': (context: IFormulaContext, valueA: any, valueB: any) => number | IRange | FormulaError.Known;
+    '/': (context: IFormulaContext, valueA: any, valueB: any) => number | IRange | FormulaError.Known;
+    '^': (context: IFormulaContext, valueA: any, valueB: any) => number | IRange | FormulaError.Known;
+    ' ': (context: IFormulaContext, valueA: IReferenceRange, valueB: IReferenceRange, reuse?: IRange.Coords) => IReferenceRange | FormulaError.Known;
+    ':': (context: IFormulaContext, valueA: IReferenceRange, valueB: IReferenceRange, reuse?: IRange.Coords) => IReferenceRange | FormulaError.Known;
+    '.:.': (context: IFormulaContext, valueA: IReferenceRange, valueB: IReferenceRange, reuse?: IRange.Coords) => IReferenceRange | FormulaError.Known;
+    '.:': (context: IFormulaContext, valueA: IReferenceRange, valueB: IReferenceRange, reuse?: IRange.Coords) => IReferenceRange | FormulaError.Known;
+    ':.': (context: IFormulaContext, valueA: IReferenceRange, valueB: IReferenceRange, reuse?: IRange.Coords) => IReferenceRange | FormulaError.Known;
+    '&': (context: IFormulaContext, valueA: any, valueB: any) => string | IRange;
+    '=': (context: IFormulaContext, valueA: any, valueB: any) => boolean | IRange;
+    '<>': (context: IFormulaContext, valueA: any, valueB: any) => boolean | IRange;
+    '>': (context: IFormulaContext, valueA: any, valueB: any) => boolean | IRange;
+    '<': (context: IFormulaContext, valueA: any, valueB: any) => boolean | IRange;
+    '>=': (context: IFormulaContext, valueA: any, valueB: any) => boolean | IRange;
+    '<=': (context: IFormulaContext, valueA: any, valueB: any) => boolean | IRange;
+};
+export declare const Prefix: {
+    '-': (context: IFormulaContext, value: any) => any;
+    '+': (context: IFormulaContext, value: any) => any;
+    '@': (context: IFormulaContext, value: any) => any;
+};
+export declare const Postfix: {
+    '%': (context: IFormulaContext, value: any) => any;
+    '#': (context: IFormulaContext, value: any) => IReferenceRange;
+};
+//# sourceMappingURL=Operators.d.ts.map

package/types/src/calculation/functions/index.d.ts

@@ -0,0 +1,2 @@
+export { initializeFunctions } from './initializeFunctions';
+//# sourceMappingURL=index.d.ts.map

package/types/src/calculation/functions/initializeFunctions.d.ts

@@ -0,0 +1,22 @@
+import { IFunction, IFormulaContext } from '@sheetxl/primitives';
+import { Implementations, MinifiedDeclaration, DynamicDescriptors, FunctionProvider } from '@sheetxl/scripting';
+/**
+ * Builds the function map for a calculation: core (open-source) functions, then enterprise
+ * (default-on), then any caller-supplied {@link FunctionProvider}s. Later binders override earlier
+ * ones on name collision, so custom functions win over built-ins.
+ */
+export declare function initializeFunctions(getContext: () => IFormulaContext, providers?: readonly FunctionProvider[]): Map<string, IFunction>;
+/**
+ * Load and bind functions to the mapFunctions.
+ *
+ * @param mapFunctions the map to bind functions to
+ * @param getContext a function to get the current formula context
+ * @param implementations the function module containing the actual implementations
+ * @param declarations the built-in declarations
+ * @param getDynamicDescriptors an optional function to get the dynamic descriptor module
+ * @param defaultCategory the default category to use if not specified in the declaration
+ */
+export declare const bindDeclarations: (mapFunctions: Map<string, IFunction>, getContext: () => IFormulaContext, implementations: Implementations, // TODO make this dynamic
+declarations: MinifiedDeclaration, // TODO make this dynamic
+getDynamicDescriptors?: DynamicDescriptors, defaultCategory?: string) => void;
+//# sourceMappingURL=initializeFunctions.d.ts.map