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

package/types/src/calculation/compiler/Types.d.ts

@@ -1,5 +1,5 @@
 import { IFunction, IRange, IRuntime } from '@sheetxl/primitives';
-import { ISymbolRegistry } from '../symbol';
+import { ISymbolRegistry, SheetCtx } from '../symbol';
 import { ICalculation } from '../ICalculation';
 import { ASTNode, ASTVisitor } from './ASTTypes';
 /**
@@ -33,14 +33,19 @@ export interface IFormulaCompiler {
      */
     scope?: string | null, 
     /**
-     * A structural transform applied to the parsed tree before compilation (pre-link) — the READ
-     * half of the dialect hook. A format reader (io-xlsx) supplies its legacy unwrap here; typed
-     * text compiles without one.
+     * Compile in the legacy entry era: the whole tree evaluates in implicit-intersection value
+     * mode (`ICalculation.JSON.legacyIntersect`). A loaded block that is not an array anchor, in a
+     * calculation in that era; typed text compiles without it.
      */
-    formulaTransform?: ICalculation.FormulaTransform): CompiledFormula;
+    legacyIntersect?: boolean, 
+    /**
+     * How SHEET scopes bind — a body linked inside an external book names that book's sheets
+     * (`SheetCtx.book`). A committed cell formula passes nothing and may mint a link.
+     */
+    sheetCtx?: SheetCtx): CompiledFormula;
     /**
      * Excel-parity **Formula AutoCorrect** at the TEXT level: repair `expression` by appending the
-     * trailing closers (`)` / `}`) its unmatched openers imply. Purely lexical — brackets inside
+     * trailing closers (`]` / `)` / `}`) its unmatched openers imply. Purely lexical — brackets inside
      * string literals / structured references never count (they lex as single tokens), and the repair
      * is NOT validated here: the caller re-compiles and accepts it only when it parses clean (see
      * `ICalculation.IFormula.autoCorrect`).
@@ -162,10 +167,24 @@ export interface CompiledFormula {
      */
     bindings: number[];
     /**
-     * Represents all references as absolute ranges.
+     * Reusable scratch for resolving references to absolute ranges: ONE pre-allocated
+     * `IRange.Coords` per {@link referencesRelative} entry, mutated in place at each resolution.
      *
      * @remarks
-     * A cache
+     * The invariant every consumer must keep: **slot `k` always means declared reference `k`**
+     * (`CompiledPrecedent.value` is the slot for a leaf), and a resolution overwrites EVERY field
+     * of the slot — bounds and `scope` (`null` when unscoped, never left over from a previous
+     * resolution). Both resolution passes go through `toSimpleAbsoluteRange`, so the slots carry
+     * NO `$` marks: nothing on the evaluation path reads them from a resolved-absolute coords,
+     * and `_appendRootPrecedents` requires their absence (it stamps `$` onto copies from the
+     * compiler's per-axis flags, and only ever sets). Indexing by anything else (an execute
+     * position, an eval index) makes one object stand for different references between passes,
+     * and any field written conditionally then leaks across them — a bare `$A4` once inherited a
+     * stale cross-sheet scope this way and dereferenced against the wrong grid.
+     *
+     * The objects are yielded to callers (`evaluations`, precedent lists) and are only valid
+     * until the block's next resolution — a consumer that retains one across evaluations (or an
+     * `await`) must copy it.
      */
     referencesAbsolute: IRange.Coords[];
     /**
@@ -191,6 +210,16 @@ export interface CompiledFormula {
      * Because we manage as cells but update as ranges we need to track the start and end of the references.
      */
     referenceIndices: number[];
