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

package/types/src/calculation/engine/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The calculation backend's code: what a started engine builds and runs.
+ *
+ * @remarks
+ * `Calculation` reaches every value here through this one module and nothing else, so the facade a
+ * workbook constructs carries none of it (DESIGN-CALC-SERVICE §5, §13.25). Types are imported
+ * directly; only values belong on this list.
+ */
+export { CalcBackend } from './CalcBackend';
+//# sourceMappingURL=index.d.ts.map

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,13 @@ 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 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,6 +111,19 @@ export declare class CalcExecutor {
      * while a pass evaluates. Released with {@link _flush}.
      */
     _overlays: Map<string, PendingOverlayGrid> | null;
+    /**
+     * The what-if layers of the data table being evaluated, per grid id (DESIGN-DATA-TABLES §4.3):
+     * what `getGridValues` hands every read while a `TABLE` node runs its substitutions. `null`
+     * otherwise.
+     */
+    _whatIf: Map<string, WhatIfLayer> | null;
+    /**
+     * 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>;
     /**
      * 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
@@ -193,20 +212,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.
      *
@@ -216,6 +224,14 @@ export declare class CalcExecutor {
      *          nothing was dirty.
      */
     execute(cycleId: number, options: CalcExecutor.ExecuteOptions, state: CalcExecutor.ExecuteState): CalcExecutor.ExecuteResult | null;
+    /**
+     * Takes the calls an evaluation of `node` deferred (DESIGN-ASYNC §4.4): the cell's value is an
+     * `AsyncValue` over them and what the formula calculated from their initials, and the node is
+     * pending with it while any is open.
+     */
+    protected _takeDeferred(node: CalcNode, value: any): any;
+    /** The cells of the `TABLE` nodes the pass skipped, scoped; `undefined` for none. */
+    private _takeSkippedTables;
     /**
      * 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
@@ -332,12 +348,41 @@ export declare class CalcExecutor {
      * `flush` of the `doEvaluate` that made it, and only that one.
      */
     private _overlayFor;
+    /**
+     * The results of a what-if data table, for the `TABLE` node being evaluated
+     * (DESIGN-DATA-TABLES §4.3): the affected nodes re-evaluated under each substitution of §2.2,
+     * through layers over what the grids read as now, the pass's uncommitted results included.
+     *
+     * @remarks
+     * The read hooks and the dynamic-edge accumulator are set aside while it runs: every member
+     * read is a plain read through the layers and registers no edge. The table's own reads of its
+     * edge, which order it and register its edges, are made before (`_DataTableFunction`). The calc
+     * scope is the table's again on return.
+     */
+    evaluateWhatIf(table: WhatIfTable): Scalar[][];
+    /**
+     * One node evaluated where it sits, under the what-if layers (DESIGN-DATA-TABLES §4.3): its
+     * input slots are cleared so every read falls through to the funnel, as a demand evaluation's
+     * do. An async result stands as the cell's last value; so does a read that raised a signal.
+     */
+    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
      * cell stores a scalar and registers no spill. Anything else as it is.
      */
     private _fitCell;
+    /**
+     * Whether a representative that read its position answers the same wherever it sits in the
+     * blank region: every variant of its formula ({@link IFormulaBlock.getPositionVariants}) answers
+     * `finalized` at its cell without reading the position, or anything else per cell.
+     *
+     * @remarks
+     * Each position test is `TRUE` or `FALSE` at every cell, so the variants cover every answer the
+     * region can give. A variant reads only what the formula itself read (no lazy argument, so no
+     * 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
@@ -345,8 +390,9 @@ export declare class CalcExecutor {
      *
      * @remarks
      * Shared only when nothing the evaluation read was per cell (`CalcScope.perCellRead`: a draw, a
-     * position, a computed reference), 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
+     * 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}).
      *
@@ -391,6 +437,13 @@ export declare class CalcExecutor {
      * reaches every cell, so the nodes go dense ({@link FormulaSpatialValue.densify}) rather than
      * being minted one by one through the sparse store.
      */
+    /**
+     * The representative's answer depends on the position, in a grid whose owner reads it a tile at
+     * a time (`CalcGridBackend.ConstructorOptions.paged`): the block keeps its sparse store and
+     * evaluates its blank region only inside the owner's tiles ({@link FormulaSpatialValue.blankPaged}),
+     * and what the rest of the region holds is cleared.
+     */
+    private _pageBlank;
     private _fallbackBlank;
     /**
      * What the pass reads for `node` right now — a member's starting value, before any demand
@@ -501,7 +554,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
@@ -568,7 +621,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 */
@@ -584,10 +637,25 @@ export declare namespace CalcExecutor {
          * The grid to seed the pass FROM — `ICalculation.CalculateOptions.scope`, i.e. "Calculate Sheet".
          */
         scopeGridId?: string;
+        /**
+         * The settle pass (DESIGN-ASYNC §4.5): seeded from what the settles marked only; the volatiles
+         * and the dirty set are left for the pass that owes them.
+         */
+        settle?: boolean;
+        /**
+         * `ICalculation.CalculateOptions.external`: the calls the pass makes fetch past the workbook's
+         * cache, to the source.
+         */
+        external?: boolean;
         /**
          * Iterative calculation (design §6.3) for the pass; `null`/absent with it off.
          */
         iterate?: IterateOptions | null;
+        /**
+         * A reactive pass under `AutomaticExceptTables`: `TABLE` nodes are skipped and left dirty
+         * (DESIGN-DATA-TABLES §4.4); they come back in {@link ExecuteResult.skippedTables}.
+         */
+        exceptTables?: boolean;
     }
     /** The two limits of `ICalculation.IterativeCalculation`. */
     interface IterateOptions {
@@ -689,6 +757,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';
@@ -39,6 +39,12 @@ export declare class DownstreamSignal extends CalcSignal {
     constructor(node: CalcNode);
 }
 export declare function rangeToTuples(range: IRange, offsetMajor?: number, offsetMinor?: number): Tuple.Region<Scalar>;
+/**
+ * A finalized result as an `evaluate()` call hands it out. A range is re-packed over a grid of
+ * cell-value runs (`createCellValueRun`), so the API returns what a cell would hold; the grid write
+ * 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
@@ -56,6 +62,22 @@ export declare function fitToExtent(value: Scalar | IRange, rowCount: number, co
  * 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;
 /**
  * TODO - document and/or rationalize with visitPrecedentBlock
  */

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

@@ -0,0 +1,50 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { CalcNode, IContextContainer } from '../state';
+import { WhatIfLayer } from '../state/_WhatIfLayer';
+/**
+ * A what-if data table as its `TABLE` formula states it (DESIGN-DATA-TABLES §1): the results'
+ * top-left cell and size, and the input cells, all on one grid.
+ */
+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[];
+/**
+ * The affected set S of a table (DESIGN-DATA-TABLES §4.3): every node downstream of an input
+ * that is upstream of a formula cell or an axis cell, in an order that evaluates a node after
+ * the nodes it reads. Widened to the whole downstream closure when a member reads through a
+ * dynamic reference, whose edges the index cannot bound.
+ *
+ * A `TABLE` node is never a member, this table's own included: another table's results are read as
+ * they stand, not re-run under this table's substitutions, as Excel reads them (design §2.2 T6).
+ * That also keeps the walk from passing through a table's own edges, which would reach the table.
+ */
+export declare function whatIfAffectedSet(container: IContextContainer, table: WhatIfTable): CalcNode[];
+/**
+ * A table's results under the what-if protocol of DESIGN-DATA-TABLES §2.2, evaluating `affected`
+ * (from {@link whatIfAffectedSet}) under each substitution. The layers are the host's; nothing is
+ * restored, the caller drops them.
+ */
+export declare function runWhatIf(host: WhatIfHost, table: WhatIfTable, affected: readonly CalcNode[]): Scalar[][];
+//# sourceMappingURL=_WhatIf.d.ts.map

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

@@ -93,6 +93,15 @@ export declare class Formula implements ICalculation.IFormula {
      * Provides a string representation of the formula.
      */
     toString(): string;
+    /**
+     * The formula text with its leading `=`, as `ICell.getFormulaText` gives it, so that
+     * logging or stringifying a formula reads as the formula.
+     *
+     * @remarks
+     * Typed `unknown` so a subclass with a persisted form of its own (`NamedFormula`) can answer
+     * with that instead.
+     */
+    toJSON(): unknown;
     /** {@inheritDoc ICalculation.IFormula.isIFormula} */
     get isIFormula(): true;
 }

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

@@ -47,6 +47,8 @@ export declare class FormulaBlock implements IFormulaBlock {
      * `null` = this block's precedents are not a pure translation.
      */
     protected _precedentTemplate: PrecedentTemplate | null | undefined;
+    /** {@link getPositionVariants}' answer, built on first ask. `undefined` = not asked yet. */
+    protected _positionVariants: FormulaBlock[] | null | undefined;
     /** {@link getRecord}'s answer, built on first ask; every vend of this block shares it. */
     private _record;
     constructor(compiled: CompiledFormula, context: IFormulaContext, scope: CalcScope, gridId: string | null, getEntireCoords: () => IRange.Coords, resolvers?: FormulaBlockResolvers | null);
@@ -78,10 +80,16 @@ 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 */
     isBlankCacheable(arrayMode?: boolean): boolean;
     /** @inheritdoc IFormulaBlock.demandFirstCell */
     demandFirstCell(): void;
+    /** @inheritdoc IFormulaBlock.getPositionVariants */
+    getPositionVariants(): FormulaBlock[] | null;
     /** @inheritdoc IFormulaBlock.isReferenceOnly */
     isReferenceOnly(): boolean;
     /** @inheritdoc IFormulaBlock.isEquals */
@@ -268,10 +276,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/IFormulaBlock.d.ts

@@ -346,6 +346,20 @@ 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.
+     *
+     * @remarks
+     * Read straight off the compiled cache — see `CompiledFormula.hasVolatile`: the declaration of
+     * each function answers, at compile time, so a call in an arm no branch selects still counts.
+     * A name the formula mentions is not descended into; its body answers for itself.
+     */
+    hasVolatile(): boolean;
     /**
      * Whether the cells of a block running this formula whose relative inputs are all blank share
      * one value within a pass, as far as the formula TEXT can say.
@@ -365,6 +379,13 @@ export interface IFormulaBlock extends IFormulaBlockView {
      * `[0,0]` read (`CompilerUtils.annotateFirstCell`). Idempotent.
      */
     demandFirstCell(): void;
+    /**
+     * This formula with every position test (`ISODD(ROW())`, `ROW()>1`) replaced by `TRUE` and by
+     * `FALSE`, in every combination — see `CompilerUtils.positionVariants`. When all of them answer
+     * alike at a cell without reading the position, the formula's answer there does not depend on
+     * the position. `null` when there is nothing to vary. Built once.
+     */
+    getPositionVariants(): IFormulaBlock[] | null;
     /**
      * If the formula is logically equal to another formula.
      *

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

@@ -39,9 +39,11 @@ export interface LambdaParam {
  *
  * @remarks
  * CALCULATION-PRIVATE, like stable ids: nothing here reaches a public API. The one boundary rule
- * is the cell's — an unconsumed lambda renders `#CALC!` (`finalizeValue`), and every consumer that
- * needs a scalar or a location fails to COERCE it with `#VALUE!` (the `isLambda` brand is what the
- * coercion sites check, the same structural pattern as `isIRange`).
+ * is the cell's — an unconsumed lambda renders `#CALC!`, as a top-level result in `finalizeValue`
+ * and as a member of an array result where the engine's value grid makes its runs
+ * (`createCellValueRun`) — and every consumer that needs a scalar or a location fails to COERCE it
+ * with `#VALUE!` (the `isLambda` brand is what the coercion sites check, the same structural
+ * pattern as `isIRange`).
  *
  * A lambda closes over its creation context by SNAPSHOT, not by reference: `regs` is a copy of the
  * creating formula's register file at the moment the `LAMBDA` node evaluated. The copy is what

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

@@ -8,6 +8,9 @@ import { IFunction } from '@sheetxl/primitives';
  * range in a slot is taken whole or intersected, for one. That question has an answer before any
  * engine starts, and the same answer wherever it is asked, so it is read here rather than from a
  * calculation's live function registry. The data is the declaration the compiler compiles from.
+ *
+ * The table loads with the formula parser: await `FormulaText.load()` first. Until then every
+ * name is unknown.
  */
 export declare namespace FunctionDeclarations {
     /** A declared function. */
@@ -20,7 +23,8 @@ export declare namespace FunctionDeclarations {
         isBuiltIn(): boolean;
     }
     /**
-     * Returns a built-in function's declaration, or `null` when no built-in has that name.
+     * Returns a built-in function's declaration, or `null` when no built-in has that name or the
+     * table is not loaded.
      *
      * @param name The canonical (English) name. Not case sensitive.
      */

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

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

@@ -0,0 +1,15 @@
+import { IFunction } from '@sheetxl/primitives';
+import { MinifiedDeclaration } from '@sheetxl/scripting';
+/**
+ * Expands one minified built-in declaration into its JSON, with the ids of the enums its
+ * parameters use.
+ *
+ * @remarks
+ * Pure: what a declaration says about its slots, with no implementation attached. The function
+ * registry binds the result to an implementation; `FunctionDeclarations` reads it as data.
+ */
+export declare function expandDeclaration(builtInName: string, builtIn: MinifiedDeclaration, expandEnum: (id: string) => IFunction.EnumJSON | undefined): {
+    decl: IFunction.DeclarationJSON;
+    enumIds: string[];
+};
+//# sourceMappingURL=expandDeclaration.d.ts.map

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

@@ -17,18 +17,6 @@ export declare function initializeFunctions(getContext: () => IFormulaContext, p
  * @param defaultCategory the default category to use if not specified in the declaration
  * @param enums the module's enums, which its parameters reference by id
  */
-/**
- * Expands one minified built-in declaration into its JSON, with the ids of the enums its
- * parameters use.
- *
- * @remarks
- * Pure: what a declaration says about its slots, with no implementation attached. The function
- * registry binds the result to an implementation; `FunctionDeclarations` reads it as data.
- */
-export declare function expandDeclaration(builtInName: string, builtIn: MinifiedDeclaration, expandEnum: (id: string) => IFunction.EnumJSON | undefined): {
-    decl: IFunction.DeclarationJSON;
-    enumIds: string[];
-};
 export declare const bindDeclarations: (mapFunctions: Map<string, IFunction>, getContext: () => IFormulaContext, implementations: Implementations, // TODO make this dynamic
 declarations: MinifiedDeclaration, // TODO make this dynamic
 getDynamicDescriptors?: DynamicDescriptors, defaultCategory?: string, enums?: MinifiedEnums) => void;

package/types/src/calculation/grid/CalcGrid.d.ts

@@ -45,12 +45,14 @@ export declare class CalcGrid implements ICalcGrid {
     protected readonly _sizeOf: string | undefined;
     /** The aggregate cache over the values; bound to the map INSTANCE, so it follows every clone. */
     protected _rangeStats: RangeStats;
+    /** The fixed size the grid was made with, or `null` for one sized by `sizeOf` or the default. */
+    protected readonly _fixedCoords: IRange.Coords | null;
     /**
      * Bumped whenever the value map is mutated IN PLACE (a vend that landed on this grid's own
-     * instance, a load): what {@link getErrorValues} invalidates its cached view by, since the
-     * map's identity does not change then.
+     * instance, a load): what the views derived from the values invalidate by, since the map's
+     * identity does not change then. See {@link getValuesEpoch}.
      */
-    protected _errorEpoch: number;
+    protected _valuesEpoch: number;
     /** The reconciled error-VALUE view; see {@link getErrorValues}. */
     protected _errorReconciled: {
         values: ISparseGrid<Scalar>;
@@ -67,6 +69,18 @@ export declare class CalcGrid implements ICalcGrid {
     protected _emitter: ListenerEmitter<ICalcGrid, ICalcGrid.IListeners> | null;
     protected _closed: boolean;
     constructor(options: CalcGrid.ConstructorOptions);
+    /** An empty grid's state, with the aggregate cache bound to its value map. */
+    protected _freshState(): CalcGrid.State;
+    /**
+     * Gives a grid that a restore left without state - one made in a commit since undone - an empty
+     * state at the current commit again, under the same id, folded into that commit. A redo then
+     * restores the grid's own record where this front reads it; a new grid under the id would read
+     * nothing there. The engine has to be told of the grid again as well: its grids are versioned too.
+     *
+     * @returns `true` when a state was made; `false` for a grid that has one, or is closed.
+     * @internal
+     */
+    _revive(): boolean;
     /**
      * Open this grid's maps from a content record, replacing what they hold: the formulas, the
      * values, their contentful summary, the error ones among them, the array extents the record
@@ -87,6 +101,24 @@ export declare class CalcGrid implements ICalcGrid {
      * own transaction.
      */
     protected _getState(transaction?: ITransaction | null): Readonly<CalcGrid.State>;
+    /**
+     * This grid, reading the record it holds now for as long as it is kept: what a snapshot sheet
+     * reads, so a copy reads its source as it was when marked, not after the destination - which
+     * can overlap it - was cleared. A read that names a transaction still answers for it.
+     * @internal
+     */
+    _pinned(): ICalcGrid;
+    /**
+     * This grid reading the record it held at a commit: what a sheet as of that commit reads.
+     * `null` when the store no longer has the commit, or the grid did not exist at it.
+     *
+     * @remarks
+     * Sound because history is never written: a pass that lands on a record history shares lands
+     * a clone, so the record a commit kept holds the values it was calculated with.
+     * @internal
+     */
+    _pinnedAt(commitId: string): ICalcGrid | null;
+    private _pinTo;
     /**
      * This grid's record as it was at a commit; the current one for the operation in progress;
      * `undefined` for a commit the store no longer has on its live history.
@@ -103,7 +135,7 @@ export declare class CalcGrid implements ICalcGrid {
     /** {@inheritDoc ICalcGrid.getSpills} */
     getSpills(transaction?: ITransaction | null): ISpatialMap<SpillEntry>;
     /** {@inheritDoc ICalcGrid.getPending} */
-    getPending(transaction?: ITransaction | null): ISpatialMap<boolean>;
+    getCalcStatus(transaction?: ITransaction | null): ISpatialMap<ICalcGrid.CalcStatus>;
     /** {@inheritDoc ICalcGrid.getCalcErrors} */
     getCalcErrors(transaction?: ITransaction | null): ISpatialMap<string>;
     /** {@inheritDoc ICalcGrid.getCirculars} */
@@ -112,6 +144,8 @@ export declare class CalcGrid implements ICalcGrid {
     getVolatileRegions(): IRange.Address[] | null;
     /** {@inheritDoc ICalcGrid.getRangeStats} */
     getRangeStats(): RangeStats;
+    /** {@inheritDoc ICalcGrid.getValuesEpoch} */
+    getValuesEpoch(): number;
     /** {@inheritDoc ICalcGrid.getErrorValues} */
     getErrorValues(): ISpatialMap<boolean>;
     /**
@@ -195,10 +229,10 @@ export declare class CalcGrid implements ICalcGrid {
     _isOwned(): boolean;
     /** {@inheritDoc ICalcGrid.Backend.requestPass} @internal */
     _requestPass(): void;
+    /** {@inheritDoc ICalcGrid.Backend.demand} @internal */
+    _demand(rects: readonly IRange.Coords[]): void;
     /** {@inheritDoc ICalcGrid.getGraphNeighborsAt} */
     getGraphNeighborsAt(coords: IRange.Coords, kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
-    /** {@inheritDoc ICalcGrid.Backend.getNameGraph} @internal */
-    _getNameGraph(kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
     /** {@inheritDoc ICalcGrid.evaluateAt} */
     evaluateAt(row: number, column: number, options?: number | ICalculation.EvaluateOptions): Promise<Scalar | IRange>;
     /** `true` once closed: its state is gone. @internal */
@@ -215,7 +249,7 @@ export declare class CalcGrid implements ICalcGrid {
      * as any answer does. Nothing is written here first - the text is the engine's to make.
      * @internal
      */
-    _setBody(options: ICalcGrid.BodyOptions): Promise<ICalcGrid.Results>;
+    _setBody(options: ICalcGrid.BodyOptions, isCurrent?: () => boolean): Promise<ICalcGrid.Results>;
     /** {@inheritDoc ICalcGrid.isVolatileAt} */
     isVolatileAt(row: number, column: number): Promise<boolean>;
     /** {@inheritDoc ICalcGrid.addListeners} */
@@ -360,12 +394,12 @@ export declare namespace CalcGrid {
          */
         volatile: IRange.Address[] | null;
         /** Cells the engine has not answered for yet. */
-        pendingSpatial: ISpatialMap<boolean>;
+        calcStatusSpatial: ISpatialMap<ICalcGrid.CalcStatus>;
         /** Engine FAILURES by cell, as a message. Not error values - those are in the values. */
         calcErrorsSpatial: ISpatialMap<string>;
         /**
          * Cells in a reference cycle or downstream of one, by cycle (DESIGN-CIRCULAR-CALC.md §7.2).
-         * Maintained from the executor's deltas, like {@link pendingSpatial}.
+         * Maintained from the executor's deltas, like {@link calcStatusSpatial}.
          */
         circularSpatial: ISpatialMap<CircularEntry>;
         /**
@@ -401,7 +435,7 @@ export declare namespace CalcGrid {
         values: ISparseGrid<Scalar>;
         contentful: ISpatialMap<ContentfulSpatialValue>;
         spills: ISpatialMap<SpillEntry>;
-        pending: ISpatialMap<boolean>;
+        calcStatus: ISpatialMap<ICalcGrid.CalcStatus>;
         calcErrors: ISpatialMap<string>;
         circulars: ISpatialMap<CircularEntry>;
         errorValues: ISpatialMap<boolean>;