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

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,15 @@ export declare class SpillEntry {
     private _c;
     private _k;
     private _cycleId;
-    constructor(coords: IRange.Coords, cycleId: number, kind?: ITypes.FormulaArrayKind);
+    private _h;
+    /**
+     * @param holder The anchor's holder when the evaluation that laid the spill out deferred
+     * (DESIGN-ASYNC §4.4): the anchor cell holds the first element, so the entry carries what a
+     * scalar cell holds in its value, and moves and versions with the spill the same way.
+     */
+    constructor(coords: IRange.Coords, cycleId: number, kind?: ITypes.FormulaArrayKind, holder?: AsyncValue | 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;
@@ -52,4 +61,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.
  *
@@ -43,14 +44,23 @@ export interface CalcScope {
     firstCell: boolean;
     /**
      * Set when the evaluation read something that is PER CELL rather than a property of its inputs
-     * — a random draw (`IFormulaContext.getRandom`), a position (`getRow`, `getColumn`, `getFormulaAt`,
-     * `getSheetIndex`, a reference's `getCoords`), 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.
+     * — 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
+     * reference's `getCoords`. Per cell like {@link perCellRead}, but a position is the one per-cell
+     * input whose effect the representative can rule out: when every position read sits under a
+     * boolean test the result does not depend on (`AND(ISODD(ROW()),$A1<>"")` over a blank `A`),
+     * the answer is still shared (`IFormulaBlock.getPositionVariants`). Cleared and read alongside
+     * {@link perCellRead}.
+     */
+    positionRead: boolean;
     /**
      * How many draws (`IFormulaContext.getRandom`) this evaluation has taken, from `0`.
      *
@@ -61,6 +71,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,16 +23,22 @@ 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
      * `demandValue` in place of an `evaluateAt`.
      */
     readonly Circular: number;
+    /**
+     * The node's last evaluation found it volatile: the formula names a volatile function
+     * (`IFormulaContext.markVolatile`, which the compiled `hasVolatile` spends), it read cells its
+     * text does not name (a dynamic precedent of kind `Reference`: `OFFSET`, `INDIRECT`), or it is
+     * a member of an iterated cycle. Cleared when an evaluation of the node starts, so it answers
+     * for the last one; persists across passes that skip the node. What `isVolatileAt` reports —
+     * the executor's volatile SET is the pass's own worklist, rebuilt every pass, and is not read
+     * for the answer.
+     */
+    readonly Volatile: number;
     /**
      * A `Waiting` node — or a finished member of a cycle that is still open — the evaluation in
      * progress has read under iterative calculation: it is in
@@ -72,6 +78,32 @@ 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;
+    /**
+     * The node's one call answered with a shape its cell cannot take without the layout machinery
+     * — a range, or the cell is a spill anchor — and a settle seeded it (DESIGN-ASYNC §4.5): the
+     * settle pass takes the holder's latest in place of running the body and lays it out as any
+     * range result. Any other pass clears it and evaluates, since the node may be dirty for its own
+     * reasons. Outside {@link PassMask}: set between passes.
+     */
+    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;
 };

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;
@@ -37,8 +38,8 @@ export declare class CalculationContext implements IFormulaContext {
      */
     protected _dynamicRead: ReadHook | null;
     /**
-     * Marks the evaluation in progress as having read something PER CELL — a position — so its
-     * answer cannot stand in for another cell's (`CalcScope.perCellRead`). One closure for the
+     * Marks the evaluation in progress as having read its position, so its answer stands in for
+     * another cell's only where the position cannot matter (`CalcScope.positionRead`). One closure for the
      * context's lifetime: every reference it builds is handed this for its `getCoords`, and the
      * context's own position accessors call it directly.
      */
@@ -60,6 +61,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
      *
@@ -81,6 +98,12 @@ export declare class CalculationContext implements IFormulaContext {
     _createScoped(sheet: string): CalculationContext | null;
     /** @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 +112,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 */
@@ -205,6 +230,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;

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

@@ -0,0 +1,260 @@
+import { IFormulaContext, IRange, IRichData, Scalar } from '@sheetxl/primitives';
+import { ISpatialMap } from '../../collections';
+import { AsyncValue } from '../../primitives/AsyncValue';
+import { CalcNode } from './CalcNode';
+import { CalcScope } from './CalcScope';
+/**
+ * Where a call stands: still wanted and unanswered, answered, failed, or closed.
+ */
+export declare const CallState: {
+    readonly Open: 0;
+    readonly Settled: 1;
+    readonly Rejected: 2;
+    readonly Closed: 3;
+};
+export type CallState = typeof CallState[keyof typeof CallState];
+/**
+ * One `IFormulaContext.defer` at one site of one cell's formula (DESIGN-ASYNC §4.4): what the
+ * executor is handed, and what a later evaluation of the cell finds again by its ordinal.
+ */
+export declare class DeferredCall implements IFormulaContext.DeferredCall {
+    readonly id: number;
+    readonly executor: IFormulaContext.DeferExecutor;
+    readonly payload: unknown;
+    /** Which function made the call (its declaration), or `null` for one with none. */
+    readonly site: object | null;
+    /**
+     * The node whose evaluation made, last served, or now holds the call (DESIGN-ASYNC §4.5 settle
+     * step 1); `null` for an evaluation with no cell. A re-mint of the cell's node takes it over.
+     */
+    owner: CalcNode | null;
+    state: CallState;
+    /** The most recent result; `undefined` until one arrives. */
+    latest: unknown;
+    protected _onCancel: (() => void)[] | null;
+    /** The port (DESIGN-ASYNC §4.9): told each time the latest moves. */
+    protected _onMoved: ((call: DeferredCall) => void) | null;
+    /** Told of the call's final answer: the manager, which holds the call only until then. */
+    protected _onFinal: ((call: DeferredCall) => void) | null;
+    /** Makes a result cell-ready (see {@link DeferredCalls.Normalize}). */
+    protected _normalize: DeferredCalls.Normalize;
+    constructor(id: number, executor: IFormulaContext.DeferExecutor, payload: unknown, site: object | null, owner: CalcNode | null, onMoved?: ((call: DeferredCall) => void) | null, onFinal?: ((call: DeferredCall) => void) | null, normalize?: DeferredCalls.Normalize);
+    /** @inheritdoc IFormulaContext.DeferredCall.resolve */
+    resolve(value: unknown): void;
+    /** @inheritdoc IFormulaContext.DeferredCall.reject */
+    reject(error: unknown): void;
+    /** @inheritdoc IFormulaContext.DeferredCall.onCancel */
+    onCancel(fn: () => void): void;
+    /** @inheritdoc IFormulaContext.DeferredCall.cancelled */
+    get cancelled(): boolean;
+    /** Whether the call has not answered yet: it is running, and a recalculation leaves it be. */
+    isOpen(): boolean;
+    /** Closes the call; `onCancel` runs when it had not finished. */
+    close(): void;
+    protected _moved(): void;
+    protected _final(): void;
+}
+/** The default settle window (DESIGN-ASYNC §4.8): at most one settle pass per window. */
+export declare const DefaultSettleWindow = 100;
+/** What an evaluation that deferred leaves for the cell: its calls, and whether the root is the only one. */
+export interface DeferredEvaluation {
+    readonly calls: readonly DeferredCall[];
+    /** The formula's root is its only call: the cell's value is that call's answer. */
+    readonly direct: boolean;
+}
+/**
+ * The holder at a cell, if any: the engine grid's value there, or the entry of the spill anchored
+ * there when the cell is an anchor (the anchor cell itself holds the first element).
+ */
+export type HeldAt = (gridId: string, row: number, column: number) => AsyncValue<DeferredCall> | null;
+/**
+ * The calls a calculation backend has made, the batch the evaluation in progress is collecting,
+ * and the state each executor keeps (DESIGN-ASYNC §4.3, §4.4).
+ *
+ * @remarks
+ * One per backend. Nothing here is touched by an evaluation that does not defer: the dispatch
+ * notices a deferral through {@link CalcScope.deferCount}, and only then asks this.
+ */
+export declare class DeferredCalls {
+    protected _scope: CalcScope;
+    protected _heldAt: HeldAt;
+    protected _getRandom: () => number;
+    protected _nextId: number;
+    /** The calls that have not given their final answer, by id. A holder names any other by pointer. */
+    protected _calls: Map<number, DeferredCall>;
+    protected _onFinal: (call: DeferredCall) => void;
+    /** Whether a holder has ever been written: until then no read needs to look for one. */
+    protected _holders: boolean;
+    /** The calls of the evaluation in progress, by ordinal, and which of them it made. */
+    protected _current: DeferredCall[];
+    protected _made: DeferredCall[];
+    /** The calls made since the last {@link flush}, by executor: each executor's batch. */
+    protected _batch: Map<IFormulaContext.DeferExecutor, DeferredCall[]>;
+    /** What each executor keeps between batches (`IBatchContext.getState`). */
+    protected _states: Map<IFormulaContext.DeferExecutor, unknown>;
+    protected _batchContext: IFormulaContext.IBatchContext;
+    protected _setCurrent: (executor: IFormulaContext.DeferExecutor | null) => void;
+    /**
+     * The port (DESIGN-ASYNC §4.9): the calls whose latest moved since the last settle pass took
+     * them. A set, so a bursting feed is one entry however often it posts: the latest is on the call.
+     */
+    protected _moved: Set<DeferredCall>;
+    protected _onMoved: (call: DeferredCall) => void;
+    /** The settle pass, run on its own task at most once per window (DESIGN-ASYNC §4.8). */
+    protected _onSettle: (() => void) | null;
+    protected _settleWindow: number;
+    protected _settleTimer: ReturnType<typeof setTimeout> | null;
+    protected _settledAt: number;
+    /** The grids a settle told the model about without a write: the next pass vends their records. */
+    protected _repaintGrids: Set<string>;
+    /** The cells a settle marked for re-evaluation, scoped: the next pass's seeds, beside its own. */
+    protected _settleDirty: ISpatialMap.Entry[];
+    protected _normalize: DeferredCalls.Normalize;
+    /**
+     * Every site is served its call (a settle pass, or an evaluation waiting on its answers);
+     * otherwise only a running call is, and a stopped one is called again (DESIGN-ASYNC §4.5).
+     */
+    protected _serving: boolean;
+    /** The batch the next {@link flush} hands out fetches past the workbook's cache (`CalculateOptions.external`). */
+    protected _external: boolean;
+    /** {@link _batchContext}, with a `fetch` that goes to the source. */
+    protected _reloadContext: IFormulaContext.IBatchContext;
+    /**
+     * The last answer the site's call gave for the same question, read by `IFormulaContext.defer`
+     * right after {@link defer}: `undefined` when there was none.
+     */
+    previous: unknown;
+    /** The {@link whenChanged} waits in progress: woken by a final answer, a settle pass starting, a cancel. */
+    protected _waiters: Set<() => void>;
+    /**
+     * Told when the counts may have changed, at the moments they become visible: calls handed out,
+     * a settle pass starting, a cancel, a close. Never per answer: a million answers are one settle.
+     */
+    protected _onCountsChange: (() => void) | null;
+    constructor(scope: CalcScope, heldAt: HeldAt, getRandom: () => number, onSettle?: (() => void) | null, settleWindow?: number, normalize?: DeferredCalls.Normalize, services?: DeferredCalls.Services, onCountsChange?: (() => void) | null);
+    /** How many calls have not answered. `0` lets a pass skip every pending-input check. */
+    getOpenCount(): number;
+    /** The held calls whose owner is a cell of `gridId`. */
+    getCallsOf(gridId: string): DeferredCall[];
+    /** Whether an answer that landed has yet to be applied: its settle pass is still to run. */
+    hasSettleWork(): boolean;
+    /**
+     * Resolves at the next change a wait for answers cares about — a call's final answer, a settle
+     * pass starting, a cancel — or after `timeout` ms, whichever is first.
+     */
+    whenChanged(timeout: number): Promise<void>;
+    protected _wake(): void;
+    /**
+     * Closes every held call whose owner `cover` covers (`ICalculation.cancelAsync`): `onCancel`
+     * runs, and a later answer is dropped. A cancelled call stays in its holders: its cell is served
+     * what it shows now, and asks again only on an external calculation.
+     *
+     * @param cover `true` for every call, a grid id for one grid's, scoped coords for a range's.
+     * @returns The calls closed, for the caller to re-evaluate their owners.
+     */
+    cancel(cover: true | string | IRange.Coords): DeferredCall[];
+    /** Closes `calls`: those still owed an answer run `onCancel`, and a later answer is dropped. */
+    closeCalls(calls: Iterable<DeferredCall>): void;
+    /** Whether any grid of this backend may hold an {@link AsyncValue}: what gates every unwrap. */
+    hasHolders(): boolean;
+    /** The open call with `id`; `undefined` once it has given its final answer, or for one unknown. */
+    getCall(id: number): DeferredCall | undefined;
+    /** Drains the port: every call whose latest moved since the last drain. */
+    takeMoved(): DeferredCall[];
+    /** Records that a settle told the model about a cell of `gridId` without a write. */
+    noteRepaint(gridId: string): void;
+    /** Marks `cells` (scoped) for the next pass to collect: a settled composite owner, or a dependent of a direct one. */
+    addSettleDirty(cells: readonly ISpatialMap.Entry[]): void;
+    /** The cells settles marked since the last pass; empties them. */
+    takeSettleDirty(): ISpatialMap.Entry[];
+    /** The grids with a repaint since the last pass, for the pass to vend; empties them. */
+    takeRepaintGrids(): string[];
+    /**
+     * Asks for a settle pass: at once on the leading edge, else when the window since the last one
+     * ends. Always a fresh task, so an executor settling synchronously cannot re-enter the pass that
+     * ran it.
+     */
+    protected _requestSettle(): void;
+    /**
+     * The cell's value for an evaluation that deferred; for one that spilled, what its spill entry
+     * carries. From here on reads must look for holders.
+     */
+    newHolder(value: Scalar | IRange, evaluation: DeferredEvaluation): AsyncValue<DeferredCall>;
+    /**
+     * Takes one `defer` from the evaluation in progress: the call this site made last time when the
+     * same function made it with an equal payload and it still stands, or a new one for the batch.
+     * It stands while it runs: a recalculation leaves it be. Once it has
+     * stopped, a recalculation calls the function again; only an answer landing ({@link setServing})
+     * serves a stopped call. Same function, not same executor: an inline executor is a new closure
+     * every evaluation, and is still served.
+     *
+     * @param site Which function is deferring (its declaration); `null` compares executors instead. The site's last call is the one the
+     * holder in its cell names at this ordinal, so a version of the grid brought back by an undo,
+     * or a cell moved by a shift, is answered by the call it was given.
+     * @param volatile The function declares itself volatile: it asks again on every evaluation,
+     * payload equal or not, as `RAND()` re-rolls (DESIGN-ASYNC §4.7).
+     * @returns The call the site was served, for the dispatch around the body to answer its latest
+     * in place of the body's return; `null` for a new call.
+     */
+    defer(executor: IFormulaContext.DeferExecutor, payload: unknown, site?: object | null, volatile?: boolean): DeferredCall | null;
+    /**
+     * Ends the deferring evaluation in progress: its calls, by ordinal. Resets the scope's
+     * per-evaluation fields.
+     */
+    endEvaluation(): DeferredEvaluation;
+    /**
+     * Ends an evaluation that will not stand — a probe of whether an answer can be shared — without
+     * keeping its calls: what it made never reaches an executor.
+     */
+    abandonEvaluation(): void;
+    /**
+     * Runs every executor once with the calls the batch collected for it (DESIGN-ASYNC §4.3). Each
+     * in its own try: a throw, or a promise that rejects, fails the calls it has not settled and no
+     * other executor's.
+     */
+    flush(): void;
+    /** Closes every open call and drops every batch and state: the backend is going away. */
+    close(): void;
+    /**
+     * Whether every site is served its call until the next {@link flush}: a settle pass, whose
+     * re-evaluations are answers landing, or an evaluation waiting on its own calls.
+     */
+    setServing(serving: boolean): void;
+    /**
+     * Whether the batch the next {@link flush} hands out fetches past the workbook's cache, to the
+     * source (`CalculateOptions.external`, `cache: 'reload'`).
+     */
+    setExternal(external: boolean): void;
+    protected _coversCell(cover: true | string | IRange.Coords, gridId: string | null, row: number, column: number): boolean;
+    protected _batchFor(executor: IFormulaContext.DeferExecutor): DeferredCall[];
+    /**
+     * The call this site of the evaluation in progress made last time: what its cell's holder names,
+     * or, for a formula held in no cell (a temporary one), the holder its node keeps.
+     */
+    protected _siteCall(ordinal: number): DeferredCall | undefined;
+}
+export declare namespace DeferredCalls {
+    /**
+     * Makes a result cell-ready as it arrives, so a holder always reads as something a cell can
+     * hold: an author's array (`[[1],[2]]`, DESIGN-ASYNC §7.3) becomes a range, and a one-cell
+     * range its scalar. The backend supplies it; a scalar or a multi-cell range passes as is.
+     */
+    type Normalize = (value: unknown) => unknown;
+    /** What the backend lends an executor through its batch context; each omitted, a default. */
+    interface Services {
+        /** Makes rich values for the backend's workbook. Omitted, made outside any workbook. */
+        createRichData?: (type: string, data?: any) => IRichData;
+        /** Adds resources to the backend's workbook. Omitted, made outside any workbook. */
+        addResource?: (buffer: ArrayBuffer, options?: {
+            fetchedFrom?: string;
+        }) => object;
+        /** The workbook's fetch. Omitted, the global `fetch`. */
+        fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+    }
+}
+/**
+ * Whether two payloads are the same question (DESIGN-ASYNC §4.3): `Object.is`, or for two plain
+ * objects or arrays, `Object.is` over their own enumerable values one level deep.
+ */
+export declare const samePayload: (a: unknown, b: unknown) => boolean;
+//# sourceMappingURL=DeferredCalls.d.ts.map

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

@@ -1,5 +1,6 @@
 import { Scalar, IRange, IRuntime, IFormulaContext } from '@sheetxl/primitives';
 import { ISparseGrid, ISpatialMap, ISpatialMap3D, ISpatialQuery } from '../../collections';
+import { IRichDataKind } from '../../richData';
 import { ISymbolRegistry } from '../symbol';
 import { IFormulaBlock, FormulaImager } from '../formula';
 import { PrecedentSpatialValue, PrecedentKind, FormulaSpatialValue } from '../spatial';
@@ -9,6 +10,8 @@ import { ICalculation } from '../ICalculation';
 import { NamedNodeInfo } from '../Types';
 import { CalcNode } from './CalcNode';
 import { CalcScope } from './CalcScope';
+import { DeferredCalls } from './DeferredCalls';
+import { WhatIfTable } from '../executor/_WhatIf';
 /**
  * Interface to allow grids to interact with calculation container.
  */
@@ -56,8 +59,24 @@ export interface IContextContainer {
     getSheetSpanIds?: (scopeId: string) => string[] | null;
     /** Every sheet's grid id in tab order, hidden sheets included. */
     getSheetIds?: () => readonly string[];
+    /**
+     * Whether a sheet in the tab order has no grid: a chart, macro or dialog sheet. Such a sheet counts
+     * in a span's members and gives no values; it cannot be a span's endpoint.
+     */
+    isGridless?: (sheetId: string) => boolean;
     getScope(): CalcScope;
+    /**
+     * The calls the container's evaluations deferred (`IFormulaContext.defer`), with each
+     * executor's batch. Absent, or `null`, where nothing can answer later: a deferring function's
+     * return value is then its answer.
+     */
+    getDeferred?(): DeferredCalls | null;
     getRuntime(): IRuntime;
+    /**
+     * What rich values a formula makes are made for: the workbook's resources and strings.
+     * Absent, they are made outside any workbook.
+     */
+    getRichDataContext?(): IRichDataKind.Context;
     /**
      * Returns the current datetime in milliseconds.
      */
@@ -162,6 +181,13 @@ export interface IContextContainer {
      * objects, copy-on-write per request.
      */
     setGridMaps(gridId: string, maps: object): void;
+    /**
+     * The clone key the requests of the batch being applied share (`ISpatialMap.clone`'s), while a
+     * held batch or a collecting batch of grids applies; `null` otherwise. The batch is one engine
+     * operation, so a map one of its requests cloned is the one the next writes into, rather than a
+     * copy per request.
+     */
+    getHeldCloneKey?(): string | null;
     /**
      * The model has restored itself to `commitId` (an undo, a redo): restore the engine's history
      * to it, once, and answer the regions of `gridId` that changed between the two snapshots. A
@@ -322,6 +348,12 @@ export interface IContextContainer {
      * recover which is which from the coords.
      */
     addDynamicPrecedent(calcNode: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind): void;
+    /**
+     * The results of a what-if data table, for the `TABLE` node being evaluated (the scope's node):
+     * its affected cells re-evaluated under each substitution, nothing written
+     * (DESIGN-DATA-TABLES §4.3). Only during a pass.
+     */
+    evaluateWhatIf(table: WhatIfTable): Scalar[][];
     /**
      * Queues an action to run at the engine's next safe point, and schedules that point.
      *

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

@@ -160,4 +160,10 @@ export declare class PendingOverlayGrid implements ISparseGrid<Scalar>, Referenc
     protected _commitAll(): void;
     get [Symbol.toStringTag](): string;
 }
+/**
+ * Whether `grid` reads an error inside the rectangle, by walking it. Shared with `WhatIfLayer`.
+ *
+ * @internal
+ */
+export declare function _scanHasError(grid: ISparseGrid<Scalar>, coords: IRange.Coords): boolean;
 //# sourceMappingURL=_PendingOverlayGrid.d.ts.map