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

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,72 @@ 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;
+/**
+ * The formula with every POSITION TEST replaced by `TRUE` and by `FALSE`, in every combination:
+ * what a block's blank-region representative is re-evaluated as to show its answer does not
+ * depend on which cell is asking (`IFormulaBlock.getPositionVariants`).
+ *
+ * @remarks
+ * A position test is a maximal subtree that reads the position (`ROW()`, `COLUMN()`) and is
+ * BOOLEAN at every cell, never an error: a comparison of position arithmetic with a literal
+ * (`ROW()>1`, `MOD(ROW(),2)=0`), `ISODD`/`ISEVEN` of it, and `NOT`/`AND`/`OR`/`XOR` of tests. Its
+ * value at any cell is `TRUE` or `FALSE`, so when the formula answers alike for every combination,
+ * the position cannot change the answer.
+ *
+ * `null` — nothing to vary — when the formula has no position test, more than
+ * {@link MAX_POSITION_TESTS}, a lazy argument (an `IF` arm a variant takes could read what the
+ * formula itself never did), or a `LET`/`LAMBDA` binding.
+ */
+export declare function positionVariants(root: ASTNode, getFunction: ((name: string) => IFunction | null) | null | undefined): ASTNode[] | null;
 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}.
@@ -279,35 +369,52 @@ export declare const findInvalidCallee: (root: ASTNode, getFunction: ((name: str
  */
 export declare function rewriteUnknownFunctionCalls(root: ASTNode, getFunction: ((name: string) => IFunction | null) | null): ASTNode;
 /**
- * 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.
+ * `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'];
+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 (post read-transform, pre {@link linkSymbols}).
+ * @param root The parsed AST.
  * @param getFunction Resolves a function name to its declaration; see {@link _binderKind}.
- * @returns A new root, or the SAME root when nothing is bound (copy-on-write).
+ * @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
- * **Runs before {@link linkSymbols}, and that is the point.** A bound node is claimed here, so no
- * `NamedFormula` symbol is minted for it, no dependency edge is drawn, and no dead id is left
- * behind: a parameter is not a name. The node stays a `named` node — the public lite view (and so
- * io-xlsx's `_xlpm.` spelling) is unchanged — but it stops being a REFERENCE and reads its value
- * from its binding rather than from the resolver.
- *
- * Declaration positions are purely syntactic, the same rule io-xlsx's `_prefixScopeParameters`
- * proved on the lite tree:
- * - `LAMBDA` — every argument except the last declares; the last is the body.
- * - `LET` — the even-indexed arguments except the last declare, the odd ones are their values, and
- *   the last is the body.
- *
- * Binding ORDER is the one rule the shape does not give away, and it is measured: a `LET` name is
- * in scope only from the argument AFTER its own value, so the same spelling in an earlier one is
- * the outer / defined name — `LET(zz,zz,zz)` binds only the third `zz`.
- *
- * Shadowing needs no special case: the environment is a stack and a use takes the INNERMOST
- * binding, so an inner scope's name wins over an outer one's, and a parameter wins over a defined
- * name (it never reaches the resolver at all).
+ * `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 function bindScopes(root: ASTNode, getFunction?: ((name: string) => IFunction | null) | null): ASTNode;
+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.
  *
@@ -318,29 +425,30 @@ export declare function bindScopes(root: ASTNode, getFunction?: ((name: string)
  * @remarks
  * Same channel and same reason as {@link findArityViolation}: Excel decides these before the
  * formula can exist, so we do too — a refused shape is a parse error, not a cell that evaluates to
- * something. Read from the shipping Excel Online analyzer
- * (`d:/dev/excel-calc-ref/excelOnlineCalc.min.js`, `applySpecificWorksheetFunctionChecks`), which
- * reports `Duplicate_binder` / `Invalid_binder` / `Missing_binder` per declaration and
- * `Insufficient_function_arguments` with `numArgsExpected: max(3, n + 1 + n % 2)` for `LET` — the
- * `n % 2` term being exactly the even-argument-count refusal.
- *
- * Duplicates compare case-INSENSITIVELY (Excel keys them in a `stringCompareCI` map), the same
- * normalization a name comparison gets everywhere else.
+ * something. Excel refuses a duplicate, invalid or missing binder per declaration, and a `LET`
+ * with too few arguments — at least `max(3, n + 1 + n % 2)` for `n` arguments, the `n % 2` term
+ * being exactly the even-argument-count refusal.
+ *
+ * Duplicates compare case-INSENSITIVELY, the same 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,37 @@ 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;
+/** The canonical specifier words a structured reference accepts — the text inside `[#…]`, minus the `#`. */
+export declare const CANONICAL_SPECIFIER_WORDS: readonly string[];
+/**
+ * The section (`StructuredReference.spec`) a structured reference's specifiers designate.
+ */
+export declare function structuredReferenceSpec(all: boolean, headers: boolean, data: boolean, totals: boolean): number;
+/**
+ * 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;
+/**
+ * The table reference starting at `startOffset` — `Table1[Col]`, `[1]!Table1[Col]` — as a one-element
+ * match, or `null`. The formula lexer's matcher for the token, and the address parser's.
+ */
+export declare function matchTableReference(text: string, startOffset: number): [string] | null;
+/**
+ * The outermost bracketed string starting at `startOffset` — `[Workbook]`, an unqualified `[Col]` —
+ * as a one-element match, or `null`.
+ */
+export declare function matchBracketedString(text: string, startOffset: number): [string] | null;
 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 +140,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`, `positionRead`) 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).
      */