@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.3

package/types/src/calculation/_CloneBoundary.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The clone boundary: a test mode that treats the model/engine crossing as if it were a wire
+ * (DESIGN-CALC-SERVICE §11, goal G1, plan step 6).
+ *
+ * @remarks
+ * Every request into a grid and every {@link ICalcGrid.Results} out of one passes through here.
+ * With the mode `off` - always, outside a test - it is an identity call and costs nothing.
+ *
+ * Two things it finds, and they are different:
+ *
+ * - What a walk can see: a function, a class instance, a value `structuredClone` refuses or
+ *   silently downgrades. Each is recorded as a {@link Violation} with the PATH it sat at, which
+ *   is the point: a payload that degrades silently fails somewhere else entirely, and the path
+ *   is what names the field to convert.
+ * - What only running can see: a reference the two sides SHARE. A walk cannot tell a run array
+ *   the sheet also holds from one minted for the message; a clone does, because the sides stop
+ *   agreeing. That is what `clone` mode is for, and why `audit` alone is not the exit criterion.
+ *
+ * Not a boundary for READS. `getValues`, `getFormulas`, `getSnapshot` and the graph walks answer
+ * synchronously out of engine objects; making them push or await is §11's list, not this one.
+ * This covers what is already message-shaped.
+ *
+ * @internal Test-mode only. Deliberately not exported from the barrel.
+ */
+export declare namespace CloneBoundary {
+    /**
+     * `off` is the default and the only mode outside a test.
+     *
+     * `audit` records what would not survive the crossing and passes the ORIGINAL through, so a
+     * suite stays green and the run produces the list. `clone` substitutes the
+     * `structuredClone` - the real wire - and is the exit criterion for "ready for a worker".
+     */
+    type Mode = 'off' | 'audit' | 'clone';
+    /** What a value at a path does to a `structuredClone`. */
+    type ViolationKind = 
+    /** A function or a symbol: `structuredClone` throws. */
+    'function'
+    /** A class instance: cloned as a plain object, its methods gone, and nothing says so. */
+     | 'live'
+    /** An `Error` subclass: clones to a bare `Error` - the subclass and its own fields are lost. */
+     | 'downgraded';
+    interface Violation {
+        /** Which crossing: `'request:setInputs'`, `'results:onCalculated'`, ... */
+        where: string;
+        /** Where in the payload, with array indices collapsed: `results.formulaInserts[].value`. */
+        path: string;
+        kind: ViolationKind;
+        /** The constructor name, or `'function'` / `'symbol'`. */
+        type: string;
+    }
+    /** Thrown by `clone` mode when the payload cannot be cloned at all. */
+    class BoundaryError extends Error {
+        readonly violations: readonly Violation[];
+        constructor(where: string, violations: readonly Violation[], cause: unknown);
+    }
+    /** Sets the mode. Anything but a known mode (including `undefined`) is `off`. */
+    const setMode: (mode: string | null | undefined) => void;
+    const getMode: () => Mode;
+    /**
+     * Called once per DISTINCT violation (a payload of 50000 cells reports its field once), so a
+     * host can write the run's list somewhere a test runner does not swallow.
+     */
+    const setListener: (listener: ((violation: Violation) => void) | null) => void;
+    /** Every distinct violation seen since the mode was set. */
+    const getViolations: () => readonly Violation[];
+    const clearViolations: () => void;
+    /**
+     * A request on its way to a grid.
+     *
+     * @param where The request's `type`, for the report.
+     */
+    const request: <T>(request: T, where: string) => T;
+    /**
+     * An {@link ICalcGrid.Results} on its way back: a resolution, or a record the engine pushed.
+     *
+     * @param where Which of the two, for the report.
+     */
+    const results: <T>(results: T, where: string) => T;
+}
+//# sourceMappingURL=_CloneBoundary.d.ts.map

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

