@sheetxl/sdk 0.8.0-beta.12 → 0.8.0-beta.14

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

@@ -105,54 +105,7 @@ export declare function qualifyStructuredRefs(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:
@@ -192,156 +145,11 @@ export declare const rangesOperators: readonly string[];
  * Used to determine is a node is a range node for writing dynamic arrays to Excel
  */
 export declare const isRangedNode: (node: ASTNode) => boolean;
-/**
- * Finds an implicit-intersection operand that cannot possibly be a reference, or `null` if the
- * formula has none.
- *
- * @param root The root of the formula's AST.
- * @param getFunction Resolves a function's stableId to its declaration, or `null`.
- *
- * @remarks
- * Implicit intersection (the whitespace operator) is defined over LOCATIONS — `A1:A10 B1:B10` is
- * the cells they have in common. Handing it something that computes a value is not a runtime
- * failure, it is a formula that never had a meaning, and Excel refuses the entry outright rather
- * than evaluating it (verified against Excel 16.0 by
- * `spreadsheetbench/formula-tests/probe-space-paren.ps1`, which walks the operand kinds:
- * `INDEX(...)` — reference-returning — is accepted on both sides, `RANDBETWEEN(...)`, `(3)`,
- * `(H1:H5+0)` and `TRUE` are all rejected).
- *
- * This matters most for a formula that LOOKS like a function call: `=SEQUENCE (3)` is not a call at
- * all, because the space keeps the `(` from binding to the name — it is the name `SEQUENCE`
- * intersected with `(3)`. Left to evaluate, the answer depended on what the operands happened to
- * lex as, so one typo produced #NAME?, #REF! or #NULL! for the same mistake.
- *
- * The one place we knowingly diverge from Excel: when the LEFT operand is a built-in function name
- * (`=SUM (H1:H5)`), Excel rejects it because `SUM` is reserved and cannot be a name, while we let it
- * resolve and report #NAME?. Recognizing that case needs a function table at PARSE time, which the
- * parse path has no access to — and "SUM is not a defined name" is an honest answer.
- */
 export declare const findNonReferenceIntersectionOperand: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => ASTNode | null;
-/**
- * Finds a spill-anchor (`#`) operand that cannot possibly be a reference, or `null` if the formula
- * has none.
- *
- * @param root The root of the formula's AST.
- * @param getFunction Resolves a function's stableId to its declaration, or `null`.
- *
- * @remarks
- * The anchor answers "where did the formula anchored HERE put its result", so its operand is a
- * location, never a value — Excel's own declaration is `ANCHORARRAY(Range) -> Range|Array`. An
- * operand that provably computes a value is refused at ENTRY, the same verdict (and the same
- * predicate — {@link isDefinitelyNotReferenceNode}) as the intersection operand beside it.
- *
- * Measured against Excel 16.0 desktop (`spreadsheetbench/formula-tests/probe-anchor.ps1`): `=5#`,
- * `={1,2}#` and `=SUM(X1:X3)#` cannot be typed at all, while a reference-returning call
- * (`=INDEX(X1:X3,1)#`, `=OFFSET(B3,0,0)#`) is accepted. A NAME is accepted too — what it resolves
- * to is not knowable here — and answers `#VALUE!` when it turns out to hold a constant, which is
- * the runtime half of this same rule.
- */
 export declare const findNonReferenceAnchorOperand: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => ASTNode | null;
-/**
- * Finds an array constant whose rows are not all the same length — a JAGGED literal such as
- * `{1,2;3}`.
- *
- * @param root The root of the formula's AST.
- * @returns A human-readable description of the first jagged array, or `null`.
- *
- * @remarks
- * **An array constant is rectangular, or it is not a formula.** Excel refuses a jagged one at
- * ENTRY; it does not pad the short row with `#N/A`. The refusal is about SHAPE alone — neither
- * content nor position changes it. Measured against Excel 16.0
- * (`spreadsheetbench/formula-tests/probe-jagged-array.ps1`): `{1,2;3}`, `{1;2,3}`, `{1,2;3;4,5}`,
- * `{1,2;3,4,5}`, `{"a","b";"c"}`, `{TRUE,FALSE;TRUE}`, `{#REF!,1;2}`, `SUM({1,2;3})`,
- * `SUM(1,{1,2;3})`, `{1,2;3}+1` and `INDEX({1,2;3},1,1)` are all refused, while every rectangular
- * control (`{1}`, `{1,2,3}`, `{1;2;3}`, `{1,2;3,4}`, `{1,2;3,4;5,6}`) is accepted and spills to
- * exactly its written shape.
- *
- * Deciding it HERE rather than at evaluation is the same lesson as `findArityViolation`, and for a
- * sharper reason: accepting a jagged literal is not a harmless superset, because the writer emits
- * whatever parsed. A jagged `<f>` ON DISK makes the workbook UNOPENABLE — Excel declines the whole
- * file rather than repairing the one cell (`probe-jagged-array2.ps1` patches `{1,2;3}` into an
- * otherwise healthy saved sheet, after which `Workbooks.Open` fails outright while the unpatched
- * seed opens fine). So this is a roundtrip guard, not merely entry parity.
- *
- * Reported here rather than in `FormulaParser._ruleLiteralArray` because on an Array node
- * `error` already MEANS "the closing brace was never consumed" — `CompilerUtils`' token emitter
- * suppresses the `}` when it is set. Since a parse-errored formula re-images from its tokens,
- * flagging the node would silently rewrite the user's text to `={1,2;3`.
- */
 export declare const findJaggedArrayLiteral: (root: ASTNode) => string | null;
-/**
- * Finds a call whose ARGUMENT COUNT the declaration cannot accept — too many, or a required
- * parameter with no argument.
- *
- * @param root The root of the formula's AST.
- * @param getFunction Resolves a function name to its declaration; `null` disables the check.
- * @returns A human-readable description of the first violation, or `null`.
- *
- * @remarks
- * Arity is decidable from the AST — argument count from the call, declared arity from the
- * registry — so by the "only the compiler emits `#PARSE!`" rule it belongs here. Excel agrees:
- * `=IMAGE()` with too few arguments cannot be typed in at all.
- *
- * **This is the "when" half of CALC-ISSUES item 29, and it converts a silent failure into a
- * loud one.** Previously arity was checked during EVALUATION (`TypedFunction`'s
- * `RuntimeError.ARGS_TOO_MANY` / `PARAM_MISSING`), which raised `#PARSE!` at calc time —
- * and `#PARSE!` is precisely what `WorksheetEmitter` refuses to write, so the cell was
- * downgraded to a literal string and the formula vanished on save with no warning. Deciding
- * it at compile time surfaces it where the user is typing.
- *
- * It does NOT fix a WRONG declaration: an arity stricter than Excel's still rejects a legal
- * call, just earlier. That is the other half of item 29 and needs the COM sweep. The runtime
- * checks stay as a backstop for paths that never compile (`IFunction.execute`, item 35).
- */
 export declare const findArityViolation: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => string | null;
-/**
- * Finds an argument that is STATICALLY KNOWN to compute a value sitting in a reference-only
- * (`r:'p'`) parameter — `COLUMN(1)`, `OFFSET(ABS(A1),1,1)`, `SUBTOTAL(9,A1+0)`.
- *
- * @param root The root of the formula's AST.
- * @param getFunction Resolves a function name to its declaration; `null` disables the check.
- * @returns The offending argument node, or `null`.
- *
- * @remarks
- * **Excel decides this at ENTRY, and so must we** (measured over 34 operand kinds x
- * `OFFSET`/`COLUMN`, `spreadsheetbench/formula-tests/probe-ref-slot-entry-boundary.ps1`; both
- * outers agree on every row, so this is the SLOT's rule, not one function's validation). Excel
- * has two channels: what it can PROVE is not a reference is refused outright and the formula
- * cannot exist; what it cannot prove is accepted and fails at evaluation with `#VALUE!`. Excel
- * Online persists a refused formula as a literal STRING — measured in a user-authored
- * `error-offset.xlsx`, where `=OFFSET(ABS(a1),1,1)` came back as `<c t="s">` while
- * `=OFFSET(IF(TRUE,1),1,1)` came back as a real `<f>` with a cached `#VALUE!`.
- *
- * Deciding it HERE is what makes that faithful. Previously the runtime guessed from the value's
- * shape and could not tell `IF(TRUE,1)` from a typed `1` once both were the number 1, so it
- * answered `#PARSE!` for a formula Excel accepts — and `#PARSE!` is exactly what
- * `WorksheetEmitter` refuses to write, so the cell was saved as text and the formula was lost.
- *
- * The provability test is the callee's declared RETURN: a scalar return proves it (`ABS`, `SUM`,
- * `IFERROR`), a ranged return does not (`IF`, `CHOOSE`, `INDEX`). Note a ranged return is
- * currently ambiguous between "array" (`SEQUENCE`, `FILTER` — Excel refuses these) and
- * "may be a reference" (`IF`, `INDEX` — Excel accepts), so we are deliberately PERMISSIVE there:
- * those cases keep today's behavioral and stay reachable only by hand, never from an
- * Excel-authored file. Splitting them needs a distinct `unknown` return type (CALC-ISSUES 39).
- */
 export declare const findValueInReferenceOnlySlot: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => ASTNode | null;
-/**
- * Finds a `Call` whose callee is STATICALLY KNOWN to produce a value — `=SUM(2)(3)`, `=3(1)`,
- * `="x"(1)`, `={1,2}(1)`, `=(1+1)(3)` — which Excel refuses at ENTRY.
- *
- * @param root The root of the formula's AST.
- * @param getFunction Resolves a function name to its declaration; `null` disables the check.
- * @returns The first violation's message, or `null`.
- *
- * @remarks
- * The application design's one rule (§3.1, measured over 34 operands run through BOTH slots):
- * the callee slot and the intersection slot share a single predicate — the operand's declared
- * return must not be provably a value. So this is {@link isDefinitelyNotReferenceNode} asked at a
- * `Call` node's `inputs[0]`, nothing more: a lambda-returning declaration passes (`getLambda()`),
- * an untyped one passes (`IF(TRUE,1,2)(3)` is accepted and fails at runtime — the decisive probe
- * row: no flow analysis, no constant folding), a reference passes (`=A1(3)` is a runtime `#REF!`),
- * and only a provable value is refused.
- */
 export declare const findInvalidCallee: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => string | null;
 /**
  * Rewrites every call to an UNKNOWN function into a name application —
@@ -379,41 +187,6 @@ export declare function appendBound(bound: readonly ICalculation.BoundName[] | u
  */
 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.
- * @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.

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

@@ -67,14 +67,6 @@ export declare class FormulaLexer {
     getLocale(): CompilerLocale;
     /** The last valid column (1-based) — `A1`/`AC` beyond it lex as a name, not a reference. */
     getMaxColumn(): number;
-    /**
-     * The last valid row (1-based).
-     *
-     * The cell matcher applies this itself (`A1048577` falls through to a NAME), but a whole-row
-     * operand cannot: a bare digit run lexes as a NUMBER, and only the parser knows it sits beside a
-     * range operator. The parser reads this to bound that conversion — Excel refuses `1:1048577` and
-     * `0:1` outright (`spreadsheetbench/formula-tests/probe-mixed-range-operand4.ps1`).
-     */
     getMaxRow(): number;
     /**
      * The fully-resolved separators this lexer tokenizes with. The parser reads `separatorDecimal`

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

@@ -107,68 +107,7 @@ export declare class FormulaParser extends EmbeddedActionsParser {
      * highest precedence). Were the operand the leaf, `-` would grab `A1` first and leave a stray `:`.
      */
     protected _rulePrefixOp: import('chevrotain').ParserMethod<[], ASTNode<TokenType, any>>;
-    /**
-     * Folds the range operators (`:` range, `.:.` / `.:` / `:.` range-trim) and the spill anchor `#` —
-     * Excel's highest-precedence operators, binding tighter than the unary prefixes (`_rulePrefixOp`).
-     * Left-associative, single level (`A1:B2:C3` = `(A1:B2):C3`); every operator produces a reference
-     * node (`isRange = true`) so the whole span resolves to one reference. This rule sits just above the
-     * `_ruleCallOp` leaf.
-     *
-     * ── Why `#` is folded HERE, with the range operators ─────────────────────────────────────────
-     *
-     * The anchor is a postfix over the reference accumulated SO FAR, not over the primary in front of
-     * it: `A1:B2#` is `(A1:B2)#`, whose operand is a multi-cell reference — `#REF!` in Excel. What a
-     * `#` before the operator anchors is only its own operand, because that is all that has
-     * accumulated yet — `B3#:B1` is `(B3#):B1`, the rectangle spanning B1 and the whole of B3's spill.
-     *
-     * Measured against Excel 16.0 desktop (`spreadsheetbench/formula-tests/probe-anchor.ps1`); the
-     * xlsx round-trip is the unambiguous witness, since the anchor lowers to an explicit call there:
-     *
-     * | typed | value | stored |
-     * | --- | --- | --- |
-     * | `B1:B3#` | `#REF!` | `_xlfn.ANCHORARRAY(B1:B3)` |
-     * | `B11:B3#` | `#REF!` | `_xlfn.ANCHORARRAY(B3:B11)` — re-imaged as `=B3:B11#` |
-     * | `B3#:B1` | B1:B5 | `_xlfn.ANCHORARRAY(B3):B1` |
-     *
-     * Excel ONLINE parses the same text differently — its grammar attaches `#` to the PRIMARY
-     * (`re = q(primary, any(Pound, StructRef), ...)` in the shipped engine), so it reads `A1:(B2#)`.
-     * Desktop wins. (The one desktop form this fold does not reproduce is `B3#:B5#`, which Excel
-     * stores as `ANCHORARRAY(B3):ANCHORARRAY(B5)` while we anchor the accumulation. Both are `#REF!`
-     * — an anchor over a multi-cell reference either way — so only the re-imaged text differs.)
-     */
     protected _ruleRangeOp: import('chevrotain').ParserMethod<[], ASTNode<TokenType, any>>;
-    /**
-     * Function application — `LAMBDA(a,b,a+b)(1,2)`, and the general form it is one instance of: any
-     * expression followed by an argument list. Zero or more suffixes, so a curried lambda
-     * (`LAMBDA(x,LAMBDA(y,x+y))(1)(2)` = `3` in Excel) folds left-associatively.
-     *
-     * This is the tightest-binding construct in the grammar — tighter than the range operators above
-     * it, which is why it sits BELOW `_ruleRangeOp`: `LAMBDA(r,r)(A1:B2):C3` is `(call):C3`. Measured
-     * against Excel 16.0 for `-`, `*`, `%`, `#` and `:` alike
-     * (`spreadsheetbench/formula-tests/probe-lambda-call.ps1`).
-     *
-     * ── The GATE is the whole design ────────────────────────────────────────────────────────────
-     *
-     * The `(` binds as a call ONLY when it touches the callee's last token. Excel refuses
-     * `=LAMBDA(x,x+1) (3)` at entry over a single space, and that adjacency is the ONLY thing
-     * separating application from implicit intersection:
-     *
-     * | typed | Excel |
-     * | --- | --- |
-     * | `A1:B3 (A2:C2)` | `4` — intersection |
-     * | `A1:B3(A2:C2)` | `#REF!` — a CALL whose callee is a range |
-     *
-     * So this gate is the exact complement of `_ruleIntersectOp`'s: that one fires on
-     * `startOffset > endOffset + 1`, this one on `startOffset === endOffset + 1`. No input satisfies
-     * both, and none falls between them. Without it, a greedy call suffix would swallow the second
-     * operand of every parenthesized intersection before `_ruleIntersectOp` ever saw it.
-     *
-     * The callee is deliberately unrestricted. Excel's own restriction is not syntactic — it is a
-     * shallow check on the callee's DECLARED return type, which is why `=IF(TRUE,1,2)(3)` is accepted
-     * (and answers `#VALUE!`) while `=SUM(2)(3)` is refused. That belongs with the sibling check for
-     * intersection operands (`CompilerUtils.findNonReferenceIntersectionOperand`), not here.
-     * See DESIGN-FORMULA-APPLICATION.md.
-     */
     protected _ruleCallOp: import('chevrotain').ParserMethod<[], ASTNode<TokenType, any>>;
     /**
      * Implements the implicit intersection operator: two adjacent reference expressions

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

@@ -14,30 +14,6 @@ export declare function createCell(coords: IRange.FixableCellCoords): CellNode;
 export declare function createCol(address: string, column: number): CellNode;
 export declare function createRow(address: string, row: number): CellNode;
 export declare function createFunction(value: string, inputs: any[] | null | undefined): FunctionNode;
-/**
- * Application of an expression `callee` to `args` — `LAMBDA(a,b,a+b)(1,2)`.
- *
- * The callee goes in `inputs[0]` rather than `value` because **`visitAST` descends `inputs` and
- * never `value`** (see its `walk`). A callee parked in `value` is invisible to every pass built on
- * it, and each of those is a silent wrong answer rather than a crash:
- *
- * - the post-parse visit in `FormulaParser.parse` — `_xlfn.LAMBDA(…)(1,2)` read back from disk
- *   would keep its prefix, because the strip never reaches the callee;
- * - `bindSymbols` — the callee's function name never binds to a stableId;
- * - `translateCellNodes` — a cell inside the callee does not shift on copy/paste or row insert;
- * - precedent collection — `=IF(A1,LAMBDA(x,x),LAMBDA(x,x+1))(2)` never registers `A1` as a
- *   precedent, so editing `A1` leaves a stale value. That one is the decisive case.
- *
- * `value` is also uniformly the node's *scalar* identity everywhere else (a name, an operator, a
- * number, a coords object); a node there breaks that for anything comparing or serializing it.
- *
- * The cost is that argument `i` is `inputs[i + 1]`, unlike {@link createFunction} — use
- * {@link calleeOf} / {@link argsOf} rather than open-coding the offset.
- *
- * Excel models this the same way: its AST has a single `App { head, args }` node and its engine
- * implements immediate invocation as an internal `APPLY` function taking the callee as argument 0
- * (DESIGN-FORMULA-APPLICATION.md §8.1).
- */
 export declare function createCall(callee: ASTNode, args: ASTNode[] | null | undefined): ASTNode;
 /** The callee of a {@link createCall} node. */
 export declare function calleeOf(node: ASTNode): ASTNode | undefined;

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

@@ -246,61 +246,9 @@ export interface CompiledFormula {
      * (add/heal/delete/rename), matched against `IndirectSymbolProvider.reconcile()`.
      */
     symbolIds: string[];
-    /**
-     * Whether the formula calls `SUBTOTAL` or `AGGREGATE` anywhere in its tree.
-     *
-     * @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 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
-     * `getFunction` rather than matched on the typed name, so a localized spelling and an
-     * `_xlfn.`-prefixed one both answer correctly.
-     */
     hasTotals: boolean;
-    /**
-     * Whether the formula calls `TABLE`, the what-if data table, anywhere in its tree.
-     *
-     * @remarks
-     * What a reactive pass under `AutomaticExceptTables` skips (DESIGN-DATA-TABLES §4.4). Resolved
-     * through `getFunction`, like {@link hasTotals}.
-     */
     hasDataTable: 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