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

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

@@ -5,19 +5,6 @@ import { FormulaRecord, FormulaImager } from '../formula';
 import { ICalculation } from '../ICalculation';
 import { NamedReference } from '../Types';
 import { ICalcGrid } from './ICalcGrid';
-/**
- * A call on a grid, as the service's channel holds it while the engine is `Starting`
- * (DESIGN-CALC-SERVICE §4, §7.2): the verb and its arguments, applied in send order once the
- * engine is up. The snapshot it was made at rides in its options (`commitId`, `cloneKey`).
- *
- * @remarks
- * Not part of {@link ICalcGrid}: a caller sees the verbs and their promises. This is what the
- * in-process channel holds in place of a worker port's queue, and what the clone boundary audits
- * (plan step 6): a held call carries what the verb's arguments carry, which is what a proxy
- * would post.
- *
- * @internal Deliberately not exported from the barrel.
- */
 export type CalcRequest = 
 /**
  * Make the engine's grid for a model grid, from what the model says it is. The grid's first
@@ -166,15 +153,13 @@ export type CalcRequest =
 }
 /**
  * The graph around cells of this grid, answered in the response (`ICalcGrid.GraphNeighbors`,
- * cells in calc currency). A question. `asName` walks the defined name this grid holds the body
- * of instead: its own precedents or dependents, cells and names.
+ * cells in calc currency). A question.
  */
  | {
     type: 'graph';
     kind: 'precedents' | 'dependents';
     direct: boolean;
-    coords?: IRange.Coords;
-    asName?: boolean;
+    coords: IRange.Coords;
 }
 /** Whether the formula at a cell is volatile, answered in the response. A question. */
  | {
@@ -186,15 +171,7 @@ export type CalcRequest =
  | {
     type: 'setBody';
     body: ICalcGrid.BodyOptions;
-}
-/**
- * The sheet list as its owner holds it when the message is sent - every sheet's grid id and
- * name, in tab order - for the engine's replica (DESIGN-CALC-SERVICE §8). A message of the
- * service, not of a grid: the channel holds it in order with the grids' requests, which is what
- * lets a seed sent before a rename compile against the names it was sent under. The owner tells
- * a sheet before any grid that names it seeds (`Calculation._setSheets`).
- */
- | {
+} | {
     type: 'sheets';
     sheets: readonly (readonly [id: string, name: string | null, gridless?: boolean])[];
     options?: ICalcGrid.RequestOptions;
@@ -215,6 +192,18 @@ export type CalcRequest =
     changes: readonly (readonly [id: string, name: NameSymbols | null])[];
     options?: ICalcGrid.RequestOptions;
 }
+/**
+ * The graph around a defined name - its precedents or dependents, cells in calc currency and
+ * names - answered in the response (`ICalcGrid.GraphNeighbors`). A question of the service, not
+ * of the name's grid: its readers are found by its id, so a name that has not compiled is asked
+ * without making it a grid.
+ */
+ | {
+    type: 'nameGraph';
+    nameId: string;
+    kind: 'precedents' | 'dependents';
+    direct: boolean;
+}
 /**
  * A nested savepoint of the model rolled back inside an operation that goes on: what the requests
  * made under it did goes with it. After them in the channel, so it undoes exactly those.
@@ -255,13 +244,6 @@ export interface CalcGridSpec {
 export type TableSymbols = readonly [name: string, columns: readonly (readonly [id: string, name: string])[]];
 /** A defined name as the engine's replica holds it: its name, and the id of the sheet it is scoped to. */
 export type NameSymbols = readonly [name: string, scopeId: string | null];
-/**
- * What crosses back (DESIGN-CALC-SERVICE §8): {@link ICalcGrid.Results} with the formula half as
- * records - data, since only data crosses. The facade images each record into the
- * {@link IFormulaBlockView} the model reads ({@link imageResponse}) before the results reach it.
- *
- * @internal Deliberately not exported from the barrel.
- */
 export type CalcResponse = Omit<ICalcGrid.Results, 'formulaInserts'> & {
     formulaInserts?: ISpatialMap.Entry<FormulaRecord>[];
     /**
@@ -287,6 +269,8 @@ export type GridRequest = Exclude<CalcRequest, {
     type: 'tables';
 } | {
     type: 'names';
+} | {
+    type: 'nameGraph';
 } | {
     type: 'rollback';
 } | {

package/types/src/calculation/spatial/CircularEntry.d.ts

@@ -1,14 +1,4 @@
 import { ICalculation } from '../ICalculation';
-/**
- * What a sheet's circular index says about a cell (DESIGN-CIRCULAR-CALC.md §7.2): which
- * reference cycle it belongs to, and whether it is in the cycle or merely downstream of it.
- *
- * @remarks
- * The value stays what it is (`0`, Excel's answer with iterative calculation off); this is
- * metadata beside it, the way `SpillEntry` marks a spill zone. Entries are interned per
- * `(cycle, kind)` by the executor, so equal payloads are the same object and adjacent cells of
- * one cycle coalesce into one region — and a region's payload IS the cycle, no id to look up.
- */
 export interface CircularEntry {
     /** The cycle; one live object per cycle, shared by every cell in it or downstream of it. */
     readonly cycle: ICalculation.ICircularReference;

package/types/src/calculation/spatial/FormulaSpatialValue.d.ts

@@ -28,21 +28,6 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
      */
     ref: IRange.Coords;
     formula: IFormulaBlock | null;
-    /**
-     * The block's nodes, DENSE - one per cell - for a block the pass evaluates cell by cell; `null`
-     * for a block that shares one answer over its blank region (PLAN-WATCHES-BLANK-AWARE §4c), which
-     * keeps its nodes in {@link _nodes} instead, and `null` while nothing has touched the block.
-     * Never indexed from outside: {@link nodeAt}, {@link nodeAtOrNull}, {@link forEachNodeIn},
-     * {@link mintNodesIn} and {@link forEachNode} are the reads, and they are the same calls for
-     * either shape.
-     *
-     * @remarks
-     * Nodes are runtime state, not the formula: they exist from the first touch ({@link nodeAt},
-     * {@link mintNodesIn}) and are dropped when the block leaves its map ({@link release}). A block
-     * that nothing has touched, or that was released, holds no node for any cell, which the executor
-     * reads as "never collected: a value". A superseded block is still held by every earlier
-     * commit's map, so what it keeps is what the history keeps; a restore mints again on demand.
-     */
     calcs: CalcNode[][] | null;
     /**
      * A gated block's nodes, keyed by cell. **A node exists only where its cell has been touched**
@@ -75,42 +60,16 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
      */
     registeredPrecedents: ISpatialMap.Entry<any>[] | null;
     /**
-     * `true` when {@link ref} is a synthetic anchor rather than a position in a real grid — a named
-     * formula's body (stored at (0,0) in its virtual grid) or the editor's temporary formula.
-     *
-     * @remarks
-     * A **relative** reference is stored as an offset from `ref`, so on these blocks its absolute
-     * position (`ref + offset`) is fiction: there is no cell it names, and nothing to compare against
-     * a shift boundary. Structural change must therefore leave relative endpoints alone — the offset
-     * IS the definition. Measured against Excel: a relative name's `RefersTo` never changes under
-     * insert/delete/move, while an absolute one always does (`$`-fixed endpoints carry a real
-     * coordinate that owes nothing to the anchor, so they shift normally on these blocks too).
-     *
-     * Deliberately NOT "is a named body". Anything holding a formula at a synthetic anchor wants the
-     * same treatment, and the shift code should not have to know what a name is.
-     *
-     * A calculation pass never evaluates such a block: its anchor is no cell, so there is nothing
-     * to write an answer to, and whatever reads the body runs it inline at its own position. It is
-     * evaluated on demand only (`ICalcGrid.evaluateAt`), and `isVolatileAt` answers for it from the
-     * formula text alone, there being nothing a pass registered (`CalcGridBackend._isVolatileNow`).
-     *
-     * Required at construction rather than defaulted: the block is immutable and re-minted on every
-     * reference rewrite, so an unthreaded copy would silently revert to `false` on the first
-     * `setReferenceAt` — which is exactly what a shift performs.
+     * This block is the one a seed loaded, and what its cells show came with it. A write replaces
+     * the block, so a block that is `true` has not been edited since.
      */
-    readonly unanchored: boolean;
+    fromLoad: boolean;
     /**
-     * `true` when every cell of this block is its own 1x1 array-entered formula — the grid's
-     * {@link ICalcGrid.isArrayFirstCell}, read once at construction.
-     *
-     * @remarks
-     * Excel's rule for a conditional-format formula (DESIGN-LIFT-AND-DEMAND §2): the whole tree is
-     * array mode (`CalculationContext.isImplicitIntersect`), the tree is evaluated under a first-cell
-     * demand so a lift builds only `[0,0]` ({@link IFormulaBlock.demandFirstCell}), and the commit
-     * keeps `[0,0]` of a result that is still a range. Every cell therefore stores a scalar, which
-     * is what lets the blank region share one answer. No extent is recorded per node: the block is
-     * a property of the grid, and a sparse block stays sparse.
+     * A cell of this block was loaded marked to calculate on load (`JSON.volatile`, xlsx `ca`), which
+     * for a call is asking its source: how a call still working at save picks up where it left off.
      */
+    calcOnLoad: boolean;
+    readonly unanchored: boolean;
     readonly arrayFirstCell: boolean;
     /**
      * How many static precedent edges each of this block's cells has — the same count at every
@@ -145,12 +104,6 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
     protected _scratchCoords: IRange.FixableCoords[] | null;
     protected _scratchRow: number;
     protected _scratchCol: number;
-    /**
-     * Blank-aware evaluation (PLAN-WATCHES-BLANK-AWARE §4): the block's touched windows, cached per
-     * collection ({@link getTouched}), and what the pass decided about the blank region's
-     * representative. Per block INSTANCE — a block is re-minted on every edit, shift and split, so
-     * none of this survives a change to the block, and none of it has to.
-     */
     protected _touched: TouchedWindows | null;
     protected _touchedCycleId: number;
     protected _touchedMarkId: number;
@@ -200,14 +153,17 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
      * of that pass only.
      */
     blankFallbackCycleId: number;
+    uncalculated: boolean;
     /**
-     * Loaded with cells that carried no cached value (`CalcGridBackend._seedNow`'s repair). Such a cell
-     * has never been evaluated, and it was not ENTERED either, so Excel gives it no entry
-     * evaluation: joining a cycle, it starts the sweeps from `""` (DESIGN-CIRCULAR-CALC §2.4).
-     * Read only where the grid holds nothing for the cell — once evaluated, the value is the start.
-     * Carried through the rebuilds that keep the nodes (shift, split, merge), not by a copy.
+     * An evaluation of some cell of this block read its position, or something else of the cell's
+     * own - `ROW()`, `ROW(A5)`, `CELL("address", A5)`, `FORMULATEXT(A5)` (`CalcScope.positionRead`,
+     * `CalcScope.perCellRead`). The text cannot tell (`collectBlankCacheable` in the compiler says
+     * why), so it is learned as the block runs and kept: a block that moves with such a read answers
+     * differently at its new cells, where one without answers there as it did
+     * (`CalcGridBackend._shiftNow`). Carried through the rebuilds that keep the nodes, like
+     * {@link uncalculated}.
      */
-    uncalculated: boolean;
+    positionRead: boolean;
     constructor(coords: IRange.Coords, gridId: string | null, formula: IFormulaBlock | null, container: IContextContainer, unanchored: boolean, nodes?: FormulaSpatialValue.NodeSource[]);
     /** Every source block's nodes, at this block's cells - see {@link FormulaSpatialValue.NodeSource}. */
     getNodeSource(): FormulaSpatialValue.NodeSource[];
@@ -232,6 +188,11 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
     protected _mintDense(): CalcNode[][];
     /** The static edges a fresh node of this block stores at a cell - what {@link _createCalcs} gives every cell. */
     protected _freshPrecedents(row: number, col: number): CalcNode['precedents'];
+    /**
+     * Reads the static edges again, for when a name the formula mentions has gained a body: a name
+     * contributes its body's cells. The nodes keep everything else they hold.
+     */
+    refreshPrecedents(): void;
     /**
      * Drops the nodes. Called as the block leaves its map, so the maps of earlier commits, which
      * still hold it, do not hold a generation of nodes with it. The anchor stays (see
@@ -261,17 +222,6 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
      * is the block's shared buffer — see {@link _scratch} for how long it stays valid.
      */
     getPrecedentsAt(row: number, col: number): (IRange.Coords | FormulaError.Known)[];
-    /**
-     * Whether the pass may evaluate ONE cell of this block's blank region and share its answer with
-     * the rest (PLAN-WATCHES-BLANK-AWARE §4) — the block-level gate over the formula's compile-time
-     * one ({@link isBlankCacheable}).
-     *
-     * @remarks
-     * A template is the shape the touched predicate needs (one relative edge per reference, the
-     * same at every cell); an array-entered block has its own fitted write; a one-cell block has
-     * nothing to share. The two pass-side verdicts — {@link blankRefused}, {@link blankFallbackCycleId}
-     * — close the gate after the fact.
-     */
     isBlankAware(cycleId: number): boolean;
     /**
      * The block's touched windows for one collection — computed on first ask, from the grids its
@@ -341,22 +291,39 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
     /** A fresh node for a cell of this block. */
     protected _newNode(cellRow: number, cellCol: number, gridId: string | null, cellPrecedents: CalcNode['precedents']): CalcNode;
     /**
-     * The static edges a cloned or minted node of a non-templated block stores; `null` under a
-     * template. The top-left's answer doubles as `paramLength`, so it is resolved once per clone.
+     * The static edges a taken or minted node of a non-templated block stores; `null` under a
+     * template. The top-left's answer doubles as `paramLength`, so it is resolved once per take.
      */
-    protected _clonePrecedents(cellRow: number, cellCol: number, topLeft: CalcNode['precedents']): CalcNode['precedents'];
+    protected _takePrecedents(cellRow: number, cellCol: number, topLeft: CalcNode['precedents']): CalcNode['precedents'];
     /**
-     * `original` re-minted as this block's node for (`cellRow`, `cellCol`): the same value, promise
-     * and cycle state, fresh slots and stamps - a new position, so nothing that described the old
-     * one is kept.
+     * Takes the sources' nodes as this block's - see {@link FormulaSpatialValue.NodeSource}.
+     *
+     * @remarks
+     * The nodes are MOVED, not copied. A node is reachable by identity from outside its block - a
+     * deferred call's owner, a cycle member's `cycleNext`, the volatile roster - and the moved node
+     * is the live one, so those stay right with no fix-up. Each source is then released: a block
+     * whose nodes left it must not answer for them to a restore. A caller with another block still
+     * to take from the same source passes `releaseSources` false and releases it itself
+     * ({@link getSplit}).
+     */
+    protected _adopt(sources: FormulaSpatialValue.NodeSource[], releaseSources: boolean): void;
+    /**
+     * `node` re-seated as this block's node for (`cellRow`, `cellCol`): the same object, with fresh
+     * slots and stamps - a new position, so nothing that described the old one is kept.
      */
-    protected _cloneNode(original: CalcNode, cellRow: number, cellCol: number, gridId: string | null | undefined, cellPrecedents: CalcNode['precedents']): CalcNode;
+    protected _adoptNode(node: CalcNode, cellRow: number, cellCol: number, cellPrecedents: CalcNode['precedents']): CalcNode;
+    /**
+     * A copy of `node` as this block's node for (`cellRow`, `cellCol`): the same value and cycle
+     * state, fresh slots and stamps. For the anchor a {@link release} keeps once the node itself has
+     * moved to another block; a live node is never copied, it is adopted.
+     */
+    protected _copyNode(node: CalcNode, cellRow: number, cellCol: number): CalcNode;
     /** The source node for this block's cell (`i`, `j`), whichever source holds it; `null` for none. */
     protected _sourceNodeAt(sources: FormulaSpatialValue.NodeSource[], i: number, j: number): CalcNode | null;
-    /** A dense node array over this block, each cell cloned from its source node or minted fresh. */
-    protected _cloneDense(sources: FormulaSpatialValue.NodeSource[], gridId: string | null | undefined): CalcNode[][];
-    /** This block's sparse nodes: every source node whose cell lands inside the block, cloned there. */
-    protected _cloneSparse(sources: FormulaSpatialValue.NodeSource[], gridId: string | null | undefined): void;
+    /** A dense node array over this block: each source node taken, and a fresh node where no source has one. */
+    protected _takeDense(sources: FormulaSpatialValue.NodeSource[]): CalcNode[][];
+    /** This block's sparse nodes: every source node whose cell lands inside the block, taken. */
+    protected _takeSparse(sources: FormulaSpatialValue.NodeSource[]): void;
     /**
      * @param coords The extent to serialize as. Defaults to the block's own; a caller that has
      * coalesced adjacent equal blocks passes the merged extent, whose anchor is this block's.
@@ -428,6 +395,8 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
     getReferencedSymbolIds(): string[];
     /** {@inheritDoc IFormulaBlock.hasTotals} */
     hasTotals(): boolean;
+    /** {@inheritDoc IFormulaBlock.hasDataTable} */
+    hasDataTable(): boolean;
     /** {@inheritDoc IFormulaBlock.hasVolatile} */
     hasVolatile(): boolean;
     /** {@inheritDoc IFormulaBlock.isBlankCacheable} */
@@ -454,6 +423,9 @@ export declare namespace FormulaSpatialValue {
      * block's cell (`i`, `j`). A split reads one source at an offset; a merge reads two, the
      * second at a negative origin; a shift, re-image or re-anchor reads the block itself at
      * (0, 0). A cell no source holds gets a fresh node.
+     *
+     * The nodes MOVE: the source is left released. Build from a block's nodes only for the block
+     * that replaces it in its map; a block that stays in a map is read through its formula instead.
      */
     interface NodeSource {
         readonly block: FormulaSpatialValue;

package/types/src/calculation/spatial/SpillEntry.d.ts

@@ -1,6 +1,7 @@
 import { IRange } from '@sheetxl/primitives';
 import { ITypes } from '../../type';
-import { ISpatialMap } from '../../collections';
+import { ISpatialMap, ISpatialQuery } from '../../collections';
+import { AsyncValue } from '../../primitives/AsyncValue';
 /**
  * Spill Entries are used to track the extent an array formula occupies.
  *
@@ -15,7 +16,11 @@ export declare class SpillEntry {
     private _c;
     private _k;
     private _cycleId;
-    constructor(coords: IRange.Coords, cycleId: number, kind?: ITypes.FormulaArrayKind);
+    private _h;
+    private _b;
+    constructor(coords: IRange.Coords, cycleId: number, kind?: ITypes.FormulaArrayKind, holder?: AsyncValue | null, blocked?: IRange.Coords | null);
+    /** The anchor's holder, for a spill laid out by an evaluation that deferred; `null` otherwise. */
+    getHolder(): AsyncValue | null;
     getCycleId(): number;
     /** {@inheritDoc ITypes.FormulaArrayKind} */
     getKind(): ITypes.FormulaArrayKind;
@@ -25,7 +30,14 @@ export declare class SpillEntry {
      */
     isFixed(): boolean;
     getCoords(): IRange.Coords;
-    setError(error: boolean, cycleId: number): ISpatialMap.Entry<this>;
+    /** The extent a blocked spill would take; `null` for any other. */
+    getBlockedCoords(): IRange.Coords | null;
+    /** {@link getBlockedCoords} moved by what moved the anchor to `to`. */
+    protected _blockedAt(to: IRange.Coords): IRange.Coords | null;
+    /**
+     * @param keepExtent For the sheet's map of blocked spills, whose entries are at the extent they would take.
+     */
+    setError(error: boolean, cycleId: number, keepExtent?: boolean): ISpatialMap.Entry<this>;
     /**
      * Refuses a shift that would change part of a fixed block - Excel's "You can't change part of
      * an array." A block the shift lands entirely before or after translates whole; a delete that
@@ -52,4 +64,9 @@ export declare class SpillEntry {
     /** {@inheritDoc ISpatialMap.IUpdatableValue.getSplit} */
     getSplit(coords: [IRange.Coords, IRange.Coords], _axis: IRange.Axis): [this, this] | undefined;
 }
+/**
+ * The holder of the spill anchored at (`row`, `col`), or `null` when no spill is anchored there
+ * or its evaluation did not defer. A blocked spill's entry is anchored too.
+ */
+export declare const spillHolderAt: (spills: ISpatialQuery<SpillEntry> | null | undefined, row: number, col: number) => AsyncValue | null;
 //# sourceMappingURL=SpillEntry.d.ts.map

package/types/src/calculation/state/CalcNode.d.ts

@@ -51,7 +51,6 @@ export interface CalcNodeExt {
      * and by `setInputs` with a `arrayFixed`; translated with the node when its block moves.
      */
     fixedRef: IRange.Coords | null;
-    pendingPromise: Promise<any> | null;
     /**
      * The demand evaluation's result — finalized for the cell, or a pending promise — which
      * `doEvaluate` consumes in place of an `evaluateAt` of its own. Cleared once consumed.

package/types/src/calculation/state/CalcScope.d.ts

@@ -1,4 +1,5 @@
 import { CalcNode } from './CalcNode';
+import { DeferredCall } from './DeferredCalls';
 /**
  * A reused data structure passed to CalculationContext.
  *
@@ -41,15 +42,6 @@ export interface CalcScope {
      * inherits it.
      */
     firstCell: boolean;
-    /**
-     * Set when the evaluation read something that is PER CELL rather than a property of its inputs
-     * — a random draw (`IFormulaContext.getRandom`), another cell's formula or sheet
-     * (`getFormulaAt`, `getSheetIndex`), or a reference it computed (a dynamic precedent) — so its
-     * answer cannot stand in for another cell's even when the two cells' inputs are identical.
-     * Cleared by whoever evaluates a cell as the representative of a block's blank region and read
-     * at its finalize (PLAN-WATCHES-BLANK-AWARE §4); a cell evaluated on its own behalf never
-     * reads it.
-     */
     perCellRead: boolean;
     /**
      * Set when the evaluation read its own POSITION — `getRow`, `getColumn`, its own address, a
@@ -70,6 +62,34 @@ export interface CalcScope {
      * before. Ignored when no seed is set.
      */
     drawIndex: number;
+    /**
+     * How many `IFormulaContext.defer` calls the backend has taken, ever.
+     *
+     * @remarks
+     * Never reset. A dispatch, or the executor around an evaluation, reads it before and compares
+     * after: a change means a body deferred inside, however deeply nested. Nothing else on the
+     * synchronous path reads it.
+     */
+    deferCount: number;
+    /**
+     * How many calls the evaluation in progress has deferred: the next call's ordinal, which is how
+     * a later evaluation of the same cell finds it. Back to `0` once the evaluation's calls are
+     * taken, which only an evaluation that deferred needs.
+     */
+    deferOrdinal: number;
+    /**
+     * Whether the formula's ROOT call deferred in the evaluation in progress. With one call in all,
+     * the cell's value is that call's answer and a settle needs no re-evaluation. Cleared with
+     * {@link deferOrdinal}.
+     */
+    deferRoot: boolean;
+    /**
+     * The call the last `defer` was served — the site's call standing for its payload — or `null`
+     * when that `defer` made a new one. The dispatch around the deferring body takes it and, when
+     * the call has a latest, answers that in place of the body's return. Cleared with
+     * {@link deferOrdinal}.
+     */
+    deferServed: DeferredCall | null;
     /**
      * Stable nameIds currently on the resolution stack — the cycle guard for named
      * formulas. A plain name re-entering itself (`X = X + 1`) is a circular reference.

package/types/src/calculation/state/CalcState.d.ts

@@ -23,10 +23,6 @@ export declare const CalcState: {
     readonly Removed: number;
     /** The node is in the pending spatial (the user has been given a pending status). */
     readonly Pending: number;
-    /** A precedent evaluated to a pending value this pass, so the node keeps its cached value. */
-    readonly PendingPrecedents: number;
-    /** The node's promise resolved; the result waits in `cachedValue` for the next pass. */
-    readonly PendingResolved: number;
     /**
      * The topological sort could not order the node this pass — it is in a reference cycle, or
      * downstream of one — so it was (or will be) evaluated by demand and `doEvaluate` takes its
@@ -82,14 +78,28 @@ export declare const CalcState: {
      * never needed for a right answer.
      */
     readonly Queued: number;
+    /**
+     * A precedent is pending with a value this pass: the node evaluates from that value, as any
+     * dependent does, and is pending with it.
+     */
+    readonly WaitingPrecedents: number;
+    /**
+     * The node is {@link Pending} with a value its dependents calculate from — it holds a call that
+     * has not answered, or was calculated from such a value — rather than holding them. Decided by
+     * each evaluation, so outside {@link PassMask}.
+     */
+    readonly PendingValue: number;
+    readonly ServeLatest: number;
+    /**
+     * The evaluation recorded a call of the cell's own that has not answered: the cell is working,
+     * not merely waiting on a precedent. Decided by each evaluation, so outside {@link PassMask}.
+     */
+    readonly OwnCall: number;
+    /** What the status index was last told, while {@link Pending}: working (set) or waiting (clear). */
+    readonly SentWorking: number;
     /** What the mark phase resets: everything a single pass decides. `Skip` and the shown role survive. */
     readonly PassMask: number;
 };
-/**
- * Where a node the topological sort could not order stands in the demand evaluation
- * (DESIGN-CIRCULAR-CALC.md §4.3). Meaningful only while `CalcState.Circular` is set for the
- * current pass. Values sit in the `CalcState.DemandMask` field.
- */
 export declare const DemandState: {
     /** Not yet evaluated; a read of it suspends the reader so it can go first. */
     readonly Unevaluated: 0;

package/types/src/calculation/state/CalculationContext.d.ts

@@ -1,10 +1,11 @@
-import { IRange, ScalarType, FormulaError, Scalar, IReferenceRange, IFunction, IFormulaContext, IFunctionArguments, IRuntime } from '@sheetxl/primitives';
+import { IRange, ScalarType, FormulaError, Scalar, IReferenceRange, IFunction, IFormulaContext, IFunctionArguments, IRuntime, IRichData } from '@sheetxl/primitives';
 import { FunctionProvider } from '@sheetxl/scripting';
 import { ITransaction } from '../../transaction';
 import { IFunctionCollection } from '../../scripting';
 import { Tuple } from '../../collections';
 import { IContextContainer } from './IContextContainer';
 import { CalcScope } from './CalcScope';
+import { WhatIfTable } from '../executor/_WhatIf';
 import { ReadHook } from './_ReadObservedGrid';
 export declare class CalculationContext implements IFormulaContext {
     protected _instanceScope: any;
@@ -29,12 +30,6 @@ export declare class CalculationContext implements IFormulaContext {
      * single-cell read {@link getValueAt} falls back to. Constructing a reference is not a read.
      */
     protected _onRead: ReadHook | null;
-    /**
-     * Receives the reads of references built on the DYNAMIC branch of {@link getReference} — the
-     * result of `OFFSET`/`INDIRECT`/`INDEX` — when {@link _onRead} is not armed. The executor arms
-     * it for the length of an ordinary pass so that a dynamic read landing on the evaluating cell
-     * is seen (DESIGN-CIRCULAR-CALC.md §5); `null` outside a pass.
-     */
     protected _dynamicRead: ReadHook | null;
     /**
      * Marks the evaluation in progress as having read its position, so its answer stands in for
@@ -60,6 +55,22 @@ export declare class CalculationContext implements IFormulaContext {
      * hook is armed. See {@link _dynamicRead}.
      */
     _setDynamicReadHook(hook: ReadHook | null): void;
+    /**
+     * @hidden
+     * Disarms both read hooks and returns what they were, for {@link _restoreReadHooks}: a what-if
+     * evaluation reads plainly in the middle of a node that is itself observed.
+     */
+    _takeReadHooks(): [ReadHook | null, ReadHook | null];
+    /** @hidden Re-arms the hooks {@link _takeReadHooks} returned. */
+    _restoreReadHooks(hooks: [ReadHook | null, ReadHook | null]): void;
+    /**
+     * @hidden
+     * The grid id of the cell being evaluated and of an input reference, for `TABLE`: `null` for a
+     * reference whose sheet does not resolve.
+     */
+    _gridIdOfReference(coords: Readonly<IRange.Coords> | null): string | null;
+    /** @hidden The what-if results of a data table, for the `TABLE` node being evaluated. */
+    _evaluateWhatIf(table: WhatIfTable): Scalar[][] | null;
     /**
      * @hidden
      *
@@ -68,19 +79,21 @@ export declare class CalculationContext implements IFormulaContext {
     _initialize(transactions?: ITransaction.IStore): Promise<{
         functions: IFunctionCollection;
     }>;
+    _createScoped(sheet: string): CalculationContext | null;
     /**
      * @hidden
-     * A context bound to `sheet`'s grid INDEPENDENT of evaluation state — the public-API vend
-     * behind `IFunctionCollection.getByName(name, { sheet })` (CALC-ISSUES item 35). The engine's
-     * shared context resolves references through the mutable `CalcScope` the container owns, which
-     * only carries a grid while a formula is evaluating; a vended function called outside the
-     * graph needs a grid of its own. Shares every initialized part (runtime, functions, coercer) —
-     * only the scope object is new — and is NEVER used on the engine's evaluation path, which
-     * stays allocation-free on the shared instance.
+     * The workbook's context with no cell, for `IDeferContext.getFormulaContext`: shares every
+     * initialized part, as {@link _createScoped} does, and refuses what needs a cell.
      */
-    _createScoped(sheet: string): CalculationContext | null;
+    _createCellFree(): CalculationContext;
     /** @inheritdoc IFormulaContext.getFunction */
     getFunction(name: string): IFunction | null;
+    /**
+     * @hidden
+     * The function registry's stamp: a function {@link getFunction} returned stays the answer for its
+     * name while this is unchanged.
+     */
+    _getFunctionStamp(): number;
     /** @inheritdoc IFormulaContext.getNumberFormat */
     getNumberFormat(formatText: string, value: Scalar): string | null;
     /** @inheritdoc IFormulaContext.getEntireCoords */
@@ -89,6 +102,8 @@ export declare class CalculationContext implements IFormulaContext {
     getFormulaAt(row: number, column: number, sheetName?: string): string | null;
     /** @inheritdoc IFormulaContext.markVolatile */
     markVolatile(): void;
+    /** @inheritdoc IFormulaContext.defer */
+    defer(executor: IFormulaContext.DeferExecutor, payload?: unknown): unknown;
     /** @inheritdoc IFormulaContext.formatResults */
     formatResults(numFmt: string): void;
     /** @inheritdoc IFormulaContext.filterHidden */
@@ -157,29 +172,6 @@ export declare class CalculationContext implements IFormulaContext {
     _expandSheetSpan(value: any): IRange.Coords[] | null;
     /** @inheritdoc IFormulaContext.getResizedReference */
     getResizedReference(anchor: Readonly<IRange.Coords>, rowCount: number, colCount: number): IReferenceRange;
-    /**
-     * Builds the {@link ReferenceRange} every {@link getReference} path returns.
-     *
-     * @remarks
-     * Coords that land off the grid cannot be formed into a reference at all, and `ReferenceRange`
-     * says so with an internal `OutOfBoundsError`. Left alone that escapes the calculation as a
-     * `#VALUE!` carrying the text "Out of bounds"; the formula-visible answer is `#REF!`, which is
-     * what {@link IFormulaContext.getReference} documents and what Excel answers for every consumer
-     * whose reference IS the result (`OFFSET` in all four directions, `INDIRECT` past the last
-     * row/column - probe-oob-getreference.ps1).
-     *
-     * A caller that reads a WINDOW rather than returning a reference - `SUMIF`'s `sum_range`,
-     * `LOOKUP`'s `result_vector`, both anchor-plus-length - goes through
-     * {@link getResizedReference} instead: Excel reads the part that fits rather than failing.
-     *
-     * This is the one place a reference is built on a formula's behalf, so it is where the read
-     * hook attaches: while {@link _onRead} is armed the reference is built over a
-     * {@link ReadObservedGrid} and every value it (or a view derived from it) opens is reported.
-     * Unarmed, a static reference's grid is used as is — the ordinary path pays nothing, not even a
-     * branch per read — while a `dynamic` one (the result of `OFFSET`/`INDIRECT`/`INDEX`, the rare
-     * path) reports to {@link _dynamicRead} when that is armed: a dynamic read that lands on the
-     * evaluating cell is a cycle on any path (design §5).
-     */
     private _toReference;
     /** @inheritdoc IFormulaContext.getAddress */
     getAddress(coords?: Readonly<IRange.FixableCoords | IRange.FixableCellCoords>, r1c1?: boolean): string;
@@ -205,6 +197,8 @@ export declare class CalculationContext implements IFormulaContext {
     toText(value: Scalar | undefined): string;
     /** @inheritdoc IFormulaContext.getRuntime */
     getRuntime(): IRuntime;
+    /** @inheritdoc IFormulaContext.createRichData */
+    createRichData(type: string, data?: any): IRichData;
     /** @inheritdoc IFormulaContext.getArgs */
     getArgs(): IFunctionArguments;
     get [Symbol.toStringTag](): string;