@@ -43,6 +43,32 @@ export interface ASTNode<T extends TokenType = TokenType, V = any> {
      * @see {@link ICalculation.FormulaToken.evalIndex}
      */
     evalIndex?: number;
+    /**
+     * Compile-time: the implicit-intersection MODE this call is evaluated in — `true` VALUE mode
+     * (a multi-cell reference at a single-value slot intersects with the formula cell), `false`
+     * ARRAY mode (it reads its first cell). Set on `Function` and `Call` nodes by
+     * `CompilerUtils.annotateImplicitIntersect` (DESIGN-IMPLICIT-INTERSECTION §2).
+     */
+    implicitIntersect?: boolean;
+    /**
+     * Compile-time: under a first-cell DEMAND (a block whose every cell is its own 1x1 array-entered
+     * extent — a conditional-format body), only element `[0,0]` of this node's result is ever read,
+     * so a lift or an operator here builds that one element. Set on every node reachable from the
+     * root through elementwise positions by `CompilerUtils.annotateFirstCell`
+     * (DESIGN-LIFT-AND-DEMAND §2); inert unless the block evaluating the formula demands it.
+     */
+    firstCell?: boolean;
+    /**
+     * The ROOT only: the formula came from a LEGACY cell, so `annotateImplicitIntersect` gives its
+     * WHOLE tree value mode instead of deriving a mode per node. Carried in from the reader's
+     * transform (`ICalculation.FormulaNode.legacyIntersect`); never persisted.
+     */
+    legacyIntersect?: boolean;
+    /**
+     * Compile-time memo: whether this expression is statically array-valued (a range, an array
+     * literal, an array-returning call, an operator over one). Read by the mode annotation.
+     */
+    arrayValued?: boolean;
     /**
      * For live editing. We may need to add original start/end offsets to align?
      *
@@ -102,6 +128,38 @@ export interface ASTNode<T extends TokenType = TokenType, V = any> {
      * accepted cost — design §3.4); only the eager VALUE resolution is skipped.
      */
     deferredResolve?: boolean;
+    /**
+     * Set by the compiler on an argument node that binds to a `Lazy` parameter: the ENGINE hands the
+     * body a handle over this subtree instead of its value.
+     *
+     * @remarks
+     * The subtree is absent from the eager execution list (the same carve-out a `LAMBDA` body gets)
+     * and is evaluated only if the call's answer turns out to be the handle. An `Empty` argument is
+     * never marked — an omitted comma is a value the caller supplied, and it marshals as one.
+     */
+    lazyArg?: boolean;
+    /**
+     * Set by the compiler on every node WITHIN a lazy argument's subtree, the root included. What
+     * the execution-list carve-out reads.
+     */
+    inLazy?: boolean;
+    /**
+     * Set by the compiler on a call node that has at least one {@link lazyArg} — so the hot argument
+     * loop pays one boolean for a feature almost no call uses.
+     */
+    hasLazyArgs?: boolean;
+    /**
+     * Set by the compiler on the ROOT of a deferred subtree — a `LAMBDA` body or a {@link lazyArg} —
+     * to the post-order execution list of that subtree, the root included: the same shape as
+     * `CompiledFormula.executions`, for the piece of the formula the eager pass leaves out.
+     *
+     * @remarks
+     * A nested root's nodes are on the nested list, not this one (its root node is here, and
+     * evaluating it closes over or defers what is underneath). A bound name executes wherever it
+     * sits; an unbound name (`deferredResolve`) is on the list too, since the eager reference pass
+     * skips it and resolving it is what the deferral is for.
+     */
+    deferred?: ASTNode[];
     /**
      * If ast had an error.
      *

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

@@ -1,6 +1,6 @@
 import { FormulaError, IFunction, IRuntime } from '@sheetxl/primitives';
 import { ICalculation } from '../ICalculation';
-import { ISymbolRegistry } from '../symbol';
+import { ISymbolRegistry, SheetCtx } from '../symbol';
 import { TokenType } from '../TokenType';
 import { CompiledFormula, ParseError } from './Types';
 import { ASTNode } from './ASTTypes';
@@ -62,6 +62,30 @@ export declare function normalizeStructuredRefs(ast: ASTNode): ASTNode;
  * @returns A new AST (structurally shared where unchanged).
  */
 export declare function rewriteThisRowToAt(ast: ASTNode): ASTNode;
+/**
+ * Collapses a table reference with EMPTY brackets to the bare table name: `Table1[]` → `Table1`.
+ *
+ * @remarks
+ * Both are the data body. Excel accepts either on entry and shows the bare name; on disk it writes
+ * `Table1[]`, which is io-xlsx's spelling. Commit-path only, the boundary {@link rewriteThisRowToAt}
+ * observes. A reference with no table name (`[]`) and an unterminated one are left alone.
+ *
+ * @returns A new AST (structurally shared where unchanged).
+ */
+export declare function collapseEmptyStructuredRefs(ast: ASTNode): ASTNode;
+/**
+ * Gives an unqualified structured reference (`[@Qty]`, `[#All]`) its table name: `Table1[@Qty]`.
+ *
+ * @remarks
+ * Linking already bound it to the table at the formula's cell; this drops the typed image that kept
+ * the name out of the text. Every reference is stored qualified, as Excel writes it. Which ones show
+ * without the name is decided at display time, from where the formula sits.
+ *
+ * Commit-path only, the boundary {@link rewriteThisRowToAt} observes: an editor keeps what was typed.
+ *
+ * @returns A new AST (structurally shared where unchanged).
+ */
+export declare function qualifyStructuredRefs(ast: ASTNode): ASTNode;
 /**
  * Sorts the items inside every `TableReference` into Excel's canonical order — section specifiers
  * in band order (`#All` | `#Headers`, `#Data`, `#Totals`), then the column selector.
@@ -81,6 +105,55 @@ export declare function rewriteThisRowToAt(ast: ASTNode): ASTNode;
  * @returns A new AST (structurally shared where unchanged).
  */
 export declare function reorderStructuredRefItems(ast: ASTNode): ASTNode;
+/**
+ * Annotates every call node with its implicit-intersection MODE (DESIGN-IMPLICIT-INTERSECTION §2,
+ * measured on Excel 16.0 by `probe-ii-propagation{,2,3}.ps1`): `true` is VALUE mode, where a
+ * multi-cell reference at a single-value slot intersects with the formula cell; `false` is ARRAY
+ * mode, where it reads its first cell. The mode is INHERITED — a call evaluates its arguments in
+ * the mode it was given — and set at four places only:
+ *
+ * - the root: array mode when the root expression is statically array-valued (`=LINEST(..)`,
+ *   `=TRANSPOSE(..)`, `=A1:A3+0`), value mode when it is scalar (`=SUM(..)`, `=INDEX(..,1,1)`);
+ * - an operand of an operator, or the argument at a lifting scalar slot, when that operand is
+ *   array-valued (the lift needs the whole array);
+ * - a `LAMBDA` body, always;
+ * - an array-entered block, at evaluation (`CalculationContext.isImplicitIntersect`).
+ *
+ * A LEGACY (pre-dynamic-array) formula skips all four: its WHOLE tree is value mode, which is the
+ * era's own regime (DESIGN-IMPLICIT-INTERSECTION §2, `probe-ii-propagation3.ps1` §I —
+ * `=SUM(LINEST(y,x,ref)+0)` intersects in a legacy cell where the operator would otherwise give
+ * the call array mode). It changes the answer for the LINEST family's logical slots ALONE: every
+ * other legacy site Excel spells with an `@`, which the reader's transform has already inserted,
+ * and the two slots that take no `@` either read their first cell in both eras (`N`, `T`) or
+ * intersect in both (`AGGREGATE`'s `k`).
+ *
+ * "Array-valued" is static: a range or array literal, a call whose declared return is an array or
+ * a reference, an operator over one, a pass-through (`IF`, `IFERROR`, …) over one, `INDEX` with a
+ * zero, empty or array index, a name or a lambda application (unknown, so array — what Excel does
+ * at the root). The two runtime refinements Excel makes (`INDEX` on a CELL holding 0, and a
+ * defined name taking the mode of its reference site) are not modelled here.
+ */
+export declare function annotateImplicitIntersect(root: ASTNode, getFunction: ((name: string) => IFunction | null) | null | undefined, legacy?: boolean): void;
+/**
+ * Annotates the nodes whose result is read only at element `[0,0]` when the formula is evaluated
+ * under a first-cell demand (DESIGN-LIFT-AND-DEMAND §2, PLAN-CF-BODY-DEMAND step 3): the body of a
+ * block whose every cell is its own 1x1 array-entered extent, which is how Excel evaluates a
+ * conditional-format formula.
+ *
+ * @remarks
+ * The demand starts at the root and is INHERITED through elementwise positions only — an operator
+ * that is not a reference operator, a one-element paren, a lifting scalar slot, an `any` slot
+ * (`IF`/`IFS`/`SWITCH`/`CHOOSE` arms, which size and sample in the lift), a `LET` body. At each of
+ * those `[0,0]` of the output depends only on `[0,0]` of each operand, and `(0,0)` is never a pad,
+ * so computing one element is computing `[0,0]`. It stops (`false`) at every other position: a
+ * range, array, reference-only, lambda or flattened slot takes its argument whole (`SUM` still sees
+ * the array), and so do a reference operator, `@`, a name, a lambda body and a `LET` binding (a
+ * binding may be read under an aggregate).
+ *
+ * Idempotent and a property of the tree alone, so a compiled formula shared by several blocks
+ * carries it harmlessly: nothing reads it unless the block evaluating the formula demands it.
+ */
+export declare function annotateFirstCell(root: ASTNode, getFunction: ((name: string) => IFunction | null) | null | undefined): void;
 export declare function compileAST(runtime: IRuntime, symbols: ISymbolRegistry | undefined, original: ASTNode, preserveExpression?: boolean, error?: ParseError | null, getFunction?: ((name: string) => IFunction | null) | null): CompiledFormula;
 /**
  * Convert a chevrotain error into a {@link FormulaError.Parse}.
@@ -278,6 +351,16 @@ export declare const findInvalidCallee: (root: ASTNode, getFunction: ((name: str
  *   registry path stay exactly as they were.
  */
 export declare function rewriteUnknownFunctionCalls(root: ASTNode, getFunction: ((name: string) => IFunction | null) | null): ASTNode;
+/**
+ * `bound` with `name` added last — an inner declaration replaces an outer one spelled the same
+ * (case-insensitively). Builds {@link ICalculation.FormulaTokenContext.bound}.
+ */
+export declare function appendBound(bound: readonly ICalculation.BoundName[] | undefined, entry: ICalculation.BoundName): readonly ICalculation.BoundName[];
+/**
+ * The declarations of a literal `LAMBDA(…)` node, as {@link ICalculation.BoundName.params}, or
+ * `undefined` for any other node.
+ */
+export declare function lambdaParamsOf(node: ASTNode | undefined): ICalculation.BoundName['params'];
 /**
  * Annotates the `LET`/`LAMBDA` scopes in a parsed AST: each declaration position is marked a
  * BINDER and every use its scope covers is bound to that binder's slot.
@@ -308,6 +391,42 @@ export declare function rewriteUnknownFunctionCalls(root: ASTNode, getFunction:
  * name (it never reaches the resolver at all).
  */
 export declare function bindScopes(root: ASTNode, getFunction?: ((name: string) => IFunction | null) | null): ASTNode;
+/**
+ * Re-reads every REFERENCE token in the formula as a NAME, when any `LET`/`LAMBDA` declaration
+ * position is a cell reference.
+ *
+ * @param root The parsed AST.
+ * @param getFunction Resolves a function name to its declaration; see {@link _binderKind}.
+ * @returns A new root, the SAME root when no declaration is reference-shaped, or a MESSAGE when
+ * the formula has to be refused at entry.
+ *
+ * @remarks
+ * `LET(A1,7,A1)` is 7 in Excel, and the consequence is far wider than the name that caused it:
+ * ONE reference-shaped declaration anywhere in a formula stops EVERY A1-style token in that
+ * formula from reading as a cell. It is not a scope rule and not a shadow — the switch covers the
+ * whole formula text, measured in every direction (probe-let-ref-names.ps1):
+ *
+ * | formula | Excel |
+ * | --- | --- |
+ * | `LET(BA1,7,BA1)` | 7 — the declaration resolves |
+ * | `LET(BA1,7,BA2)` | `#NAME?` — a token bound nowhere no longer names a cell |
+ * | `LET(BA1,BA2,BA1)` | `#NAME?` — the declaration's OWN value expression is included |
+ * | `BA2+LET(BA1,7,BA1)` | `#NAME?` — so is text BEFORE the `LET`, outside it |
+ * | `LET(BA1,7,BA1)+LET(q,1,q+BA2)` | `#NAME?` — and an unrelated SIBLING scope |
+ * | `LET(BA1,7,BA2,9,BA1+BA2)` | 16 — two declarations, both resolving |
+ * | `LET(BA1,7,BA2,9,SUM(BA1:BA2))` | `#VALUE!` — `7:9`, the range OPERATOR over two values |
+ *
+ * Excel refuses to create a defined name that looks like a cell reference, so a re-read token can
+ * only resolve to a `LET`/`LAMBDA` declaration; everything else is `#NAME?`, which is what the
+ * ordinary resolver answers once the node is a name. That is why this pass has no resolution of
+ * its own — it changes what the tokens ARE and lets `bindScopes` and the resolver do the rest.
+ *
+ * The one entry refusal is `$`: a name cannot contain one, so under the switch any `$` in an
+ * A1-style token makes the formula untypeable — in a declaration or in a use, on one axis or both
+ * (`LET(BA1,7,BA1+$BA$2)`, `LET(BA1,7,BA1+BA$2)`, `LET($BA$1,7,$BA$1)`;
+ * probe-let-ref-names2.ps1 §B).
+ */
+export declare const retypeReferenceBinders: (root: ASTNode, getFunction?: ((name: string) => IFunction | null) | null) => ASTNode | string;
 /**
  * Finds a malformed `LET`/`LAMBDA` scope — a shape Excel refuses at ENTRY.
  *
@@ -328,19 +447,22 @@ export declare function bindScopes(root: ASTNode, getFunction?: ((name: string)
  * normalization a name comparison gets everywhere else.
  */
 export declare const findBinderViolation: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => string | null;
+export declare function linkSymbols(ast: ASTNode, symbols: ISymbolRegistry, scope?: string | null, sheetCtx?: SheetCtx, home?: {
+    rowIndex: number;
+    colIndex: number;
+} | null): ASTNode;
 /**
- * Visits the AST and links display names to stable IDs using the symbol registry.
- *
- * @param ast The root AST node to start the traversal.
- * @param symbols The symbol registry used to resolve display names to stable IDs.
- * @param scope The sheet this formula is written on, or `null`/omitted when there is none.
- *   Only defined names need it, and only because they can be sheet-scoped: `MonthName` on January
- *   and the same text on February are two different names when each sheet defines its own, so the
- *   vantage is part of the question. Without it every reference binds to whichever definition
- *   happened to win globally.
- * @returns The updated AST with linked symbols.
+ * The first structured reference Excel refuses at entry, after {@link linkSymbols}: an unqualified one
+ * (`[@Qty]`) whose formula is not in a table or whose table has no such column, and a qualified one
+ * naming a table that does not exist (`Nope[Qty]`) or a column its table does not have
+ * (`Table1[Nope]`).
+ *
+ * @remarks
+ * A bare name (`=Nope`) is not a structured reference and is not refused: it is `#NAME?`.
+ *
+ * @returns A message, or `null` when every structured reference names its table's columns.
  */
-export declare function linkSymbols(ast: ASTNode, symbols: ISymbolRegistry, scope?: string | null): ASTNode;
+export declare function findUnboundTableReference(ast: ASTNode, symbols?: ISymbolRegistry): string | null;
 /**
  * Returns a new AST with every relative Cell node's coordinates shifted by (rowDelta, colDelta),
  * wrapping out-of-bounds results within [0, max) (Excel behavioral).

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

@@ -1,5 +1,5 @@
 import { IFunction, IRuntime } from '@sheetxl/primitives';
-import { ISymbolRegistry } from '../symbol';
+import { ISymbolRegistry, SheetCtx } from '../symbol';
 import { ICalculation } from '../ICalculation';
 import { IFormulaCompiler, CompiledFormula } from './Types';
 import { FormulaParseOptions } from './FormulaParser';
@@ -37,13 +37,16 @@ export declare class FormulaCompiler implements IFormulaCompiler {
     private readonly _editing;
     constructor(options?: FormulaCompilerOptions);
     /** @inheritdoc IFormulaCompiler.compile */
-    compile(runtime: IRuntime, rowIndex: number, colIndex: number, expression: string, symbols?: ISymbolRegistry, getFunction?: ((name: string) => IFunction | null) | null, scope?: string | null, formulaTransform?: ICalculation.FormulaTransform): CompiledFormula;
+    compile(runtime: IRuntime, rowIndex: number, colIndex: number, expression: string, symbols?: ISymbolRegistry, getFunction?: ((name: string) => IFunction | null) | null, scope?: string | null, legacyIntersect?: boolean, sheetCtx?: SheetCtx): CompiledFormula;
     /** @inheritdoc IFormulaCompiler.autoCorrect */
     autoCorrect(expression: string): string | null;
     /**
      * The zero-recovery parse-failure result: a compiled formula whose only token is the raw expression
      * as `unparsed`, evaluating to the parse error. Nothing is lost (the text round-trips), nothing is
      * spent — this is the calc profile's entire failure path, and editing's last resort.
+     *
+     * `partialTable` (editing only): an expression that is nothing but a structured reference being
+     * typed (`[@Co`) still gets its table tokens — no prefix parses, so recovery never reaches it.
      */
     private _compileUnparsed;
     /**
@@ -61,9 +64,31 @@ export declare class FormulaCompiler implements IFormulaCompiler {
      * Append the un-parseable `tail` to `tokens` as `unparsed` token(s): stamp the enclosing function
      * context (from the last token that has one) so a caret in the tail still resolves to the right
      * function + argument, and split off a trailing identifier run (`[A-Za-z_][A-Za-z0-9_]*` at a token
-     * boundary, not glued to a preceding digit like `12abc`) as its own `isLookup` token, so a partial
-     * name being typed can still drive autocomplete.
+     * boundary, not glued to a preceding digit like `12abc`) as its own `named` token — what it would
+     * parse as once the rest of the formula does — so a partial name being typed can still drive
+     * autocomplete.
+     *
+     * A tail ending inside a structured reference's brackets (`Sales[Co`) becomes that reference's
+     * tokens instead — see {@link appendPartialStructuredReference}.
      */
     private _appendUnparsedTail;
 }
