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

package/types/src/calculation/executor/CalcExecutor.d.ts

@@ -1,4 +1,4 @@
-import { IRange, IFormulaContext } from '@sheetxl/primitives';
+import { IRange, Scalar, IFormulaContext } from '@sheetxl/primitives';
 import { FixedPackedArray } from '../../primitives/PrimitiveUtils';
 import { PendingOverlayGrid } from '../state/_PendingOverlayGrid';
 import { ISpatialMap, ISpatialMap3D } from '../../collections';
@@ -6,21 +6,20 @@ import { FormulaSpatialValue, PrecedentSpatialValue, PrecedentKind } from '../sp
 import { ICalcGrid, CalcGridBackend } from '../grid';
 import { IContextContainer, CalcNode } from '../state';
 import { ReadHook } from '../state/_ReadObservedGrid';
+import { DeferredCall } from '../state/DeferredCalls';
+import { AsyncValue } from '../../primitives/AsyncValue';
+import { WhatIfTable } from './_WhatIf';
+import { WhatIfLayer } from '../state/_WhatIfLayer';
 import { CircularReference, CycleHost } from './CircularReference';
 /**
  * Executes a calculation cycle: collect → mark-and-plan → evaluate.
  *
- * Owns cycle counters, the async-recalc pending queue, and all transient
- * per-pass state. `Calculation` is the controller that owns persistent spatial
- * state; CalcExecutor receives snapshots and returns results.
+ * Owns cycle counters and all transient per-pass state. `Calculation` is the controller that
+ * owns persistent spatial state; CalcExecutor receives snapshots and returns results.
  */
 export declare class CalcExecutor {
     protected _container: IContextContainer;
     protected _context: IFormulaContext;
-    private readonly _requestCalculate;
-    protected _pendingCalcs: Map<CalcNode, number>;
-    /** Debounced drain of {@link _pendingCalcs} into the volatile set; one instance for the executor's lifetime. */
-    private readonly _flushPendingCalcs;
     /**
      * The last pass's circular roster: every node it evaluated by demand (a `doMarkAndPlan` that
      * could not order, or the iteration guard's hand-over) plus every node whose dynamic read
@@ -91,6 +90,15 @@ export declare class CalcExecutor {
     protected _deferredLength: number;
     /** The pass the hook answers for; inert otherwise. Set by `doMarkAndPlan`, released with `_gridUpdates`. */
     protected _passActive: boolean;
+    /** The pass in progress is a settle pass (`ExecuteOptions.settle`): its seeds are the settles' alone. */
+    protected _settlePass: boolean;
+    /** The pass a load owes: see {@link _savedAnswer}. */
+    protected _loadPass: boolean;
+    /**
+     * The holder {@link _takeDeferred} made for an evaluation whose value is a range: the value keeps
+     * its shape for the spill layout, which puts the holder on the spill's entry. Taken at once.
+     */
+    protected _spillHolder: AsyncValue<DeferredCall> | null;
     protected _passCycleId: number;
     protected _passMarkId: number;
     /**
@@ -105,13 +113,14 @@ export declare class CalcExecutor {
      * while a pass evaluates. Released with {@link _flush}.
      */
     _overlays: Map<string, PendingOverlayGrid> | null;
+    _whatIf: Map<string, WhatIfLayer> | null;
     /**
-     * The blank regions of the blocks whose representative could not stand for them this plan
-     * (PLAN-WATCHES-BLANK-AWARE §4), and the cells of the regions that WERE shared whose value the
-     * share moved under a reader ({@link _dirtyBlankReaders}) — handed to `doEvaluate`'s incremental
-     * dirty set at the end of the plan, so the next iteration of the pass collects the first cell
-     * by cell and the readers of the second.
+     * A reactive pass under `AutomaticExceptTables`: a `TABLE` node is not evaluated, and is left
+     * dirty ({@link _skippedTables}). Set for the length of `execute`.
      */
+    protected _exceptTables: boolean;
+    /** The `TABLE` nodes the pass in progress skipped, for `ExecuteResult.skippedTables`. */
+    protected _skippedTables: Set<CalcNode>;
     protected _fallbackDirty: ISpatialMap | null;
     /**
      * The cycle table (design §7.3): per cycle id, one live {@link CircularReference} holding the
@@ -193,20 +202,9 @@ export declare class CalcExecutor {
     protected _planMemos: [CalcExecutor.PlanMemo, CalcExecutor.PlanMemo];
     /** The memos' LRU clock. Its own counter, NOT `PlanStats.passes`: a stats reset must not reorder the slots. */
     protected _planMemoClock: number;
-    /**
-     * Nodes with an async promise in flight. Per executor, NOT module scope — module scope would
-     * cross-pollute workbook instances (undo to 0 formulas needs to clear these; TODO - revisit
-     * how we manage promises).
-     */
-    protected _pendingPromises: Set<CalcNode>;
     _gridUpdates: Map<string, ICalcGrid.IncrementalUpdates> | null;
     _addDynamicPrecedent: ((node: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind) => void) | null;
-    constructor(container: IContextContainer, context: IFormulaContext, requestCalculate: () => void);
-    /**
-     * Called when an async formula promise resolves. Adds the node to the pending
-     * queue and debounces a new calculation cycle via `requestCalculate`.
-     */
-    scheduleRecalculation: (cycleId: number, calcNode?: CalcNode) => void;
+    constructor(container: IContextContainer, context: IFormulaContext);
     /**
      * Runs a full calculation pass.
      *
@@ -217,23 +215,15 @@ export declare class CalcExecutor {
      */
     execute(cycleId: number, options: CalcExecutor.ExecuteOptions, state: CalcExecutor.ExecuteState): CalcExecutor.ExecuteResult | null;
     /**
-     * The read hook of a pass (DESIGN-CIRCULAR-CALC.md §4.3, §5), shared by both paths: armed for
-     * every reference while a node is evaluated by demand, and for dynamic-branch references
-     * (`OFFSET`/`INDIRECT`/`INDEX` results) on the ordinary path. A read that lands on a node of
-     * THIS pass decides: `Waiting` (on the in-progress stack — transitively waiting on the reader)
-     * is a cycle; `Unevaluated` suspends the reader until it is done; `Evaluated` (in the pending
-     * batch) is committed on the spot and read; `Done` with a cycle role makes the reader
-     * downstream. Any other cell is a value. Inert outside a pass, so a reference built during one
-     * and read later (a spill committed afterwards) is plain values.
-     *
-     * `prefetch` is the rectangle an ITERATION was asked for, announced before its first read. Only
-     * the `Unevaluated` decision belongs to it — bringing what the sweep may need forward is free,
-     * and over-eager is harmless (design §4.3) — while `Waiting` and a finished cycle role are left
-     * to the per-position reports the sweep makes, which is what stops an early-exit lookup from
-     * reporting the tail it never opened (plan item 1). It answers whether those reports can say
-     * anything at all: a rectangle holding no node of this pass and nothing the sheet shows in a
-     * cycle is swept unobserved.
+     * What a cell answers with instead of the calls its evaluation just made, on the pass a load owes:
+     * the value it was saved with, which is the cached answer until something asks the source. `undefined`
+     * when it should ask: the file marks it to calculate on load, nothing was saved, what was saved is
+     * not an answer (`#BUSY!`, a blocked spill), or the function is volatile.
      */
+    protected _savedAnswer(node: CalcNode): Scalar | IRange | undefined;
+    protected _takeDeferred(node: CalcNode, value: any): any;
+    /** The cells of the `TABLE` nodes the pass skipped, scoped; `undefined` for none. */
+    private _takeSkippedTables;
     private _onPassRead;
     /**
      * A read of a `Done` cycle node by the node being evaluated: the reader is downstream of that
@@ -298,27 +288,6 @@ export declare class CalcExecutor {
      * slot `length` on; returns the new length.
      */
     private _collectUnevaluated;
-    /**
-     * Evaluates `worklist` by demand (DESIGN-CIRCULAR-CALC.md §4.3): each node is evaluated with the
-     * read hook armed; a read that lands on one not yet evaluated suspends the reader and evaluates
-     * that one first (`NeedsFirst`); a read that lands on one already suspended — waiting,
-     * transitively, on the reader — is a cycle (`Circular`), and the in-progress stack from it up
-     * to the reader are the members, written `0`. A node that reads a member is downstream and
-     * writes `0` too. Everything else simply computes: an unorderable static edge that is never
-     * read (`OFFSET`'s anchor, `ROW`'s argument, an untaken `IF` branch) makes no cycle.
-     *
-     * @remarks
-     * Two callers: `doEvaluate` when the plan reaches the nodes `doMarkAndPlan` could not order
-     * (the batch, after everything ordered is committed), and `doEvaluate` again for a single
-     * ordered node whose dynamic read landed on a node not yet evaluated — the same suspension,
-     * on the ordinary path (§5). Every node evaluated here is flagged `circular`, so the plan
-     * takes its `demandValue` when it reaches it, and its finalized scalar is already in the
-     * overlay's demand layer for later lazy reads (`_pushDemand`); `flush` commits the ordered
-     * path's pending batch when a read needs a value still sitting in it. Flat: the stack is an
-     * array, so a 1,560-row chain is 1,560 evaluations, not 1,560 JS frames. A node is retried at
-     * most once per `NeedsFirst` it raises, and with the prefetch of its static precedents that is
-     * normally once.
-     */
     protected doDemandEvaluate(cycleId: number, getUpdates: (scope: string) => ICalcGrid.IncrementalUpdates, worklist: readonly CalcNode[], flush: () => void): void;
     /**
      * The finalized scalar goes into the overlay's demand layer now, so a later lazy read sees it;
@@ -332,6 +301,8 @@ export declare class CalcExecutor {
      * `flush` of the `doEvaluate` that made it, and only that one.
      */
     private _overlayFor;
+    evaluateWhatIf(table: WhatIfTable): Scalar[][];
+    private _evaluateWhatIf;
     /**
      * A finalized result fitted to its cell when the block makes every cell its own 1x1
      * array-entered extent (`FormulaSpatialValue.arrayFirstCell`): element `[0,0]` of a range, so the
@@ -349,30 +320,6 @@ export declare class CalcExecutor {
      * arm it skipped), all of it final by now, so it is evaluated without the pass's read hook.
      */
     private _isPositionFree;
-    /**
-     * The representative of a gated block has finalized (PLAN-WATCHES-BLANK-AWARE §4): its scalar is
-     * shared with the block's blank region, or the gate is closed and the region is re-collected
-     * cell by cell.
-     *
-     * @remarks
-     * Shared only when nothing the evaluation read was per cell (`CalcScope.perCellRead`: a draw, a
-     * computed reference; a position unless {@link _isPositionFree} rules it out), the result is a
-     * scalar, and the node ran on its own - not a promise, not pending on one, not in a cycle. A
-     * per-cell read is a fact of the formula and
-     * closes the gate for good ({@link FormulaSpatialValue.blankRefused}); the rest may not recur
-     * and close it for this pass ({@link _fallbackBlank}).
-     *
-     * How the region is shared depends on who can read it (§4c). A block in a SHEET grid is read
-     * by other formulas, the sheet and the error index, all through the grid's values, so the
-     * scalar is written as runs - one per column of each blank rectangle, which for a column block
-     * is one run. A block in a grid that SHADOWS a sheet (a watch body, a one-shot evaluation) has
-     * exactly one reader, the range its owner holds, and that range answers the region as its empty
-     * value from the block (`FormulaSpatialValue.getBlankValueWithin`): nothing is written, whatever
-     * the region's size, and what an earlier pass stored there is removed so the block's answer is
-     * the one read.
-     *
-     * @param refuse The caller's own reasons the result cannot stand for the region.
-     */
     private _finalizeRepresentative;
     /**
      * Marks dirty the cells of a shared blank region whose value the share just moved, wherever a
@@ -460,29 +407,6 @@ export declare class CalcExecutor {
      * them run on (iteration on). Returns the stack index of `read`.
      */
     private _markCycleSlice;
-    /**
-     * Iterative calculation (design §6.3) over the members {@link _demandRun} marked. Each sweep
-     * evaluates them in ADDRESS order, each read seeing the latest value (Gauss–Seidel in row-major
-     * order, as Excel: `probe-iterative.ps1`), until no member moved by `maxChange` or
-     * `maxIteration` sweeps ran.
-     * The limits are global, as in Excel — one unsettled member keeps every cycle of the pass
-     * sweeping. Downstream nodes read the members once more afterwards; one that feeds a swept node
-     * is swept with them instead (`_onMemberRead`), so the rest feed no cycle and need no sweeping.
-     * Converged means a sweep over a list that did not grow moved nothing by `maxChange`: every
-     * node a swept node reads is then swept itself or does not move in this pass, so the state is a
-     * fixed point and not a fragment's. The members are then registered as volatile so the next
-     * recalculation re-runs them, which is how `=A1+1` advances per recalc (Excel re-iterates every
-     * cycle on every `Calculate()`).
-     *
-     * @remarks
-     * The evaluation that FOUND the members ran in dependency order — `B1 = B2+1` needs `B2` first,
-     * whichever of the two the plan reached first — so its results are not a sweep of this order,
-     * and counting them as one costs a step. The members go back to the values the pass found them
-     * at; a member that had none is then evaluated once, in address order, for the entry evaluation
-     * Excel gave it when it was written (§2.4), and every one of the `maxIteration` sweeps runs on
-     * top of that. Discovery's results are never read: a node that read a member is downstream, and
-     * evaluates again below.
-     */
     private _demandSweep;
     /** Clears the `IterHit` flags of the hits not consumed by {@link _demandRun}'s loop and empties the list. */
     private _drainIterHits;
@@ -520,7 +444,7 @@ export declare class CalcExecutor {
      * A `CalcNode` is a plain graph object reachable by identity long after the grid has replaced or
      * dropped its block — the same hazard `doCollectVolatileCalcs` guards against with `isLiveBlock`.
      */
-    protected isLiveNode(node: CalcNode): boolean;
+    isLiveNode(node: CalcNode): boolean;
     /**
      * @internal
      * A copy of the last pass's circular roster — see {@link _circularNodesLength} — each node
@@ -565,6 +489,8 @@ export declare class CalcExecutor {
      * Uses Kahn's algorithm.
      */
     doMarkAndPlan(cycleId: number, markId: number, initial: FixedPackedArray<CalcNode>, plan: FixedPackedArray<CalcNode>, forceDemand?: boolean): boolean;
+    /** Stamps a plan as the order later passes may take a subset of (§1.2); `orderedLength` is where its demand appendix starts. */
+    private _stampPlan;
     /**
      * The remembered plan whose seed set is exactly this pass's, at this epoch — or `null`. The
      * length check first: it is what rejects the common miss (a single-cell pass against a bulk
@@ -587,7 +513,7 @@ export declare class CalcExecutor {
      * one if there is one, else the least recently used.
      */
     private _rememberPlan;
-    doEvaluate(cycleId: number, getUpdates: (scope: string) => ICalcGrid.IncrementalUpdates, scheduleRecalculation: (cycleId: number, calcNode?: CalcNode) => void, commit: (calcNodes: CalcNode[], calcNodesLength: number) => void, forceFull: boolean, plan: FixedPackedArray<CalcNode>): ISpatialMap | undefined;
+    doEvaluate(cycleId: number, getUpdates: (scope: string) => ICalcGrid.IncrementalUpdates, commit: (calcNodes: CalcNode[], calcNodesLength: number) => void, forceFull: boolean, plan: FixedPackedArray<CalcNode>): ISpatialMap | undefined;
 }
 export declare namespace CalcExecutor {
     /** Per-pass options derived from ICalculation.CalculateOptions */
@@ -603,10 +529,19 @@ export declare namespace CalcExecutor {
          * The grid to seed the pass FROM — `ICalculation.CalculateOptions.scope`, i.e. "Calculate Sheet".
          */
         scopeGridId?: string;
+        settle?: boolean;
+        /**
+         * `ICalculation.CalculateOptions.external`: the calls the pass makes fetch past the workbook's
+         * cache, to the source.
+         */
+        external?: boolean;
+        /** The pass a load owes: a cell with a saved value answers with it rather than asking the source. */
+        load?: boolean;
         /**
          * Iterative calculation (design §6.3) for the pass; `null`/absent with it off.
          */
         iterate?: IterateOptions | null;
+        exceptTables?: boolean;
     }
     /** The two limits of `ICalculation.IterativeCalculation`. */
     interface IterateOptions {
@@ -692,12 +627,9 @@ export declare namespace CalcExecutor {
         /** Discovery searches skipped (or verified) because `dependentsEpoch` was current. */
         dependentsCacheHits: number;
         dependentsCacheMisses: number;
-        /**
-         * Nodes evaluated on the ORDERED path (`evaluateAt` from `doEvaluate`); `evaluations` counts
-         * the demand path. Their sum is every formula run — what blank-aware evaluation
-         * (PLAN-WATCHES-BLANK-AWARE §4) reduces to the touched cells plus one.
-         */
         evaluated: number;
+        /** Plans ordered by formula block, with no cell-level walk (`orderByBlocks`). */
+        blockOrdered: number;
         discoveryMs: number;
         inDegreeMs: number;
         kahnMs: number;
@@ -708,6 +640,8 @@ export declare namespace CalcExecutor {
         precedentSpatial: ISpatialMap3D<PrecedentSpatialValue>;
         dynamicByBlock: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>;
         lastUpdates: Map<string, ICalcGrid.IncrementalUpdates>;
+        /** The cells of the `TABLE` nodes an `exceptTables` pass skipped, scoped: still out of date. */
+        skippedTables?: IRange.Coords[];
     }
 }
 //# sourceMappingURL=CalcExecutor.d.ts.map

package/types/src/calculation/executor/CalcExecutorUtils.d.ts

@@ -1,5 +1,5 @@
 import { IRange, Scalar } from '@sheetxl/primitives';
-import { Tuple, ISpatialMap } from '../../collections';
+import { Tuple, ISpatialMap, ISpatialQuery } from '../../collections';
 import { CalcSignal } from '../../primitives/CalcSignal';
 import { CalcNode } from '../state';
 import { PrecedentSpatialValue, FormulaSpatialValue } from '../spatial';
@@ -45,27 +45,62 @@ export declare function rangeToTuples(range: IRange, offsetMajor?: number, offse
  * is the packing, and the result reads its grid alone. Anything else is returned as it is.
  */
 export declare function packForReturn<T>(finalized: T): T;
-/**
- * Fits a result to a fixed (array-entered) extent, per dimension: a dimension of 1 broadcasts, a
- * longer one is clipped, a shorter one is padded with `#N/A`. Measured against Excel
- * (`probe-cse.ps1`): `=SEQUENCE(5)` into 3 rows is `1,2,3`; `=SEQUENCE(2)` into 5 rows is
- * `1,2,#N/A,#N/A,#N/A`; `=SUM(H1:H5)` into 3x3 is the sum nine times; a 1x3 into 3x3 repeats the
- * row; a 3x1 into 3x3 repeats the column.
- *
- * @returns The fitted values, row-major, exactly `rowCount` x `colCount`. A blank source cell stays
- * blank (`null`), as it does when a dynamic array spills. The fit is a fixed point - fitting the
- * result again yields the same shape - so nothing downstream needs a "do not resize" guard.
- */
 export declare function fitToExtent(value: Scalar | IRange, rowCount: number, colCount: number): Scalar[][];
 /**
  * {@link fitToExtent} as grid tuples over `coords`, in the orientation of the grid they are written
  * to. `null` when every fitted cell is blank.
  */
 export declare function fitToTuples(value: Scalar | IRange, coords: IRange.Coords, isColumn: boolean): Tuple.Region<Scalar> | null;
+/**
+ * Visits, for every precedent entry that reads into `region`, the window of its block whose cells
+ * can see the region - the discovery step of a dirty walk (`CalcExecutor.doCollectDirtyCalcs`)
+ * and of a data table's affected set (`_WhatIf`).
+ *
+ * @remarks
+ * An entry spans the REFERENCED region, which may be larger than the block (a relative reference
+ * is widened per block cell), so the region is mapped back through that overflow to the block's
+ * own coordinates. An anchored endpoint sits at the same coordinate for every cell of the block,
+ * so it stops bounding which cells saw the change - that side opens to the whole block. The END
+ * endpoint bounds the near side, the START endpoint the far side (see `PrecedentSpatialValue`).
+ * A dynamic entry (`index < 0`) has no extent to map: it is reported whole.
+ *
+ * @param scratch An array the search fills; the caller's, reused across calls.
+ */
+export declare function visitReaderWindows(precedentSpatial: ISpatialQuery<PrecedentSpatialValue>, region: IRange.Coords, scratch: ISpatialMap.Entry<PrecedentSpatialValue>[], visitWindow: (block: FormulaSpatialValue, rowFrom: number, rowTo: number, colFrom: number, colTo: number) => void, visitDynamic: (entry: ISpatialMap.Entry<PrecedentSpatialValue>, block: FormulaSpatialValue) => void): void;
+/**
+ * Whether every cell of a static entry's block reads exactly one cell through it.
+ *
+ * @remarks
+ * Only such a reader looks at what a precedent pushes. A range reader builds its range when it
+ * evaluates, over that same slot. A reader this answers `false` for and that does read one cell (the
+ * first of `$A$1:A1`, whose range grows from there) has an empty slot, and reads the cell itself.
+ */
+export declare function readsOneCell(depEntry: ISpatialMap.Entry<PrecedentSpatialValue>): boolean;
 /**
  * TODO - document and/or rationalize with visitPrecedentBlock
  */
 export declare function visitDependencyBlock(depEntry: ISpatialMap.Entry<PrecedentSpatialValue>, rowIndex: number, colIndex: number, callbackFn: (calc: CalcNode) => void, mint?: MintWindow | null): void;
+/** The part of a reader block an entry has reached so far in one discovery, absolute and closed. */
+export interface ReachedWindow {
+    rowFrom: number;
+    rowTo: number;
+    colFrom: number;
+    colTo: number;
+}
+/**
+ * {@link visitDependencyBlock} for discovery, which only has to reach each reader once.
+ *
+ * @remarks
+ * Every cell of a range reports to the same readers, so a running total reached from each of its n
+ * inputs would walk n²/2 readers to find one input's worth. What an entry has reached is kept in
+ * `reached` for the discovery, and each visit walks only what it adds: nothing for a running total
+ * after its first input, one reader per input for a sliding window. A window that does not meet what
+ * is held is walked whole, and the larger of the two is kept; that only costs a repeat, since
+ * reaching a reader twice changes nothing.
+ *
+ * An entry whose readers read one cell has one reader per input, and nothing to save.
+ */
+export declare function discoverDependencyBlock(depEntry: ISpatialMap.Entry<PrecedentSpatialValue>, rowIndex: number, colIndex: number, callbackFn: (calc: CalcNode) => void, mint: MintWindow, reached: Map<PrecedentSpatialValue, ReachedWindow>): void;
 /**
  * Visit the cells of a dependent block that read a spill's BODY — the extent an anchor at
  * (`anchorRow`, `anchorCol`) occupies, MINUS the anchor cell itself.

package/types/src/calculation/executor/CircularReference.d.ts

@@ -13,23 +13,6 @@ export interface CycleHost {
     /** The sheet name for a grid id, or `undefined` for a virtual grid (a named formula's body). */
     resolveScope(gridId: string): string | undefined;
 }
-/**
- * One reference cycle (DESIGN-CIRCULAR-CALC.md §7.3): the executor's record of it and its public
- * face in one — the object a `Feature.Circular` region carries as its payload and
- * `ICell.getCircularReference()` answers. It holds the nodes the sheet index currently shows as
- * its members and as downstream of it, the interned index payloads, and how the sweep that
- * settled it ended. It persists across passes — a node moves between cycles when a commit writes
- * its delta (`_trackCircular`) — and is dropped when its last node leaves.
- *
- * @remarks
- * Every read filters through {@link CycleHost.isLiveNode}: a pass that deletes the offending
- * formula never plans, so the sets cannot clear themselves, and a member is counted only while
- * its cell still holds the block the cycle was found in (design §7.3, trap 5).
- *
- * The iteration answers come from the sweep that settled the cycle (design §6.3). A cycle id is
- * minted by the pass that finds it, so a cycle evaluated with iteration off is a different object
- * with no record — `isIterative()` is exactly "a sweep settled this one".
- */
 export declare class CircularReference implements ICalculation.ICircularReference {
     protected readonly _host: CycleHost;
     protected readonly _cycleId: number;

package/types/src/calculation/executor/_BlockOrder.d.ts

@@ -0,0 +1,29 @@
+import { ISpatialMap3D } from '../../collections';
+import { FormulaSpatialValue } from '../spatial';
+import { CalcNode } from '../state';
+/**
+ * Orders a pass by formula block rather than by cell.
+ *
+ * @remarks
+ * A range reader adds an edge per cell it reads, so ordering a running total cell by cell visits
+ * n²/2 edges to learn that one column goes before another. A block's references are the same at
+ * every cell at that cell's offset, so its reads are known from its corners, and the block graph is
+ * as many vertices as the sheet has distinct fills.
+ *
+ * Every edge between cells lies inside an edge between their blocks, so a block order that exists
+ * is a valid cell order. Within a block the cells go in row order or column order, whichever puts
+ * everything the block reads of itself first. The block graph can refuse an order the cells have
+ * (`A1=B1`, `B1=A2`, filled down: each column reads the other); that answer is `false`, and is not
+ * a statement about cycles. Cell-level ordering decides those.
+ *
+ * Inputs and spills are the caller's: a spill's body edges are not in a block's references, and a
+ * reader of a cycle shown elsewhere is found by the cell-level walk.
+ *
+ * @param nodes The affected nodes.
+ * @param length The number of affected nodes.
+ * @param formulas The formula map the references resolve against.
+ * @param out Receives the nodes in order. Written over on `false` as well.
+ * @returns Whether `out` is a valid order.
+ */
+export declare function orderByBlocks(nodes: CalcNode[], length: number, formulas: ISpatialMap3D<FormulaSpatialValue>, out: CalcNode[]): boolean;
+//# sourceMappingURL=_BlockOrder.d.ts.map

package/types/src/calculation/executor/_WhatIf.d.ts

@@ -0,0 +1,31 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { CalcNode, IContextContainer } from '../state';
+import { WhatIfLayer } from '../state/_WhatIfLayer';
+export interface WhatIfTable {
+    gridId: string;
+    /** The top-left result cell: where the `TABLE` formula sits. */
+    row: number;
+    col: number;
+    rows: number;
+    cols: number;
+    /** The cell the row axis values go into; `null` for a one-input table down a column. */
+    rowInput: IRange.CellCoords | null;
+    /** The cell the column axis values go into; `null` for a one-input table along a row. */
+    colInput: IRange.CellCoords | null;
+}
+/** What the what-if evaluation asks of the executor it runs inside. */
+export interface WhatIfHost {
+    readonly container: IContextContainer;
+    /**
+     * Evaluates `node` where it sits, every read answered through the installed what-if layers: the
+     * cell's finalized value, a range for a spill.
+     */
+    evaluate(node: CalcNode): Scalar | IRange;
+    /** The layer of a grid, made on first use over what the grid reads as now. */
+    layerFor(gridId: string): WhatIfLayer;
+}
+/** The rectangles of a table's edge: the formula cells, then the axes. All on the table's grid. */
+export declare function whatIfEdge(table: WhatIfTable): IRange.Coords[];
+export declare function whatIfAffectedSet(container: IContextContainer, table: WhatIfTable): CalcNode[];
+export declare function runWhatIf(host: WhatIfHost, table: WhatIfTable, affected: readonly CalcNode[]): Scalar[][];
+//# sourceMappingURL=_WhatIf.d.ts.map

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

@@ -80,6 +80,8 @@ export declare class FormulaBlock implements IFormulaBlock {
     getReferencedSymbolIds(): string[];
     /** @inheritdoc IFormulaBlock.hasTotals */
     hasTotals(): boolean;
+    /** @inheritdoc IFormulaBlock.hasDataTable */
+    hasDataTable(): boolean;
     /** @inheritdoc IFormulaBlock.hasVolatile */
     hasVolatile(): boolean;
     /** @inheritdoc IFormulaBlock.isBlankCacheable */
@@ -174,36 +176,8 @@ export declare class FormulaBlock implements IFormulaBlock {
      * shared named-body block at every level, and only a copy keeps an outer activation's captured
      * environment intact underneath it. See `LambdaValue`.
      */
-    /**
-     * Fills the shared argument buffer for a call that has at least one LAZY argument, deciding per
-     * call whether to defer at all.
-     *
-     * @remarks
-     * The engine declines whenever an eager argument is a CONTAINER, because the call is then about
-     * to LIFT: the body runs once per element and different elements may select different arms, so
-     * every arm is needed. Excel abandons laziness there too — `=IF(B1:B3>0,1,A1+1)` in A1 IS a
-     * circular reference where the scalar-condition form is not (measured, `probe-lazy-args.ps1`).
-     *
-     * A declined argument is evaluated ONCE, here, and handed over as the VALUE rather than as a
-     * filled handle: the lift SAMPLES an arm per element (`IF(A1:A5>2,A1:A5,0)` answers element by
-     * element), and only the marshaller can sample it. The handle it hands the body is rebuilt there,
-     * around the sampled member. So the arm is evaluated once and indexed, never re-evaluated.
-     *
-     * Deferring evaluates nothing, so nothing can re-enter `_reuseArgs` while it is being filled.
-     * The decline path does evaluate, and takes a private array for exactly that reason.
-     */
     protected _fillLazyArgs(argsIndexed: ASTNode[], argsLength: number, regs: any[], frame: ReadonlyMap<number, any> | null, row: number, column: number, depth: number): void;
     protected _createLambdaValue(node: FunctionNode, regs: any[], frame: ReadonlyMap<number, any> | null, row: number, column: number): LambdaValue;
-    /**
-     * The callee verdicts + apply for a `Call` node (design §3.4, §1.1):
-     *
-     * - a lambda value → arity check, bind, evaluate the body;
-     * - a function value (eta `SUM`) → dispatch to the function itself;
-     * - a reference that is not a lambda → `#REF!` (Excel resolved it and failed to CALL it);
-     * - any other value → `#VALUE!` (a failed coercion, same class as `="a"+1`).
-     *
-     * All three error rows are MEASURED (probe-lambda-call.ps1).
-     */
     protected _applyCallee(callee: any, node: ASTNode, regs: any[]): any;
     /**
      * Apply over VALUES — the marshalled-callable twin of {@link _applyCallee}'s lambda branch
@@ -274,10 +248,9 @@ export declare class FormulaBlock implements IFormulaBlock {
     protected _evaluateSubtree(node: ASTNode, regs: any[], frame: ReadonlyMap<number, any> | null, row: number, column: number): any;
     /**
      * Runs an execution list — the eager `executions` or a deferred root's list — writing each
-     * node's result into its register. Answers the promise chain when a node is async, in which
-     * case the rest of the list is queued behind it.
+     * node's result into its register.
      */
-    protected _runList(list: ASTNode[], regs: any[], row: number, column: number, frame: ReadonlyMap<number, any> | null): Promise<any> | undefined;
+    protected _runList(list: ASTNode[], regs: any[], row: number, column: number, frame: ReadonlyMap<number, any> | null): void;
     /**
      * The execution list of a subtree that is NOT a deferred root — a partial evaluation (the
      * editor's tooltip) pointing inside a lazy argument. The enclosing root's list restricted to

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

@@ -4,11 +4,6 @@ import { ICalculation } from '../ICalculation';
 import { ReferenceCoords, StructuredReference } from '../Types';
 import { CompilerLocale } from '../compiler/CompilerLocale';
 import { FormulaRecord, IFormulaBlockView } from './IFormulaBlock';
-/**
- * What imaging a {@link FormulaRecord} needs beside the record (DESIGN-CALC-SERVICE §8): the
- * symbol map to resolve its stable ids against, the grid the formula sits on, and the reader's
- * locale. The facade supplies the model's own map; the engine never images for it.
- */
 export interface FormulaImager {
     /** Stable ids to display names. */
     readonly symbols: ISymbolRegistry;
@@ -24,16 +19,6 @@ export interface FormulaImager {
      */
     resolveTableReference?(reference: StructuredReference, row: number): IRange.FixableCoords | FormulaError.Known;
 }
-/**
- * A block as the model reads it: the engine's record imaged against the reader's own symbols
- * (DESIGN-CALC-SERVICE §8).
- *
- * @remarks
- * What the facade hands the model for every block the engine vends. The record is plain data and
- * crosses the channel; the imager is the facade's and never does. Text is the same function of
- * (tokens, symbols, anchor, locale) the compiled block images by - only where it runs differs -
- * so what a sheet reads is what the engine would image, by the model's names.
- */
 export declare class FormulaRecordView implements IFormulaBlockView {
     /** The block as data: what this view images. */
     readonly record: FormulaRecord;

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

@@ -1,18 +1,6 @@
 import { IRange, FormulaError } from '@sheetxl/primitives';
 import { ICalculation } from '../ICalculation';
 import { ReferenceCoords, SetReferenceOptions, PrecedentTemplate, StructuredReference } from '../Types';
-/**
- * A compiled formula as data (DESIGN-CALC-SERVICE §8): what the engine vends for a block, and all
- * the facade needs to image a read view of it for the model (`FormulaRecordView`). Plain data, so
- * it survives `structuredClone`; the syntax tree never crosses.
- *
- * @remarks
- * The tokens carry stable ids in their values - a sheet's, a name's, a table's - and cell
- * coordinates relative to the block's top-left, so one record serves every cell of the block. Text
- * is imaged from them against the reader's own symbol map ({@link FormulaImager}), which is what
- * makes a held copy rename-proof: nothing in the record names a sheet by its name. The model
- * never sees one: it holds the view.
- */
 export interface FormulaRecord {
     /** The block's tokens, stable ids in their values, references relative to the block's top-left. */
     readonly tokens: readonly ICalculation.FormulaToken[];
@@ -346,6 +334,11 @@ export interface IFormulaBlock extends IFormulaBlockView {
      * either all of them call a total function or none do.
      */
     hasTotals(): boolean;
+    /**
+     * Whether the formula calls `TABLE`, the what-if data table, anywhere in its tree. Read off the
+     * compiled cache (`CompiledFormula.hasDataTable`).
+     */
+    hasDataTable(): boolean;
     /**
      * Whether the formula names a volatile function anywhere in its tree.
      *

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

@@ -172,20 +172,5 @@ export declare const OMITTED: unique symbol;
  * to convert, so it cannot leak (plan risk 2).
  */
 export declare const readFrameValue: (value: any) => any;
-/**
- * The recursion budget apply enforces via `CalcScope.depth`.
- *
- * @remarks
- * DESKTOP measured (probe-lambda-eval block A, 2026-08-21): its cap sits between 5,000 and 100,000, and the error at it IS `#NUM!` — the
- * error Microsoft's own LAMBDA documentation names for runaway recursion.
- *
- * 512 rather than Online's 1000: each apply level costs a dozen JS frames, and past ~1000 levels a
- * BROWSER stack dies first — not as a catchable `RangeError` at the recursion site, but as
- * arbitrary near-exhaustion failures deep inside the engine (a regex compile inside the number
- * parser was the observed one), which inner catch sites convert to `#VALUE!` values. The budget
- * has to keep the engine comfortably inside every platform's stack; raising it toward the measured
- * desktop number needs the lazy-`IF` (Conditional) carve-out first, since eager `IF` makes every
- * terminating recursion burn to this cap before unwinding.
- */
 export declare const MAX_LAMBDA_DEPTH = 512;
 //# sourceMappingURL=LambdaValue.d.ts.map

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

@@ -21,14 +21,7 @@ export declare function absoluteReferences(references: readonly ReferenceCoords[
  * When `symbols` is absent (no registry was used at compile time) the tokens
  * already hold display names and are returned as-is.
  */
-export declare function resolveTokenSymbols(tokens: ICalculation.FormulaToken[], symbols: ISymbolRegistry | null | undefined, canonical?: boolean, 
-/**
- * Re-image for a READER rather than for storage. Only an external book reads differently: stored
- * it is `[n]Sheet1` (a position), displayed it is the book's own spelling, and the book half is
- * split into its own {@link TokenType.ExternalReference} token so an editor can color or elide it
- * (DESIGN-EXTERNAL-LINKS §4B).
- */
-display?: boolean, 
+export declare function resolveTokenSymbols(tokens: ICalculation.FormulaToken[], symbols: ISymbolRegistry | null | undefined, canonical?: boolean, display?: boolean, 
 /**
  * The formula's cell (`scope` is its sheet's name or id), for display only. A single-column
  * reference to the table holding it (`Table1[Qty]`, `Table1[@Qty]`) drops the table name, as Excel

package/types/src/calculation/functions/_DataTableFunction.d.ts

@@ -0,0 +1,14 @@
+import { IFormulaContext } from '@sheetxl/primitives';
+import { FunctionDeclarationModule, Implementations, DescriptorModule } from '@sheetxl/scripting';
+/**
+ * The category `TABLE` is listed under: ours, not Excel's. Excel has no `TABLE` a user may type, so
+ * the writer treats it as a function Excel does not have wherever it cannot write Excel's tag.
+ */
+export declare const DataTableCategory = "SheetXL";
+/** `TABLE`'s declarations, as the declaration table and the function registry read them. */
+export declare const DataTableDeclarations: FunctionDeclarationModule;
+/** `TABLE`'s descriptors, loaded on demand like the built-ins'. */
+export declare const DataTableDescriptors: () => Promise<DescriptorModule>;
+/** The implementation the registry binds `TABLE`'s declaration to. */
+export declare const createDataTableImplementations: (getContext: () => IFormulaContext) => Implementations;
+//# sourceMappingURL=_DataTableFunction.d.ts.map