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

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

@@ -0,0 +1,207 @@
+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];
+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;
+    owner: CalcNode | null;
+    state: CallState;
+    /** The most recent result; `undefined` until one arrives. */
+    latest: unknown;
+    protected _onCancel: (() => void)[] | null;
+    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, options?: IFormulaContext.DeferredCall.ResolveOptions): 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;
+}
+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;
+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 (`IDeferContext.getState`). */
+    protected _states: Map<IFormulaContext.DeferExecutor, unknown>;
+    protected _deferContext: IFormulaContext.IDeferContext;
+    protected _setCurrent: (executor: IFormulaContext.DeferExecutor | null) => void;
+    protected _moved: Set<DeferredCall>;
+    protected _onMoved: (call: DeferredCall) => void;
+    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;
+    protected _serving: boolean;
+    /** The batch the next {@link flush} hands out fetches past the workbook's cache (`CalculateOptions.external`). */
+    protected _external: boolean;
+    /** {@link _deferContext}, with a `fetch` that goes to the source. */
+    protected _reloadContext: IFormulaContext.IDeferContext;
+    /**
+     * 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>;
+    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;
+    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 {
+    type Normalize = (value: unknown, options?: IFormulaContext.DeferredCall.ResolveOptions) => unknown;
+    /** What the backend lends an executor through its defer 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>;
+        /** The workbook's context with no cell. Omitted, asking for it throws. */
+        getFormulaContext?: () => IFormulaContext;
+        /** Reads delimited text as the workbook reads typed entry. Omitted, it rejects. */
+        parseText?: (text: string, options?: IFormulaContext.IDeferContext.ParseTextOptions) => Promise<Scalar[][]>;
+    }
+}
+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.
  */