+/**
+ * Append a structured reference still being typed at the end of `tail` — `Sales[`, `Sales[Co`,
+ * `Sales[#Da`, `Sales[[#This Row],[Co`, `[@Co` — as the tokens it will be once it closes, in the shape
+ * `generateFormulaTokens` gives a complete one: a `tableReference` for the name, `paren` tokens for every
+ * bracket, and a `tableColumn` / `tableSpecifier` per part whose value is an
+ * {@link ICalculation.TablePartRef} naming the table (`''` when unqualified).
+ *
+ * The unfinished part is marked `partial` with what may finish it, and a part not yet started — right
+ * after the `[` or `@` that opened it — is an empty token, so an editor completes from the tokens alone.
+ *
+ * The name may already sit in `tokens` as the `named` token the parsed prefix ended with; it is
+ * re-typed in place. Anything in `tail` before the reference is one `unparsed` token.
+ *
+ * @returns `false`, with `tokens` untouched, when the tail does not end inside a structured reference.
+ */
+export declare function appendPartialStructuredReference(tokens: ICalculation.FormulaToken[], tail: string, context: ICalculation.FormulaTokenContext | undefined, 
+/** The display name of the table at the formula's cell, which an unqualified reference names. */
+homeTable?: () => string | undefined): boolean;
 //# sourceMappingURL=FormulaCompiler.d.ts.map

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