+    /**
+     * Positions in {@link referenceIndices} (so in `getReferences()`) of the cell and range
+     * literals that are value operands, in text order - the cells an entered formula inherits its
+     * number format from. A literal at a reference-typed parameter, a name, a structured reference
+     * and a `#REF!` are not listed.
+     *
+     * @remarks
+     * A cache, computed once at compile time from {@link ast}.
+     */
+    formatReferenceIndices: number[];
     /**
      * The formula's editor tokens (syntax highlighting, function/argument hints). Computed lazily and
      * cached on first call — most compiles (grid cells) never need them. On a parse failure this returns
@@ -223,7 +252,7 @@ export interface CompiledFormula {
      * @remarks
      * A cache, computed once at compile time from {@link ast}. What `IFormulaContext.filterTotals`
      * needs to answer per CELL, and computing it here is what keeps that answer free: the alternative
-     * is re-inspecting a neighbour's formula on every recalculation of every enclosing total.
+     * is re-inspecting a neighbor's formula on every recalculation of every enclosing total.
      *
      * "Anywhere in its tree", not "is the outermost call" — measured, `=SUM(SUBTOTAL(9,A1:A3))` is
      * excluded from an enclosing SUBTOTAL exactly as a bare `=SUBTOTAL(9,A1:A3)` is. Resolved through
@@ -231,6 +260,47 @@ export interface CompiledFormula {
      * `_xlfn.`-prefixed one both answer correctly.
      */
     hasTotals: boolean;
+    /**
+     * Whether the formula names a VOLATILE function anywhere in its tree — the cell recalculates on
+     * every pass, whether or not that call is ever reached.
+     *
+     * @remarks
+     * Volatility is otherwise marked at RUNTIME, by the body (`IFormulaContext.markVolatile`), which
+     * was equivalent while every argument was evaluated. It stopped being equivalent with lazy
+     * arguments: `=IF(TRUE,1,RAND())` never runs `RAND` and would silently stop recalculating.
+     * Excel keeps it volatile — measured 2026-09-07, `probe-lazy-args.ps1` P1: the cell costs a full
+     * recalculation on every idle F9, for `RAND`, `NOW` and `OFFSET` alike, in an arm no branch
+     * selects. So the mark is a property of the formula TEXT and is collected here.
+     *
+     * The declaration answers it (`Volatile<T>` on the return), so a UDF counts exactly as a
+     * built-in does and no list of names lives in the engine. `IFormulaContext.markVolatile()`
+     * remains on the context for a function that cannot declare — it is not how a built-in says it.
+     */
+    hasVolatile: boolean;
+    /**
+     * Whether every cell of a block running this formula whose RELATIVE inputs are all blank must
+     * evaluate to the same value within one pass — so the engine may evaluate one of them and share
+     * the answer (PLAN-WATCHES-BLANK-AWARE §4).
+     *
+     * @remarks
+     * A property of the formula TEXT, like {@link hasVolatile}, and `false` whenever the text shows
+     * the answer could depend on which cell is asking: an implicit intersection, a name, an
+     * expression callee, or a function the registry does not know. `TODAY()` and `NOW()` are
+     * accepted: volatile, but one value per pass. So are `RAND()` and every function taking a
+     * reference (`ROW()`, `OFFSET`, `FORMULATEXT`, the `SUMIF` family): whether the body reads a
+     * position (or draws) is a per-cell READ (`CalcScope.perCellRead`) that the pass sees when it
+     * evaluates the representative, not a property of the text. The block adds its own gates (a
+     * precedent template, not array-entered) and the pass its run-time ones (no dynamic read, no
+     * per-cell read, a scalar result); this is only the half that can be known from the text.
+     */
+    isBlankCacheable: boolean;
+    /**
+     * {@link isBlankCacheable} for a block evaluated in ARRAY mode throughout — every cell its own
+     * 1x1 array-entered extent (a conditional-format body). The same refusals less the value-mode
+     * one: with nothing intersecting, a value-or-range slot over a multi-cell reference reads the
+     * same cells at every cell.
+     */
+    isBlankCacheableArray: boolean;
     /**
      * Indicates if the formula is reference-only (i.e. it only returns a range and does not return a scalar value).
      */