@@ -62,7 +65,18 @@ export interface IContextContainer {
      */
     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.
      */
@@ -125,36 +139,8 @@ export interface IContextContainer {
      * Returns the grid for a given gridId. This is used to get other grids when calculating.
      */
     getGrid(gridId: string): CalcGridBackend | null;
-    /**
-     * Runs a request against the engine's state, landing what it writes under the snapshot it
-     * names (DESIGN-CALC-SERVICE §13.13: the engine keeps its own history keyed by the model's
-     * ids).
-     *
-     * @param landingId The engine commit the request lands in: the model's commit for a root
-     * transaction, its savepoint for a nested one, or `undefined` for a request naming no snapshot
-     * (a caller with no model), which is applied as it is.
-     * @param action The request; its writes land together.
-     */
     landRequest<R>(landingId: string | undefined, action: () => R): R;
-    /**
-     * Sends a grid request through the service's channel (DESIGN-CALC-SERVICE §4, §7.2).
-     *
-     * @param gridId The grid the request is for.
-     * @param landingId The engine commit a request applied now lands in - see {@link landRequest}.
-     * @param request The request, as data.
-     *
-     * @remarks
-     * On a `Running` engine the request is applied at once and lands under `landingId`. While the
-     * engine is `Starting` it is held, in send order, and applied once the engine is up, behind the
-     * seeds; one whose snapshot the model has undone by then is dropped. On an `Off` engine nothing
-     * is recorded and the request resolves with nothing: a later start is seeded from the model.
-     */
     sendRequest(gridId: string, landingId: string | undefined, request: CalcRequest): Promise<ICalcGrid.Results>;
-    /**
-     * What images a grid's records for the model (DESIGN-CALC-SERVICE §8): the model's symbol
-     * map, the grid as home scope, its bounds, the reader's locale. The facade's, read where a
-     * response crosses to the model.
-     */
     getImager(gridId: string): FormulaImager;
     /**
      * Records the regions a request touched on the commit it is landing in, so a revert knows what
@@ -334,32 +320,7 @@ export interface IContextContainer {
      * recover which is which from the coords.
      */
     addDynamicPrecedent(calcNode: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind): void;
-    /**
-     * Queues an action to run at the engine's next safe point, and schedules that point.
-     *
-     * @remarks
-     * Safe means two things, and they are why this exists rather than calling inline: the engine can
-     * actually do the work (the compiler is loaded, grids are populated), and the synchronous work
-     * that queued the action has finished — a `setInputs` run re-entrantly during an active commit is
-     * what produced the intermittent `OutOfOrderError` in the value builder.
-     *
-     * No guard is required. Queuing schedules its own drain, so an action queued here always runs:
-     * while `Starting` it is held for `start()`'s drain, inside a drain it joins the pass already
-     * running, and on a settled engine a microtask drain is posted for it.
-     *
-     * It did require one, and was called `whenStarting` for that reason — the queue was pumped only
-     * as a side effect of `start`/`ready`/`calculate`, so an action queued on a settled engine waited
-     * for a calculation that might never come and was dropped rather than delayed. Callers written
-     * against that rule (guarding on {@link isLoading} or a `Starting` status) remain correct; the
-     * guard is now redundant, not wrong.
-     *
-     * What a caller does owe: the action must be safe to run at an arbitrary microtask boundary, not
-     * only from inside a calculation.
-     *
-     * For the engine's own deferrals (wiring a name, recompiling its dependents), which stay
-     * backend-side. A grid request is never queued here: it goes through {@link sendRequest}, as
-     * data, so the channel can hold it (DESIGN-CALC-SERVICE §6.2).
-     */
+    evaluateWhatIf(table: WhatIfTable): Scalar[][];
     whenSafe(action: () => Promise<unknown>): void;
     /**
      * `true` while the engine is either `Starting` or inside a pending-action drain — at any drain
@@ -381,8 +342,11 @@ export interface IContextContainer {
      * so dependents pick up the change. A recompile, not a dirty-mark, on purpose: a definition
      * change requires dependents to re-derive their precedents (`setInputs`), which `markDirty` does
      * not do. Where a re-evaluation suffices, use {@link invalidateNamed} instead.
+     *
+     * @param loaded The name's definition has not changed: its body is the one the file holds, only
+     * now compiled. A formula still as it was loaded re-derives its precedents and keeps its value.
      */
-    recompileNamed(nameId: string): void;
+    recompileNamed(nameId: string, loaded?: boolean): void;
     /**
      * Marks every formula that references `nameId` — directly or through another name — dirty, so it
      * re-evaluates against the name's current definition.

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

@@ -0,0 +1,5 @@
+/** @internal */
+export declare const markKeepBlanks: (result: object) => void;
+/** @internal */
+export declare const isKeepBlanks: (result: object) => boolean;
+//# sourceMappingURL=_KeepBlanks.d.ts.map

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

@@ -3,48 +3,51 @@ import { Direction, RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
 import { IGrid, ISparseGrid, Tuple, IListLike } from '../../collections';
 import { ReferenceErrorIndex } from '../../primitives/ReferenceRange';
 /**
- * The calc grid's committed values with the pass's UNCOMMITTED results laid over them.
+ * The batch's cells: every result of a pass goes in here and most are read straight back out, so
+ * this is an open-addressed table on (row, col) rather than a `Map`.
  *
  * @remarks
- * The executor batches results and commits them in one write (`writeCalcs`); a reference built
- * during the pass used to force that commit whenever it could see a batched cell. On a row-chained
- * sheet (`SUM($K$51:K#)` on every row) that was a commit per row — thousands of small persistent
- * writes into the same long runs. This grid serves those reads from the batch instead, so the
- * executor commits every N results and the writes are few and contiguous.
- *
- * It is a SUBSTITUTION view: iteration walks the committed runs and swaps in the pending value
- * where one exists. That only describes a cell the committed grid already holds; a result for a
- * cell with no committed run under it (a formula's first result — new after load, entry, paste)
- * cannot be shown this way, so such a push marks the overlay `uncovered` and the next ITERATION
- * over the pending box commits first (`_coverFor`), which is exactly the old behavior; a point
- * read is answered by the map and never commits. A steady-state recalc never trips it. Reads
- * outside the batch's bounding box never touch the map.
- *
- * Operations that materialize or write go through a commit first and then the committed grid —
- * the safe fallback for anything a substitution cannot answer (`getValues`, `copyTo`, `clone`,
- * every write). `cloneEmpty` needs no values.
- *
- * It is also the error index of references built over it ({@link ReferenceErrorIndex}): the
- * committed index plus a scan of the pending map, taken only while the batch holds an error.
- *
- * A second layer holds DEMAND results (DESIGN-CIRCULAR-CALC.md §4.6): what demand evaluation and
- * the iteration sweeps compute ahead of the plan. It is not part of the batch — a commit leaves it
- * alone — and an entry lives until the plan takes its node ({@link takeDemand}), which then pushes
- * the same value to the batch. A sweep rewrites its members many times, and every rewrite is a map
- * write, not a persistent one. Substitution still needs a committed run under the cell, so the
- * first result for a cell with nothing under it is written through as well; every later one is
- * substituted.
+ * Consecutive rows of a column take consecutive slots, which is the order a filled block runs in,
+ * so a chain probes once per cell. A commit empties it, so it is never much larger than a batch. A
+ * value of `undefined` means no entry; a blank is held as `null`.
  */
+declare class PendingCells {
+    size: number;
+    private _keys;
+    private _values;
+    /** The occupied slots in the order they were filled. */
+    private _order;
+    private _mask;
+    /** The slot holding the cell, or the empty one it would take. The table is never full. */
+    private _slotOf;
+    get(row: number, col: number): Scalar | undefined;
+    /** @returns What the cell held, or `undefined` for a new one. */
+    set(row: number, col: number, value: Scalar): Scalar | undefined;
+    clear(): void;
+    /** Whether a cell added at or after position `from` of the fill order has nothing in `grid`. */
+    anyAbsentFrom(from: number, grid: ISparseGrid<Scalar>): boolean;
+    /** Whether an error is held inside the rectangle. */
+    hasErrorIn(rowStart: number, colStart: number, rowEnd: number, colEnd: number): boolean;
+    private _grow;
+}
 export declare class PendingOverlayGrid implements ISparseGrid<Scalar>, ReferenceErrorIndex {
     protected readonly _inner: ISparseGrid<Scalar>;
     protected readonly _committed: ReferenceErrorIndex;
     protected readonly _flush: () => void;
     protected readonly _isColumn: boolean;
-    protected _pending: Map<number, Scalar>;
+    protected _pending: PendingCells;
+    /** Results pushed before anything read through here: counted, and not in {@link _pending}. */
+    protected _unobserved: number;
+    /** A read has landed in the pending box this pass, so results are held in {@link _pending}. */
+    observed: boolean;
     /** Pending values that are errors — the pending scan in {@link hasErrorIn} runs only while > 0. */
     protected _errors: number;
     /** A pending cell has no committed run under it; substitution cannot show it. */
     protected _uncovered: boolean;
+    /** The pending cells {@link _uncovered} has answered for. Only an iteration asks, so a push does not look. */
+    protected _coverChecked: number;
+    /** Where the copy {@link _substituteRun} last made starts. */
+    protected _substitutedFrom: number;
     protected _rowStart: number;
     protected _rowEnd: number;
     protected _colStart: number;
@@ -89,6 +92,8 @@ export declare class PendingOverlayGrid implements ISparseGrid<Scalar>, Referenc
     protected _growAny(row: number, col: number): void;
     /** Rebuilds the union box from the two layers' own. */
     protected _resetAny(): void;
+    /** From here on results are held in the map; what was pushed before it is committed now. */
+    observe(): void;
     /** Does a rectangle overlap the bounding box of the cells either layer holds? */
     intersects(rowStart: number, colStart: number, rowEnd: number, colEnd: number): boolean;
     /** Does a rectangle overlap the pending (batch) cells' bounding box? */
@@ -104,7 +109,7 @@ export declare class PendingOverlayGrid implements ISparseGrid<Scalar>, Referenc
      */
     protected _writeDemandIn(bounds: Partial<RangeCoords> | null | undefined): void;
     /** The cell's value in either layer (they never share a cell), or `undefined`. */
-    protected _layered(key: number): Scalar | undefined;
+    protected _layered(row: number, col: number): Scalar | undefined;
     /**
      * Before an ITERATION over `bounds`: commits when a pending cell substitution cannot show
      * (`uncovered`) lies inside them. A point read never needs this — the map answers it — and
@@ -118,8 +123,15 @@ export declare class PendingOverlayGrid implements ISparseGrid<Scalar>, Referenc
     protected _inBounds(row: number, col: number): boolean;
     /** Nothing in either layer: every read is the committed grid's. */
     protected _isEmpty(): boolean;
-    /** The run with pending values swapped in, or the run itself when none fall inside it. */
-    protected _substituteRun(major: number, minorFrom: number, run: IListLike<Scalar>): IListLike<Scalar>;
+    /**
+     * The part of a run a read asked for with pending values swapped in, or the run itself when none
+     * fall inside that part. A copy starts at {@link _substitutedFrom}.
+     *
+     * @remarks
+     * A stored run can be a whole column, so a copy is never wider than the read: a short range over
+     * a long run costs what the range costs.
+     */
+    protected _substituteRun(major: number, minorFrom: number, run: IListLike<Scalar>, readFrom: number, readTo: number): IListLike<Scalar>;
     /** {@inheritDoc IGrid.getValueAt} */
     getValueAt(row: number, column: number): Scalar;
     /** {@inheritDoc ISparseGrid.getRuns} */
@@ -160,4 +172,11 @@ 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;
+export {};
 //# sourceMappingURL=_PendingOverlayGrid.d.ts.map

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

@@ -0,0 +1,77 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { Direction, RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
+import { Tuple, IGrid, ISparseGrid, IListLike } from '../../collections';
+import { ReferenceErrorIndex } from '../../primitives/ReferenceRange';
+export declare class WhatIfLayer implements ISparseGrid<Scalar>, ReferenceErrorIndex {
+    protected readonly _inner: ISparseGrid<Scalar>;
+    protected readonly _committed: ReferenceErrorIndex;
+    protected readonly _isColumn: boolean;
+    protected _map: Map<number, Scalar>;
+    /** Substituted values that are errors — the scan in {@link hasErrorIn} runs only while > 0. */
+    protected _errors: number;
+    protected _rowStart: number;
+    protected _rowEnd: number;
+    protected _colStart: number;
+    protected _colEnd: number;
+    constructor(inner: ISparseGrid<Scalar>, committed: ReferenceErrorIndex);
+    get isWhatIfLayer(): true;
+    /** The committed grid. */
+    getInner(): ISparseGrid<Scalar>;
+    /** Substituted cells. */
+    get size(): number;
+    /** Substitutes `value` at the cell. A blank is kept as a blank (`null`), as an axis cell's is. */
+    set(row: number, col: number, value: Scalar): void;
+    /** Drops every substitution: the committed grid answers everything again. */
+    clear(): void;
+    /** Does a rectangle overlap the bounding box of the substituted cells? */
+    intersects(rowStart: number, colStart: number, rowEnd: number, colEnd: number): boolean;
+    /** {@inheritDoc ReferenceErrorIndex.hasErrorIn} */
+    hasErrorIn(coords: IRange.Coords): boolean;
+    /** Is the cell inside the substituted box? */
+    protected _inBounds(row: number, col: number): boolean;
+    /** The run with substituted values swapped in, or the run itself when none fall inside it. */
+    protected _substituteRun(major: number, minorFrom: number, run: IListLike<Scalar>): IListLike<Scalar>;
+    /** {@inheritDoc IGrid.getValueAt} */
+    getValueAt(row: number, column: number): Scalar;
+    /**
+     * {@inheritDoc ISparseGrid.getRuns}
+     *
+     * @remarks
+     * A substituted cell the committed grid does not hold at all (an input that was never written)
+     * is not shown by a run iteration: substitution only describes cells with a run under them, as
+     * the pending overlay's does. A point read answers it.
+     */
+    getRuns(options?: ISparseGrid.RunIteratorOptions): ISparseGrid.RunIterableIterator<Scalar>;
+    /** {@inheritDoc IGrid.entries} */
+    entries(options?: IGrid.IteratorOptions): IGrid.EntryIterator<Scalar>;
+    /** {@inheritDoc IGrid.values} */
+    values(options?: IGrid.IteratorOptions): IGrid.ValueIterator;
+    /** {@inheritDoc IGrid.keys} */
+    keys(options?: IGrid.IteratorOptions): IGrid.KeyIterator;
+    /** {@inheritDoc IGrid.getValues} */
+    getValues(coords?: RangeCoords): Tuple.Region<Scalar> | null;
+    /** {@inheritDoc IGrid.copyTo} */
+    copyTo(destination: IGrid, topLeft: CellCoords, from: RangeCoords): void;
+    /** {@inheritDoc IGrid.getAxis} */
+    getAxis(): RangeAxis;
+    /** {@inheritDoc IGrid.getCount} */
+    getCount(): number;
+    /** {@inheritDoc IGrid.getCoords} */
+    getCoords(): RangeCoords | null;
+    /** {@inheritDoc IGrid.getMaxCoords} */
+    getMaxCoords(): RangeCoords | null;
+    /** {@inheritDoc IGrid.clone} */
+    clone(_cloneKey?: any): this;
+    /** {@inheritDoc IGrid.cloneEmpty} */
+    cloneEmpty(cloneKey?: any): this;
+    /** {@inheritDoc IGrid.setValues} */
+    setValues(_values: Tuple.GridTuple<Scalar>): this;
+    /** {@inheritDoc IGrid.setValueAt} */
+    setValueAt(_row: number, _column: number, _value: Scalar): void;
+    /** {@inheritDoc IGrid.delete} */
+    delete(_coords: RangeCoords | null): boolean;
+    /** {@inheritDoc IGrid.shift} */
+    shift(_coords: RangeCoords, _direction: Direction): boolean;
+    get [Symbol.toStringTag](): string;
+}
+//# sourceMappingURL=_WhatIfLayer.d.ts.map

package/types/src/calculation/symbol/ExternalSheetSymbols.d.ts

@@ -1,16 +1,6 @@
 import { IExternalBookCollection, ExternalScopeParts } from '../../externalBook';
 import { ExternalBookCollection } from '../../externalBook/ExternalBookCollection';
 import { SheetSymbolHandle } from './SheetSymbolProvider';
-/**
- * The stable-id prefix that marks a sheet symbol as living in an external book.
- *
- * @remarks
- * `ext:<bookId>` is the book-scoped form (`[1]!Name`); `ext:<bookId>:<sheetIndex>` adds a sheet, and
- * `ext:<bookId>:<first>:<last>` is a 3-D span across the book's sheets (`[1]Alpha:Data Sheet`). The
- * prefix is the test every consumer uses — "is this scope external" is a `startsWith`, which is why
- * external books needed no new {@link SymbolType} and no new branch in the twenty-odd places that
- * ask the Sheet provider (DESIGN-EXTERNAL-LINKS §4B).
- */
 export declare const EXTERNAL_ID_PREFIX = "ext:";
 /** Is this stable id an external sheet or book? */
 export declare const isExternalSymbolId: (stableId: string | null | undefined) => boolean;
@@ -41,39 +31,7 @@ export interface ExternalBookMinter {
     /** Records `sheetName` on an existing book — answers the sheet's index. */
     addSheet(bookId: string, sheetName: string): number;
 }
-/**
- * Binds a sheet scope that names an external book, or `null` if it names none of this workbook's.
- *
- * @remarks
- * Every spelling a book answers to binds to the SAME id, so the storage form (`[1]Sheet1`), the
- * closed display form (`C:\dir\[Book.xlsx]Sheet1`) and the open one (`[Book.xlsx]Sheet1`) are three
- * ways of writing one symbol — which is the invariant that lets a handle's `toString()` be fed
- * straight back to `bind` (see {@link SheetSymbolProvider}).
- *
- * A position that does not exist (`[7]` of three books) answers `null`: the typed image is kept
- * verbatim, the reference is `#REF!`, and the writer warns. A file name matching more than one book
- * answers `null` too — the citation is genuinely ambiguous and `[n]` is the only spelling that is
- * not — unless the typed directory picks one of them out.
- *
- * A 3-D span (`[1]Alpha:Data Sheet`) binds to one id with its sheets in the book's own order, so
- * `[1]Data Sheet:Alpha` is the same symbol; both sheets must be listed.
- *
- * With a `minter`, a file name no book carries MINTS one (DESIGN-EXTERNAL-LINKS §4C): typing
- * `'C:\dir\[Book.xlsx]Sheet1'!A1` creates the link, cache empty, exactly as Excel does when it cannot
- * see the source. A sheet a known book does not list is recorded on it the same way. A `[n]` is never
- * minted — a position is a citation of something that exists, and a directory that differs from a
- * same-named book's is a different book, not a respelling of it. A span never mints either.
- */
 export declare function bindExternalScope(books: ExternalBookCollection | null | undefined, displayName: string, minter?: ExternalBookMinter | null, withinBook?: string | null): string | null;
-/**
- * Resolves an `ext:` stable id to a sheet handle, or `null` if the book has since been removed.
- *
- * @remarks
- * `toString()` is the projection DESIGN-EXTERNAL-LINKS §4B describes: `[n]Sheet1` by default — the
- * form a formula is STORED as, read off the book's current position — and the book's display name
- * when the caller asks for one. Both bind back. A span spells both sheets after one book prefix
- * (`[1]Alpha:Data Sheet`), as Excel writes it.
- */
 export declare function resolveExternalSymbol(books: ExternalBookCollection | null | undefined, stableId: string, display: boolean): SheetSymbolHandle | null;
 /** The `AddOptions` a minted book starts from: the typed directory and file, the typed sheet. */
 export declare function mintedBookOptions(parts: ExternalScopeParts): IExternalBookCollection.AddOptions;

package/types/src/calculation/symbol/ISymbolRegistry.d.ts

@@ -19,12 +19,6 @@ export interface SheetCtx {
      * (`'C:\dir\[Book.xlsx]Sheet1'`). A local sheet has one name and ignores this.
      */
     display?: boolean;
-    /**
-     * Bind is AUTHORING: a scope that names an external book this workbook has none of may create
-     * one (`'C:\dir\[Book.xlsx]Sheet1'` typed into a cell is how a link is made — DESIGN-EXTERNAL-LINKS
-     * §5 step 13). Off by default, and off for an editing compile, so a keystroke mints nothing; a
-     * local sheet is never minted.
-     */
     mint?: boolean;
     /**
      * The formula being linked belongs to an external BOOK — a cached defined name's body — so a

package/types/src/calculation/symbol/SheetSymbolProvider.d.ts

@@ -1,17 +1,5 @@
 import { IRange } from '@sheetxl/primitives';
 import { ISymbolProvider, SymbolHandle } from './ISymbolRegistry';
-/**
- * Strict provider for sheet symbols.
- *
- * @remarks
- * An EXTERNAL sheet is a sheet symbol too. A scope this workbook has no sheet for, and which names
- * a book (`[1]Sheet1`, `C:\dir\[Book.xlsx]Sheet1`), falls through to `_getExternal` rather than to a
- * `SymbolType` of its own — the twenty-odd consumers of a scope all ask this provider, and teaching
- * one provider a second spelling touches none of them (DESIGN-EXTERNAL-LINKS §4B).
- *
- * So is a 3-D span (`Alpha:Gamma`, PLAN-3D-REFS §2.1): one symbol naming its two endpoint sheets,
- * `<firstId>:<lastId>`, with the endpoints in tab order.
- */
 export declare class SheetSymbolProvider implements ISymbolProvider {
     private readonly _getId;
     private readonly _getById;

package/types/src/calculation/symbol/SymbolRegistry.d.ts

@@ -16,15 +16,6 @@ export declare class SymbolRegistry implements ISymbolRegistry {
     /** @inheritdoc ISymbolRegistry.resolve */
     resolve(type: SymbolType, stableId: string, ctx?: Record<string, unknown>): SymbolHandle | null;
 }
-/**
- * A registry that answers some symbol types from providers of its own and every other from a base.
- *
- * @remarks
- * The model's symbol map (DESIGN-CALC-SERVICE §8) is this over the engine's: the types the engine
- * keeps a copy of resolve through the model's live items here, while the rest resolve through the
- * engine's providers. Registering a provider registers it on the base, so a provider that arrives
- * late (the functions, once their module loads) is seen by both.
- */
 export declare class OverlaidSymbolRegistry implements ISymbolRegistry {
     private readonly _base;
     private readonly _overrides;