@@ -4,7 +4,6 @@ import { ASTNode, ParseResult } from './ASTTypes';
 import { FormulaLexer, FormulaLexerOptions } from './FormulaLexer';
 import { CompilerLocale } from './CompilerLocale';
 import { SRParser } from './SRParser';
-import { ICalculation } from '../ICalculation';
 declare module 'chevrotain' {
     interface EmbeddedActionsParser {
         getLexerPosition(): number;
@@ -80,7 +79,7 @@ export declare class FormulaParser extends EmbeddedActionsParser {
      * none, so `=_xlfn.SUM(A1)` typed is an unknown name, as in Excel. Runs where the hardcoded
      * legacy visit used to run — no extra parse.
      */
-    parse(rowIndex: number, colIndex: number, expression: string, formulaTransform?: ICalculation.FormulaTransform): ParseResult;
+    parse(rowIndex: number, colIndex: number, expression: string): ParseResult;
     /**
      * Parses a flat sequence of infix-operator / operand pairs, then folds them into a
      * left-associative AST using the precedence table in `ParserUtils.binaryOperatorsPrecedence`.

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

@@ -1,6 +1,13 @@
 import { ICalculation } from '../ICalculation';
 import { ISymbolRegistry } from '../symbol';
 import { ASTNode } from './ASTTypes';
+/**
+ * The public node view of an internal AST — what {@link ICalculation.IFormula.getNode} answers.
+ *
+ * @param root The internal AST root.
+ * @param symbols The registry the AST was linked against.
+ */
+export declare function toFormulaNode(root: ASTNode, symbols: ISymbolRegistry | null | undefined): ICalculation.FormulaNode;
 /**
  * Applies a public {@link ICalculation.FormulaTransform} to an internal AST.
  *
@@ -12,4 +19,14 @@ import { ASTNode } from './ASTTypes';
  * that identity to skip recompilation.
  */
 export declare function applyTransformToAST(root: ASTNode, transform: ICalculation.FormulaTransform, symbols?: ISymbolRegistry | null): ASTNode;
+/**
+ * Walks a lite tree with a transform, post-order, and returns the transformed root: the SAME
+ * object when nothing changed.
+ */
+export declare function transformFormulaNode(root: ICalculation.FormulaNode, transform: ICalculation.FormulaTransform): ICalculation.FormulaNode;
+/**
+ * Rebuilds an AST from a lite tree: nodes a transform left alone come back as the AST nodes they
+ * were made from, replacements are built fresh.
+ */
+export declare function fromFormulaNode(root: ICalculation.FormulaNode): ASTNode;
 //# sourceMappingURL=LiteTransform.d.ts.map

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

@@ -1,4 +1,5 @@
 import { FormulaError, IRange } from '@sheetxl/primitives';
+import { ICalculation } from '../ICalculation';
 import { CompilerLocale } from './CompilerLocale';
 import { ASTNode, ASTVisitor, CellNode, FunctionNode } from './ASTTypes';
 /**
@@ -49,6 +50,21 @@ export declare function createTableReference(value: string, inputs: any[]): ASTN
  * word → canonical. Display re-imaging (`tokensToString`) re-localizes for a localized target.
  */
 export declare function createTableSpecifier(image: string, locale?: CompilerLocale): ASTNode;
+/**
+ * A column name as a structured reference spells it: a `'` before each `[`, `]`, `#` and `'`,
+ * which is Excel's escape inside a column specifier. Without it a name holding a bracket cannot be
+ * referenced at all — the bracket would close the reference.
+ */
+export declare function escapeColumnName(name: string): string;
+/**
+ * The column name a specifier spells — the inverse of {@link escapeColumnName}.
+ *
+ * @remarks
+ * A `'` before anything else is a literal `'`, not a dangling escape: `#` and `'` were referenced
+ * unescaped long before the escape was read, and text written then still has to name the same
+ * column (`[Q#1]` and `[Q'#1]` are both `Q#1`).
+ */
+export declare function unescapeColumnName(image: string): string;
 export declare function createTableColumn(image: string): ASTNode;
 export declare function createInfix(operator: string, left: ASTNode, right: ASTNode, isReference?: boolean): ASTNode;
 export declare function createPostfix(operator: string, input: ASTNode | null | undefined, isReference?: boolean): ASTNode;
@@ -108,11 +124,20 @@ export declare function createRefError(image?: string, locale?: CompilerLocale,
 export declare function createNameError(): ASTNode;
 /**
  * The plain error behind an `error` node/token value, whichever shape it is: an error REFERENCE
- * carries an {@link ICalculation.ErrorRef} (qualifier and all), an error LITERAL the bare
+ * carries an {@link ErrorReference} (qualifier and all), an error LITERAL the bare
  * {@link FormulaError}. Evaluation and precedent resolution want the error itself either way — an
  * `ErrorRef` never escapes the reference layer into a cell value.
  */
 export declare function errorOfValue(value: unknown): FormulaError.Known;
+/**
+ * An `error` node's value as its TOKEN carries it: the error's canonical label for a literal, an
+ * {@link ICalculation.ErrorRef} for a reference. Plain data either way.
+ */
+export declare function errorTokenValue(value: unknown): string | ICalculation.ErrorRef | undefined;
+/**
+ * The error an `error` TOKEN names, from the label it carries ({@link errorTokenValue}).
+ */
+export declare function errorOfTokenValue(value: unknown): FormulaError.Known | undefined;
 /**
  * Does an error token's `text` already carry its sheet qualifier (`Data!#REF!`)?
  *

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

@@ -29,9 +29,10 @@ export declare class SRParser extends EmbeddedActionsParser {
     /**
      * Parses a complete structured reference and returns a ParseResult.
      *
-     * Accepts the full token image in either form:
+     * Accepts the full token image in any of three forms:
      *   '[Column1]'                 — no table name (BracketedString token)
      *   'Table1[#Headers,[Col1]]'   — with table name (TableReference token)
+     *   '[1]!Table1[Col1]'          — with an EXTERNAL book prefix, which belongs to the table NAME
      */
     parse(rowIndex: number, colIndex: number, expression: string): ParseResult;
 }

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).
      */