@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.10

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

@@ -1,68 +1,210 @@
 import { IRange, FormulaError } from '@sheetxl/primitives';
 import { ICalculation } from '../ICalculation';
-import { ReferenceCoords, SetReferenceOptions } from '../Types';
-export interface IFormulaBlock {
+import { ReferenceCoords, SetReferenceOptions, PrecedentTemplate, StructuredReference } from '../Types';
+/**
+ * A compiled formula as data (DESIGN-CALC-SERVICE §8): what the engine vends for a block, and all
+ * the facade needs to image a read view of it for the model (`FormulaRecordView`). Plain data, so
+ * it survives `structuredClone`; the syntax tree never crosses.
+ *
+ * @remarks
+ * The tokens carry stable ids in their values - a sheet's, a name's, a table's - and cell
+ * coordinates relative to the block's top-left, so one record serves every cell of the block. Text
+ * is imaged from them against the reader's own symbol map ({@link FormulaImager}), which is what
+ * makes a held copy rename-proof: nothing in the record names a sheet by its name. The model
+ * never sees one: it holds the view.
+ */
+export interface FormulaRecord {
+    /** The block's tokens, stable ids in their values, references relative to the block's top-left. */
+    readonly tokens: readonly ICalculation.FormulaToken[];
+    /** Set when the text did not parse. */
+    readonly error?: FormulaRecord.ParseFailure;
+    /** {@inheritDoc IFormulaBlockView.isReferenceOnly} */
+    readonly isReferenceOnly: boolean;
     /**
-     * This is the eval used internally by graph.
-     * precedents must be an array of either IRange or Scalar.
+     * The block's written references in order, aligned with `FormulaToken.referenceIndex`: what
+     * {@link IFormulaBlockView.getReferencesAt} answers from. Absent when there are none.
+     */
+    readonly references?: readonly FormulaRecord.Reference[];
+}
+export declare namespace FormulaRecord {
+    /**
+     * A written reference as the record carries it. A cell or range is relative to the block's
+     * top-left, a name is its stable id, and a table reference is as written: the model resolves it
+     * against its own table, per cell. `null` is a reference that cannot be one (`#REF!`).
+     */
+    type Reference = IRange.FixableCoords | {
+        readonly nameId: string;
+    } | {
+        readonly table: StructuredReference;
+    } | null;
+    /** A parse failure as data: what {@link IFormulaBlockView.getError} is rebuilt from. */
+    interface ParseFailure {
+        /** The text as written. */
+        readonly input: string;
+        /** The primary error's message. */
+        readonly message: string;
+        /**
+         * `true` when nothing parsed: there are no faithful tokens, and a read answers `input`. A
+         * recovered formula (an error, but a tree) images from its tokens like any other.
+         */
+        readonly unparsed: boolean;
+        /** Where the primary error sits in `input`. */
+        readonly details?: {
+            line: number;
+            column: number;
+            offset: number;
+            length: number;
+        };
+    }
+}
+/**
+ * The READ side of a formula block — what the model and the UI see. `Sheet`, `SheetCell`, autofit
+ * and `Formula` type against this; nothing outside `src/calculation/` sees the rest.
+ *
+ * @remarks
+ * The split exists so the calc engine can move behind a worker boundary. {@link ICalcGrid} is the
+ * WRITE surface (later comlink-proxied): every mutation and every question that needs the live
+ * graph goes there, its notifications come back on `ICalcGrid.Results`, and what lands here is a
+ * read view the facade builds from the engine's record of the block ({@link FormulaRecord}):
+ * tokens with stable ids, imaged on the model's side of the channel against the model's symbol
+ * map. The model holds the view and nothing else.
+ *
+ * The line: a fact that belongs to ONE BLOCK - derivable from its record - is declared here. A
+ * fact that needs the graph, the container, or a range of blocks belongs to {@link ICalcGrid}:
+ * evaluating (`evaluateAt`), every write, the recursive walks (`getPrecedentsAt`,
+ * `getDependentsAt`), the reverse edges (`getDirectDependentsAt`), what a range READ last calc
+ * (`getDirectPrecedentsAt`, which also consults the runtime `INDIRECT`/`OFFSET` registry), and
+ * the range form of what a block declares (`getNamedReferencesAt`).
+ *
+ * `FormulaBlock` satisfies both halves engine-side; `FormulaRecordView` satisfies this one over a
+ * record at the facade, and the sheet's `FormulaEntry` over that view, or over its own text while
+ * the entry is pending.
+ */
+export interface IFormulaBlockView {
+    /**
+     * 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 target Who the text is for. Default `'storage'` — the form files, undo snapshots and
+     * re-parses read. See {@link ICalculation.FormulaTarget}.
+     */
+    getTextAt(row: number, column: number, r1c1?: boolean, evalIndex?: number, target?: ICalculation.FormulaTarget): string;
+    /**
+     * 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[];
+    /**
+     * @see
+     * { @link ICalculation.IFormula.isReferenceOnly }
+     */
+    isReferenceOnly(): boolean;
+    /**
+     * Return an error with the formula.
      *
      * @remarks
-     * The precedents can be passed in as a performance optimization graph caches them as it calculates.
+     * This is not a value error but that the formula is unable to resolve.
      */
-    evaluateAt(row: number, column: number, evalIndex?: number): any;
+    getError(): FormulaError.Parse | null;
     /**
-     * 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.
+     * The formula's written references at a cell, absolute, aligned with
+     * `FormulaToken.referenceIndex`.
      *
-     * @see {@link finalizeValueForCell} for the write-to-a-grid variant.
+     * @param row The row of the cell.
+     * @param column The column of the cell.
+     *
+     * @remarks
+     * A name is `{ nameId }` holding its display name, a table reference resolves to the cells it
+     * designates from this cell (marked with its `tableId`), and a reference that cannot be one is
+     * `null`. What the formula READ on the last calculation (`INDIRECT`, `OFFSET`) is the graph's,
+     * not this list.
      */
-    finalizeValue(value: any): any;
+    getReferencesAt(row: number, column: number): ReferenceCoords[];
+}
+/**
+ * A compiled formula body, over the range of cells that share it.
+ *
+ * @remarks
+ * Extends {@link IFormulaBlockView}. The members declared HERE need the compiled AST or the
+ * engine's container. No caller outside `src/calculation/` uses any of them: a committed formula
+ * reaches the equivalent through its view ({@link IFormulaBlockView.getReferencesAt}) or
+ * {@link ICalcGrid} (`setReferenceAt`), and the block forms below serve the UNCOMMITTED path (`TemporaryFormula`, the
+ * formula the editor is tokenizing while it is typed), which has no grid entry to resolve against.
+ */
+export interface IFormulaBlock extends IFormulaBlockView {
     /**
-     * {@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.
+     * The block as data: what the engine vends for it, and what the facade images the model's view
+     * from.
+     *
+     * @remarks
+     * Built once per block and shared by every vend of it: a record is never mutated.
      */
-    finalizeValueForCell(value: any): any;
+    getRecord(): FormulaRecord;
     /**
-     * Return the formula as an array of formula token values.
+     * 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`.
      *
-     * @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.
+     * Relative to (`row`, `column`). {@link IFormulaBlockView.getReferencesAt} is the same list
+     * absolutized, and is how the model asks; it answers from the record's
+     * {@link FormulaRecord.references}.
+     *
+     * Not to be confused with `ICalcGrid.getDirectPrecedentsAt`, which is a different KIND of fact:
+     * what a range of blocks READ on the last calculation, including runtime reads (`INDIRECT`,
+     * `OFFSET`) that appear in no reference list. That one needs the container's dynamic registry
+     * and stays on the grid.
      */
-    getTokensAt(row: number, column: number, evalIndex?: number): ICalculation.FormulaToken[];
+    getReferences(row: number, column: number): ReferenceCoords[];
     /**
-     * Return the formula string.
+     * The root of the compiled tree in the shape a {@link ICalculation.FormulaTransform} and a
+     * {@link ICalculation.FormulaDialect} read, or `null` when nothing parsed.
      *
-     * @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.
+     * @remarks
+     * Engine-side, and deliberately not on {@link IFormulaBlockView}: the tree is never handed to
+     * the model. A consumer that needs something from it asks for the answer instead.
      */
-    getTextAt(row: number, column: number, r1c1?: boolean, formulaTransform?: ICalculation.FormulaTransform, evalIndex?: number, 
+    getNode(): ICalculation.FormulaNode | null;
     /**
-     * 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).
+     * The references an entered formula inherits its number format from, in text order: the cell
+     * and range literals that are value operands.
+     *
+     * @remarks
+     * Excel's entry rule: `=A1+B1` takes the format of the first of `A1`, `B1` that is not
+     * General; `=OFFSET(A1,0,0)` takes nothing, since `A1` sits in a reference-typed parameter.
+     * Names, structured references and `#REF!` slots are not listed. Anchor-free - offsets on a
+     * relative axis, a position on a fixed one - so one list serves every cell of the block; the
+     * executor ships it on {@link ICalcGrid.Results.formatInserts} for the sheet to resolve.
+     */
+    getFormatReferences(): IRange.FixableCoords[];
+    /**
+     * 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.
+     *
+     * @remarks
+     * NOT a projection of {@link IFormulaBlockView.getReferences} - that list is per-POSITION and
+     * index-aligned to `FormulaToken.referenceIndex` (null slots kept), while this is deduped,
+     * position-free, skips bound `LET`/`LAMBDA` parameters, and is cached on the compiled formula.
+     * Ids rather than {@link NamedReference}s because every caller compares ids (against
+     * `recompileNamed`'s targets, `IndirectSymbolProvider.reconcile()`).
+     *
+     * Engine-side: no view-side caller. `ICalcGrid.getNamedReferencesAt` is the range form - the
+     * union of this over the blocks a range covers - and is how `Sheet` asks.
      */
-    canonical?: boolean): string;
+    getNamedIds(): 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 index The index of the reference to replace (aligned to {@link IFormulaBlock.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 `:`);
@@ -71,6 +213,10 @@ export interface IFormulaBlock {
      *   - 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}.
+     *
+     * @remarks
+     * PURE — returns a new block rather than rewriting this one. The committed form is
+     * `ICalcGrid.setReferenceAt`, which rewrites inside a transaction batch.
      */
     setReferenceAt(index: number, reference: ReferenceCoords, options?: SetReferenceOptions): this;
     /**
@@ -83,23 +229,54 @@ export interface IFormulaBlock {
      * @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.
+     *
+     * Its one caller outside the engine is `Sheet._imageWatchBody`, which composes it with
+     * `createFormulaBlock` and `getTextAt` — compiler work, so it stays with the compiled block
+     * rather than following the read view.
      */
     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.
+     * 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
+     * Engine-side: evaluating needs the calc scope. A caller reaches it through
+     * `ICalcGrid.evaluateAt`, which establishes that scope and is async.
+     *
+     * The precedents can be passed in as a performance optimization graph caches them as it calculates.
      */
-    replaceSheetReferences(fromSheetDisplay: string, toSheetDisplay: string): this;
+    evaluateAt(row: number, column: number, evalIndex?: number): any;
     /**
-     * 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`.
+     * Finalizes a raw value from {@link IFormulaBlock.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 IFormulaBlock.finalizeValueForCell} for the write-to-a-grid variant.
      */
-    getReferences(row: number, column: number): ReferenceCoords[];
+    finalizeValue(value: any): any;
+    /**
+     * {@link IFormulaBlock.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 IFormulaBlock.finalizeValue} instead.
+     */
+    finalizeValueForCell(value: any): any;
+    /**
+     * Replaces the scope of every ref qualified with the stable id `fromScopeId` by `toScopeId` — a
+     * sheet id, a 3-D span id, or another. Unqualified refs are left untouched.
+     */
+    replaceScopeIds(fromScopeId: string | null, toScopeId: string | null): this;
     /**
      * Returns the reference at `index`, or `null` if out of range.
-     * Convenience single-slot accessor aligned to {@link getReferences}.
+     * Convenience single-slot accessor aligned to {@link IFormulaBlock.getReferences}.
      */
     getReferenceAt(row: number, column: number, index: number): ReferenceCoords;
     /**
@@ -118,6 +295,23 @@ export interface IFormulaBlock {
      * * Returns as absolute coordinates.
      */
     resolvedPrecedentsAt(row: number, column: number, includeInvalidIntersect?: boolean, verticalAbs?: boolean[], horizontalAbs?: boolean[]): readonly (Readonly<IRange.FixableCoords> | FormulaError.Known)[];
+    /**
+     * The relative form of {@link IFormulaBlock.resolvedPrecedentsAt} when that answer is a pure
+     * TRANSLATION of the formula's own references — one edge per root reference, at the asking
+     * cell's offset — or `null` when it is not.
+     *
+     * @remarks
+     * This is what lets a block of many cells stop storing an edge list per cell: with a template
+     * in hand, a cell's edges are its own position plus the relative rects here, so they can be
+     * materialized on demand into one reusable buffer instead of allocated a million times over.
+     *
+     * `null` for everything the resolver actually has to RESOLVE rather than translate — a name to
+     * flatten into the caller's edges, a table reference, a range/intersection/union operator, a
+     * computed operand. Those blocks keep their per-cell lists. A broken reference (`#REF!`) is not
+     * among them: it is the same error at every cell and rides the template as an edge that
+     * translates to nothing.
+     */
+    getPrecedentTemplate(): PrecedentTemplate | null;
     /**
      * Wraps the formula in an implicit reference operator if hasSpill returns true and the formula
      * expects a spill.
@@ -130,28 +324,9 @@ export interface IFormulaBlock {
      * 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}.
+     * named formulas AND tables. Superset of {@link IFormulaBlock.getNamedIds}.
      *
      * @remarks
      * Used to reverse-invalidate dependents when a name/table's resolution changes (add/heal, delete,
@@ -171,6 +346,25 @@ export interface IFormulaBlock {
      * either all of them call a total function or none do.
      */
     hasTotals(): boolean;
+    /**
+     * Whether the cells of a block running this formula whose relative inputs are all blank share
+     * one value within a pass, as far as the formula TEXT can say.
+     *
+     * @remarks
+     * Read straight off the compiled cache — see `CompiledFormula.isBlankCacheable`. The block's
+     * own gates (a precedent template, not array-entered) and the pass's run-time ones are checked
+     * by the consumer; `false` here settles it without them.
+     *
+     * @param arrayMode For a block whose every cell is its own 1x1 array-entered extent — see
+     * `CompiledFormula.isBlankCacheableArray`.
+     */
+    isBlankCacheable(arrayMode?: boolean): boolean;
+    /**
+     * Prepares the formula to be evaluated under a first-cell demand — as the body of a block whose
+     * every cell is its own 1x1 array-entered extent — by marking which nodes only ever have element
+     * `[0,0]` read (`CompilerUtils.annotateFirstCell`). Idempotent.
+     */
+    demandFirstCell(): void;
     /**
      * If the formula is logically equal to another formula.
      *

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

@@ -1,4 +1,5 @@
 import { IFunction } from '@sheetxl/primitives';
+import { ILambdaValue } from '../../primitives/LambdaBrand';
 import { ASTNode } from '../compiler/ASTTypes';
 import { CompiledFormula } from '../compiler/Types';
 import { IFormulaBlock } from './IFormulaBlock';
@@ -29,10 +30,7 @@ export interface LambdaParam {
     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.
-     */
+    /** Declared optional (`[b]`) — an absent trailing argument is legal at and after it. */
     readonly optional: boolean;
 }
 /**
@@ -49,9 +47,11 @@ export interface LambdaParam {
  * 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.
+ * activation's environment intact underneath it. The snapshot is also the ACTIVATION: every
+ * application of the value runs its body in these registers, and only a re-entrant application
+ * copies them (`FormulaBlock._evaluateBody`).
  */
-export declare class LambdaValue {
+export declare class LambdaValue implements ILambdaValue {
     /** The declared parameters, in order. */
     readonly params: readonly LambdaParam[];
     /** The body subtree (excluded from the eager execution list — design §3.3). */
@@ -71,12 +71,12 @@ export declare class LambdaValue {
     /** 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;
+    /** @inheritdoc ILambdaValue.isFunctionValue */
+    readonly isFunctionValue: true;
+    /** The value as a declared, executable function — built on first ask. */
+    private _asFunction;
+    /** Applications of this value currently running in `regs` — see the class remarks. */
+    active: number;
     constructor(
     /** The declared parameters, in order. */
     params: readonly LambdaParam[], 
@@ -102,6 +102,21 @@ export declare class LambdaValue {
      * which shares `_evaluateBody` (and the recursion budget) with the spelled `Call` path.
      */
     makeCallable(): LambdaCallable;
+    private _function;
+    /**
+     * Applies the lambda over values and returns its RAW result — the caller applies its own rule to
+     * an array. An error comes back as a value, never thrown.
+     */
+    execute<R = any>(...args: any[]): R;
+    /** Always `''`: a lambda passed as a value has no name. */
+    getName(): string;
+    /** Declares the lambda's own parameters, optional ones flagged. */
+    getDeclaration(): IFunction.IDeclaration;
+    getDescriptor(locale?: string): Promise<IFunction.IDescriptor>;
+    isBuiltIn(): boolean;
+    isLambda(): boolean;
+    getContext(): string | null;
+    get isIFunction(): true;
     get [Symbol.toStringTag](): string;
 }
 /**
@@ -109,14 +124,15 @@ export declare class LambdaValue {
  * 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.
+ * Shares the `isFunctionValue` brand: both are function values, and every non-callee consumer
+ * treats them identically (cell → `#CALC!`, coercion → `#VALUE!`). Apply dispatches to the function
+ * itself, and as an {@link IFunction} it answers as that function does.
  */
-export declare class FunctionValue {
+export declare class FunctionValue implements ILambdaValue {
     /** The referenced function. */
     readonly fn: IFunction;
-    /** @see LambdaValue.isLambda */
-    readonly isLambda: true;
+    /** @inheritdoc ILambdaValue.isFunctionValue */
+    readonly isFunctionValue: true;
     constructor(
     /** The referenced function. */
     fn: IFunction);
@@ -128,16 +144,25 @@ export declare class FunctionValue {
      * arity/coercion error comes back as a value, embedding per element like any other result.
      */
     makeCallable(): LambdaCallable;
+    execute<R = any>(...args: any[]): R;
+    getName(): string;
+    getDeclaration(): IFunction.IDeclaration;
+    getDescriptor(locale?: string): Promise<IFunction.IDescriptor>;
+    isBuiltIn(): boolean;
+    isLambda(): boolean;
+    getContext(): string | null;
+    get isIFunction(): true;
     get [Symbol.toStringTag](): string;
 }
 /**
- * The sentinel apply binds for an absent or explicitly-skipped OPTIONAL parameter (design §3.5).
+ * The sentinel a binding holds when its argument was supplied EMPTY — an explicitly empty slot at
+ * a lambda or `LET` call (`f(,1)`, `LET(x,,…)`), or an absent trailing argument at an OPTIONAL
+ * parameter (design §3.4).
  *
  * @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.
+ * (`readFrameValue`), except in the argument slot of `ISOMITTED` itself.
  */
 export declare const OMITTED: unique symbol;
 /**
@@ -149,9 +174,7 @@ 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
+ * 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

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

@@ -0,0 +1,96 @@
+import { ILazy } from '@sheetxl/primitives';
+import { ASTNode } from '../compiler/ASTTypes';
+import { IFormulaBlock } from './IFormulaBlock';
+/**
+ * The handle a `Lazy` parameter receives — one argument's subtree, anchored at the calling cell,
+ * that the engine has either not evaluated yet or has evaluated already.
+ *
+ * @remarks
+ * CALCULATION-PRIVATE as a class; the INTERFACE (`ILazy`) is public, because a function author
+ * declares the slot and may read it. The sibling of `LambdaValue`, and the same idea: "evaluate
+ * this piece of the formula later, anchored at this cell". The difference is only what it closes
+ * over — an argument's subtree rather than a lambda's body — and that this one takes no
+ * parameters, so forcing it is a call with an empty argument list.
+ *
+ * A body does one of two things with it, and the engine answers for both:
+ *
+ * - **returns it unread** — the engine sees its own handle come back as the call's result and
+ *   evaluates the subtree then, on its normal path, so an ASYNC subtree is fine there.
+ * - **forces it** with {@link getValue} — which happens mid-body, where the engine has no way to
+ *   wait, so a subtree that answers a promise is `#VALUE!` rather than a wrong answer.
+ *
+ * A DEFERRED handle carries the block, the node and the registers to evaluate against; a
+ * PRE-FILLED one carries the value alone ({@link LazyValue.of}) and is what the engine hands over
+ * whenever it declines to defer — an empty or literal argument, or a call that is about to lift.
+ * The author cannot tell them apart, which is the point: laziness is the engine's to grant.
+ *
+ * ### Lifetime, and why the deferred handles are pooled
+ *
+ * A handle lives exactly as long as the call it was built for, and that life is SYNCHRONOUS: the
+ * body either forces it in place or returns it unread, and the executor forces a returned one
+ * before it moves on. Nothing retains a handle past that point — every value-layer boundary
+ * (coercion, the operators, a range's typed read, a cell's final value) recognizes and refuses
+ * one. So a deferred handle is not allocated per call; it is taken from a pool indexed by call
+ * DEPTH and argument position ({@link deferred}) and re-pointed at the next call's subtree. Depth,
+ * not node: the same `IF` node re-enters at a deeper level under recursion, and a nested call
+ * inside a body (a forced arm that itself calls `IF`) must not re-point the handles the enclosing
+ * body is still holding. The executor brackets each lazy call with {@link enter} / {@link leave},
+ * which is what makes the nested call land one level deeper.
+ *
+ * The async case is safe under this: {@link _force} stores the promise as the value, and the
+ * executor's chain holds the promise, not the handle.
+ */
+export declare class LazyValue implements ILazy {
+    /** @inheritdoc ILazy.isLazy */
+    readonly isLazy: true;
+    /** The forced value, once {@link _force} has run. */
+    private _value;
+    private _forced;
+    /** The block whose formula the subtree belongs to, or `null` when pre-filled. */
+    private _owner;
+    /** The argument's subtree root. */
+    private _node;
+    /** The register file to evaluate against — the block's own, or a lambda activation's. */
+    private _regs;
+    /** The lambda-parameter frame in scope, when the call sits inside a lambda body. */
+    private _frame;
+    /** The anchor the owner is being evaluated at. */
+    private _row;
+    private _col;
+    private constructor();
+    /**
+     * One row of handles per call depth, one handle per argument position — see the class remarks.
+     * Grows to the deepest nesting and widest lazy call seen, and is never trimmed.
+     */
+    private static readonly _pool;
+    private static _depth;
+    /**
+     * Opens the handle row for a lazy call about to be filled. Answers the depth to pass to
+     * {@link deferred} and back to {@link leave}, in a `finally`.
+     */
+    static enter(): number;
+    /** Closes the row {@link enter} opened. Restores rather than decrements, so a throw cannot skew it. */
+    static leave(depth: number): void;
+    /**
+     * A handle over a subtree the engine has NOT evaluated — the pooled handle at `(depth, slot)`,
+     * re-pointed. Valid until {@link leave} closes the depth; the caller must not keep it past that.
+     */
+    static deferred(depth: number, slot: number, owner: IFormulaBlock, node: ASTNode, regs: any[], frame: ReadonlyMap<number, any> | null, row: number, column: number): LazyValue;
+    /** A handle over a value the engine has ALREADY computed — the decline path. */
+    static of(value: any): LazyValue;
+    /**
+     * Re-points a filled handle at another value. The lift's per-element reset: one handle per lazy
+     * slot for the whole spill, pointed at each sampled member in turn, instead of {@link of} per
+     * element. Only for a handle that was never deferred.
+     */
+    _fill(value: any): void;
+    /**
+     * Evaluates the subtree, at most once. The ENGINE's entry point: a promise here is an async
+     * subtree returned unread, which the caller chains like any other async node result.
+     */
+    _force(): any;
+    /** @inheritdoc ILazy.getValue */
+    getValue(): any;
+    get [Symbol.toStringTag](): string;
+}
+//# sourceMappingURL=LazyValue.d.ts.map