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

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

@@ -0,0 +1,523 @@
+import { IRange, FormulaError, Scalar, IFormulaContext } from '@sheetxl/primitives';
+import { RunCoords } from '@sheetxl/utils';
+import { Tuple, ISpatialQuery, ISparseGrid, ISpatialMap, ISpatialMap3D } from '../../collections';
+import { IContextContainer, CalcNode } from '../state';
+import { SpillEntry, FormulaSpatialValue, ContentfulSpatialValue, PrecedentSpatialValue, CircularEntry } from '../spatial';
+import { IFormulaBlock, FormulaRecord } from '../formula';
+import { ReferenceCoords, NamedReference } from '../Types';
+import { ICalculation } from '../ICalculation';
+import { ICalcGrid } from './ICalcGrid';
+import { GridRequest, CalcResponse } from './_CalcRequest';
+import { CalcGridProxy } from './CalcGridProxy';
+/**
+ * ICalcGrid implementation
+ */
+export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.Backend {
+    /**
+     * This is MOSTLY set by the user but spills also contribute.
+     * * Trying to keep lookups to a bare minimum.
+     */
+    _values: ISparseGrid<Scalar>;
+    _spillSpatial: ISpatialMap<SpillEntry>;
+    _errorSpatial: ISpatialMap<string>;
+    _pendingSpatial: ISpatialMap<boolean>;
+    _circularSpatial: ISpatialMap<CircularEntry>;
+    _contentfulSpatial: ISpatialMap<ContentfulSpatialValue>;
+    _notifyValues: ISpatialMap;
+    /** Accumulated bounds of the regions answered blank on a block; `null` until the first. */
+    _notifyBlank: IRange.Coords | null;
+    _notifySpillsInsert: ISpatialMap.Entry<SpillEntry>[];
+    _notifySpillsRemove: IRange.Coords[];
+    _notifyFormats: ISpatialMap;
+    _notifyPending: ISpatialMap<boolean>;
+    _notifyCircular: ISpatialMap<CircularEntry | false>;
+    /**
+     * Regions of this grid whose formula blocks were minted, re-imaged or removed since the last
+     * vend: the formula half of {@link ICalcGrid.Results}. Every site that rewrites a block appends
+     * here - on THIS grid, or on another grid's when a shift or a delete rewrote a cross-sheet
+     * reference there - and each mutator drains what it finds into its resolution, a calculation
+     * pass drains the rest into `onCalculated`. What is vended is the map's current blocks over these
+     * regions, so a region touched several times in one batch reports its final state once.
+     */
+    _touchedFormulas: IRange.Coords[];
+    /** Other grids a request applied here rewrote formulas in: told as the request lands. See {@link _apply}. */
+    protected _touchedOthers: Set<CalcGridBackend> | null;
+    _iterationId: number;
+    _options: CalcGridBackend.ConstructorOptions;
+    _getEntireCoords: () => IRange.Coords;
+    /** The size a `resize` gave, in place of {@link _getEntireCoords}; versioned with the maps. */
+    protected _resized: IRange.Coords | null;
+    /** The rows the owner hides, ascending and disjoint; `null` for none. Versioned with the maps. */
+    protected _hiddenRows: readonly RunCoords[] | null;
+    /** The columns the owner hides, as {@link _hiddenRows}. */
+    protected _hiddenColumns: readonly RunCoords[] | null;
+    /** Whether the owner is filtered ({@link ICalcGrid.setFiltered}). Versioned with the maps. */
+    protected _filtered: boolean;
+    /**
+     * @see CalcGridBackend.ConstructorOptions.unanchored
+     */
+    readonly _unanchored: boolean;
+    /** @see CalcGridBackend.ConstructorOptions.shadowOf */
+    readonly _shadowOf: string | null;
+    /** @see CalcGridBackend.ConstructorOptions.arrayFirstCell */
+    readonly _arrayFirstCell: boolean;
+    /** @see CalcGridBackend.ConstructorOptions.paged */
+    readonly _paged: boolean;
+    /** The tiles of a paged body's blank region its owner reads now: see {@link getDemanded}. */
+    protected _demanded: readonly IRange.Coords[];
+    _container: IContextContainer;
+    _context: IFormulaContext;
+    protected _isProcessingJSON: boolean;
+    /**
+     * Captures taken for {@link getSnapshot} by id: what a `copyTo` request reads. A capture is
+     * taken in channel order (a request of its own while the engine is `Starting`), so a cut's clear
+     * sent after the snapshot never reaches it first. Bounded: a clipboard holds one snapshot at a
+     * time, so the oldest are dropped past a few.
+     */
+    protected _snapshots: Map<string, CalcGridSnapshot> | null;
+    /**
+     * The owner's callback for a record the engine pushed - a pass's results, a seed's. The one
+     * place the response half of the boundary is crossed on the way out (plan step 6); every site
+     * that pushes calls this rather than `_options.onCalculated`.
+     */
+    protected _onCalculated: (response: CalcResponse) => void;
+    constructor(options?: CalcGridBackend.ConstructorOptions);
+    /**
+     * Runs a request against this grid under the engine commit it lands in: the per-grid maps are
+     * copied on write under that key first, so the snapshot before the request keeps what it had.
+     */
+    protected _land<R>(landingId: string | undefined, action: () => R): R;
+    /** Copy the per-grid maps on write under `key` (the same key hands back the same copies). */
+    protected _versionMaps(key: string): void;
+    /** Record the maps this grid holds now in the engine's history. */
+    protected _publishMaps(): void;
+    /** @internal A restore of the engine's history: hold what the snapshot holds for this grid. */
+    _adoptMaps(maps: CalcGridMaps): void;
+    /**
+     * Record that the formula blocks over these entries changed. An entry scoped to another grid is
+     * recorded on THAT grid: a shift or a delete here rewrites references in formulas over there,
+     * and that grid's sheet learns of it through its own results.
+     */
+    protected _touchFormulas(entries: readonly IRange.Coords[] | null | undefined): void;
+    /**
+     * The formula blocks over this grid's touched regions, as the read views the sheet holds, and
+     * the regions themselves as removes. Drains the touched list.
+     */
+    protected _takeFormulaResults(results: CalcResponse, all?: boolean): CalcResponse;
+    /** The vend shape of engine entries: scope-free coords and the block as data. */
+    protected _formulaRecords(entries: readonly ISpatialMap.Entry<FormulaSpatialValue>[]): ISpatialMap.Entry<FormulaRecord>[];
+    /**
+     * A mutator's resolution: what it minted and removed, over the regions it touched, answering
+     * for the snapshot the request named.
+     */
+    protected _mutationResults(commitId: string | undefined): CalcResponse;
+    /**
+     * @internal
+     * Applies a request to this grid, landing under `landingId`: what the channel calls, at once or
+     * once the engine is up.
+     *
+     * @param held `true` for a request the channel held: the savepoint it was made under has
+     * closed since, so its key would let the write update maps committed after it.
+     */
+    _apply(request: GridRequest, landingId: string | undefined, held?: boolean): CalcResponse | Promise<CalcResponse>;
+    /** A grid holding one body - a watch's, a name's, a held expression's - rather than a sheet's cells. @internal */
+    _holdsBody(): boolean;
+    /** This grid's touched formulas, pushed to its owner now: see {@link _apply}. @internal */
+    _pushTouched(commitId: string | undefined): void;
+    protected _applyNow(request: GridRequest, landingId: string | undefined, held: boolean): CalcResponse | Promise<CalcResponse>;
+    /** Takes a capture of this grid as it is now and files it under `snapshotId` for a later copy. */
+    protected _captureSnapshot(snapshotId: string): void;
+    /** @inheritdoc ICalcGrid.beginUpdates */
+    beginUpdates(): ICalcGrid.IncrementalUpdates;
+    /** {@inheritDoc ICalcGrid.IncrementalUpdates.notifyBlank} */
+    protected _addNotifyBlank(coords: IRange.Coords): void;
+    /** The engine's own ask for a pass from this grid. @internal */
+    _calculateNow(full?: boolean): Promise<ICalculation.Status>;
+    protected _shiftNow(options: ICalcGrid.ShiftOptions): CalcResponse;
+    /** The synchronous form of {@link remove}, for the engine's own use on a `Running` engine. */
+    protected _removeNow(range: IRange.Coords): IRange.Coords[];
+    protected _autoFillNow(template: IRange.Coords, destination: IRange.Coords, commitId: string | undefined): CalcResponse;
+    /**
+     * @internal
+     * Rewrites every formula citing a 3-D span whose endpoint the tab-order change from `before` to
+     * `after` removed, or `movedId` carried across the other endpoint, so the endpoint is its inward
+     * neighbor (PLAN-3D-REFS §1.3). The maps are published through the container, so the rewrite
+     * lands in whatever commit the sheet operation holds open and an undo restores it.
+     */
+    _replaceSheetSpans(before: readonly string[], after: readonly string[], movedId?: string): void;
+    protected _deleteNow(): void;
+    /**
+     * Takes the grid out of the graph and leaves every formula that read it exactly as written.
+     *
+     * @remarks
+     * The other half of {@link delete}: that one is the sheet-deletion contract and rewrites each
+     * dependent's reference to `#REF!`, which is right when the cells are gone for good. An external
+     * book's sheet is not — its removal keeps the citation on the slot's id so that an undo heals it
+     * — so here the precedent entries under this grid are dropped (a plan built through them would
+     * reach a grid that no longer exists) and the formulas that held them are dirtied by their own
+     * region, which is the only handle left once the entries are gone. Re-evaluated, each finds no
+     * grid to bind its scope to and computes `#REF!` on its own.
+     * @internal
+     */
+    _detach(): void;
+    /** The engine's own dirty marking over this grid's cells. @internal */
+    _markDirtyRegionsNow(coords: readonly IRange.Coords[]): void;
+    /**
+     * The rows or columns the owner hides, ascending and disjoint; `null` for none. Engine-side: not
+     * on {@link ICalcGrid}.
+     */
+    getHiddenRuns(axis: IRange.Axis): readonly RunCoords[] | null;
+    /**
+     * Whether the owner is filtered: some AutoFilter or table on it holds a condition
+     * ({@link ICalcGrid.setFiltered}). Engine-side: not on {@link ICalcGrid}.
+     */
+    isFiltered(): boolean;
+    /**
+     * A range's skip (`IRange.IteratorOptions.processRowSkip`) over the rows or columns the owner
+     * hides, for a range starting at `origin` on that axis; `null` when the hidden set does not
+     * cross `origin..end`.
+     *
+     * @remarks
+     * One per hidden set and origin, kept: the statistics cache their zones by the skip they were
+     * walked under, so a formula handed the same skip on every pass keeps them warm, and a set
+     * that changed is a new array and so a new skip. A skip keeps a cursor, which makes it cheap
+     * to ask in order and correct to ask out of it.
+     */
+    getHiddenSkip(axis: IRange.Axis, origin: number, end: number): ((index: number, reverse?: boolean) => number) | null;
+    /**
+     * What a `hidden` request carries, held; the formulas that can skip hidden cells are owed a pass.
+     *
+     * @remarks
+     * A row hidden changes no cell, so nothing in the graph reaches them. They are found by what
+     * they call ({@link FormulaSpatialValue.hasTotals}), on every grid: a total reads another
+     * sheet's rows too, and a fact of the compiled formula holds for one a load trusted and never
+     * evaluated.
+     */
+    protected _setHiddenNow(axis: IRange.Axis, runs: readonly RunCoords[]): void;
+    /** What a `filtered` request carries, held; as {@link _setHiddenNow}, the totals are owed a pass. */
+    protected _setFilteredNow(filtered: boolean): void;
+    /** Mark every formula that calls a total function, on every grid, and ask for a pass. */
+    protected _markTotals(): void;
+    /** @inheritdoc ICalcGrid.getId */
+    getShadowOf(): string | null;
+    /** @inheritdoc ICalcGrid.isArrayFirstCell */
+    isArrayFirstCell(): boolean;
+    /** Whether this grid's body may evaluate its blank region a tile at a time: see `ConstructorOptions.paged`. */
+    isPaged(): boolean;
+    /**
+     * The tiles of the body's blank region its owner reads now, in this grid's coordinates. A paged
+     * body evaluates its blank region only inside them; empty for a grid that is not paged.
+     */
+    getDemanded(): readonly IRange.Coords[];
+    /**
+     * Take the owner's tiles. A tile that is new or released is dirtied: the next pass evaluates a
+     * new one and clears what a released one holds.
+     */
+    protected _demandNow(rects: readonly IRange.Coords[]): void;
+    /** {@inheritDoc ICalcGrid.getEntireCoords} */
+    getEntireCoords(): IRange.Coords;
+    /**
+     * `true` when any cell within `coords` holds an error value.
+     *
+     * @remarks
+     * Answered from the error index the grid maintains at every write - inputs and calc commits
+     * alike (`applyContentful`) - so it never scans. It describes the COMMITTED values, exactly
+     * what {@link getValues} holds. Engine-side: not on {@link ICalcGrid}.
+     */
+    hasErrorIn(coords: IRange.Coords): boolean;
+    /** The bounding range of the content, values and formulas, or `null` when the grid has none. Engine-side. */
+    getBoundingRange(): IRange.Coords | null;
+    /** @inheritdoc ICalcGrid.getValues */
+    getValues(): ISparseGrid<Scalar>;
+    /** The regions marked dirty since the last pass. Engine-side. */
+    getDirtyRegions(): ISpatialQuery;
+    /**
+     * A queryable spatial index of the compiled blocks on this grid: the engine's live map.
+     *
+     * @remarks
+     * Engine-side, not on {@link ICalcGrid}: the model holds its own entries and reads the blocks
+     * the engine vends on {@link ICalcGrid.Results.formulaInserts}.
+     */
+    getFormulas(): ISpatialQuery<IFormulaBlock>;
+    /**
+     * A queryable spatial index of the ARRAY EXTENTS on this grid: one entry per array formula,
+     * keyed by the cells it occupies (a dynamic array's spill, a legacy CSE block, or the single
+     * cell a blocked spill collapses to).
+     *
+     * @remarks
+     * The same index a pass writes through {@link ICalcGrid.IncrementalUpdates.spillSpatial}
+     * (`beginUpdates` hands out this very map), so a read answers identically inside and outside a
+     * pass, which is what lets a formula evaluated OUTSIDE one resolve a spill anchor. Engine-side.
+     */
+    getSpills(): ISpatialQuery<SpillEntry>;
+    protected _revertNow(options: ICalcGrid.RevertOptions): CalcResponse;
+    /**
+     * The direct dependents of a range: one hop downstream. A range a formula resolved at run
+     * time (`INDIRECT`, `OFFSET`) is reported like any other, with the caveat under
+     * {@link getDirectPrecedentsAt}. Engine primitive; {@link ICalcGrid.getGraphNeighborsAt} is
+     * the model's question.
+     */
+    getDirectDependentsAt(coords: IRange.Coords): IRange.Coords[];
+    /**
+     * Pushes `dep` and the landed output of every spill anchored in it. An anchor rewrites its whole
+     * spill when it re-evaluates, and this is the hop that lets a transitive walk reach what reads the
+     * spill's far end, not just its anchor. A blocked spill landed on its anchor alone, so adds nothing.
+     */
+    private _pushWithSpills;
+    /**
+     * The direct precedents of a range: one hop upstream, as of the last calculation.
+     *
+     * @remarks
+     * A range a formula resolved at run time (`INDIRECT`, `OFFSET`) is reported like any other,
+     * but it is not the same KIND of fact: a written reference is a property of the text, true
+     * before anything calculates; a resolved one is a record of the last pass, moves when the
+     * formula's inputs move, and is absent for a block not yet calculated. The bounds are the
+     * union of everything the block read, wider than the cells touched for a scattered read:
+     * over-reporting costs a caller a clean check, under-reporting hands it an incomplete answer
+     * that looks complete. Engine primitive; {@link ICalcGrid.getGraphNeighborsAt} is the
+     * model's question.
+     */
+    getDirectPrecedentsAt(coords: IRange.Coords): IRange.Coords[];
+    /**
+     * One hop of a transitive walk, taken on whichever GRID the coord names.
+     *
+     * @remarks
+     * `getDirect*At` are grid-local by construction — they search their own grid and answer with
+     * `scope` set only where a neighbor is elsewhere. A walk therefore cannot keep asking `this`:
+     * once it steps onto `Sheet2!C3` the next hop belongs to Sheet2, and asking Sheet1 for `C3`
+     * reads a different cell entirely. Results come back bare-relative to the grid that produced
+     * them, so they are re-expressed against the walk's own anchor before being handed back.
+     * @internal
+     */
+    private _directAcrossGrids;
+    /** Every range downstream of `coords`, recursively: the total impact of a change there. Engine primitive. */
+    getDependentsAt(coords: IRange.Coords): IRange.Coords[];
+    /** Every range upstream of `coords`, recursively: all of its root data sources. Engine primitive. */
+    getPrecedentsAt(coords: IRange.Coords): IRange.Coords[];
+    /** What a `graph` request answers for cells: see {@link ICalcGrid.getGraphNeighborsAt}. */
+    protected _graphNeighborsNow(coords: IRange.Coords, kind: 'precedents' | 'dependents', direct: boolean): ICalcGrid.GraphNeighbors;
+    /**
+     * The distinct stable nameIds of the named formulas mentioned by the formulas over `coords`.
+     *
+     * @remarks
+     * The NAME half of {@link getReferencesAt}: both report what the TEXT mentions, so
+     * neither walks the graph. It is nonetheless what answers the name half of PRECEDENTS: a name
+     * is applied at eval, so the cell graph carries no edge for it (`=Doubled` has NO cell
+     * precedents) and the written mention is the whole answer. Only the queried blocks are
+     * inspected; a name mentioned upstream is that cell's precedent. Engine primitive.
+     */
+    getNamedReferencesAt(coords: IRange.Coords): string[];
+    /**
+     * What a `graph` request asking about this grid's defined name answers: the name's precedents
+     * or dependents, cells scoped by grid and names as nodes - ONE answer, as a cell's is.
+     *
+     * @remarks
+     * The PRECEDENTS: the cell half is the ordinary precedent graph - a body is a real formula here,
+     * and its references registered precedent ranges like any cell's. The name half is the body's
+     * `getNamedIds`: apply-at-eval means a name the body reads has no precedent edge, so the symbol
+     * list is the only carrier - one hop for `direct`, the downward closure (cycle-guarded) for the
+     * deep form, each member contributing its own grid's cell walk. The deep form does not take the
+     * symbol hop from UPSTREAM CELLS (`X = A1*2`, `A1 = SomeName`: `A1` is listed and `SomeName`'s
+     * inputs are not) - that hop is `A1`'s, one step of a tree walk.
+     *
+     * The DEPENDENTS: two graphs meet, and the walk changes vehicles between them. The symbol edge -
+     * which formulas mention this name - is not in the precedent spatial at all; it is the nameId
+     * list each compiled block carries (`container.getNamedDependents`). The cell edge is the
+     * precedent graph, which carries everything downstream of those blocks: `direct` is one hop of
+     * the first; the deep form takes it, then hands each landing block to its grid. A block on a
+     * grid that is no sheet is another NAME reading this one: a node, and the deep walk passes
+     * THROUGH it on the symbol closure (`getNamedDependentNames`), or `Base`'s dependents would stop
+     * at `Plus1`. This name is listed only when a true cycle leads back to it.
+     */
+    protected _nameGraphNow(kind: 'precedents' | 'dependents', direct: boolean): ICalcGrid.GraphNeighbors;
+    /** The blank region of the body this grid holds, as data: see {@link ICalcGrid.Results.blankRegion}. */
+    protected _blankRegion(): ICalcGrid.BlankRegion | null;
+    /** The compiled block at a cell, or `null`. Engine-side: the model reads the vended view. */
+    getFormulaBlockAt(row: number, column: number): IFormulaBlock | null;
+    /** The written references of the formula at a cell, absolute (`IFormulaBlockView.getReferencesAt`). Engine primitive. */
+    getReferencesAt(row: number, column: number): ReferenceCoords[];
+    /** What an `evaluate` request answers: the formula at the cell, evaluated now; `null` where there is none. */
+    protected _evaluateNow(row: number, column: number, evalIndex?: number, coerce?: 'scalar'): Scalar | IRange | Promise<Scalar | IRange> | null;
+    /** What a `setReference` request does: the rewrite, and the write of the formula it makes. */
+    protected _setReferenceNow(row: number, column: number, index: number, precedent: IRange.FixableCoords | IRange.FixableCellCoords | NamedReference | FormulaError.Ref): CalcResponse;
+    /** What a `setReferenceMode` request does: refused for a reference that is not to cells. */
+    protected _setReferenceModeNow(row: number, column: number, index: number, side: ICalculation.ReferenceSide, mode?: number): CalcResponse;
+    /** What an `isVolatile` request answers. */
+    protected _isVolatileNow(row: number, column: number): boolean;
+    protected _formulaAt(row: number, column: number): ISpatialMap.Entry<FormulaSpatialValue> | null;
+    /**
+     * Create non error spill entries for move/copy.
+     */
+    protected _createCopySpillEntries(spillSpatial: ISpatialMap<SpillEntry>, from: IRange.Coords, to: IRange.Coords, reuseInserts?: ISpatialMap.Entry<SpillEntry>[] | null, reuseRemoves?: ISpatialMap.Entry<SpillEntry>[] | null): ISpatialMap.Updates;
+    /**
+     * Because the formula we are copying from maybe have been compiled using
+     * a different calculation context we have to serialize back to the formula string.
+     *
+     * @param gridExplicitId The grid context to compile in AND the scope prefix added to unqualified refs.
+     *   For formula-move: the source grid (refs get source-grid prefix). For precedent-move: the
+     *   destination grid (refs get destination-grid prefix).
+     * @param targetScope If provided, the formula entry scope after re-anchoring. Defaults to this._gridId.
+     *   Use from.scope when re-anchoring formulas that stay in the source sheet.
+     *
+     * @remarks
+     * This modifies the insert in place.
+     */
+    protected _reanchorFormulas(inserts: ISpatialMap.Entry<FormulaSpatialValue>[], gridExplicitId?: string | null, targetScope?: string | null, force?: boolean): void;
+    /**
+     * Will copy tiles and invalidate relative precedents that are out
+     * of bounds.
+     */
+    protected _copyTo(snapshot: CalcGridSnapshot, from: IRange.Coords, to: IRange.Coords): void;
+    /**
+     * Will update absolute precedents from precedentEntries relative precedents get shifted
+     */
+    protected _moveTo(snapshot: CalcGridSnapshot, from: IRange.Coords, to: IRange.Coords): void;
+    protected _notifyCalculated(cycleId: number, options: ICalculation.CalculateOptions | boolean): Promise<CalcResponse>;
+    /**
+     * The write itself, on a `Running` engine. Records what it minted and removed for the vend rather
+     * than taking it, so the engine's own callers (a reference edit, `recompileNamed`) leave the
+     * vend for the pass that follows.
+     */
+    _setInputsNow(values: Tuple.Region<Scalar> | null, formulas: readonly ISpatialMap.Entry<string>[] | null, deleteRange?: IRange.Coords, options?: ICalcGrid.SetInputsOptions): IRange.Coords[];
+    /**
+     * Joins each block just written with an equal block beside it, so a formula written under a run
+     * of it, or between two runs, extends the run rather than starting a block of its own.
+     *
+     * @param reevaluate Called with a joined block that has to be evaluated whole: see remarks.
+     * @returns The joined blocks, or `null` when none joined.
+     *
+     * @remarks
+     * Two blocks are the same formula when their relative forms match; only an array-entered
+     * (fixed) extent is never joined. The sheet joins its entries on the same rule when they are
+     * written, so the two agree without waiting for the vend.
+     *
+     * The joined block clones its sources' nodes, so the cells already there keep what they
+     * calculated; only the cells written are marked dirty, by the caller, from the blocks as written.
+     * Two things a source holds do not survive that: its dynamic precedents (kept per block, and
+     * replaced wholesale by whatever the block's evaluated cells read next) and a result still
+     * pending (the promise resolves onto the source's node). A join that drops either evicts the
+     * source's dynamic precedents and hands the joined block to `reevaluate`, so every cell of it
+     * reads again.
+     */
+    protected _joinInserted(formulaSpatial: ISpatialMap3D<FormulaSpatialValue>, precedentSpatial: ISpatialMap3D<PrecedentSpatialValue>, inserts: readonly ISpatialMap.Entry<FormulaSpatialValue>[], reevaluate: (joined: IRange.Coords) => void): ISpatialMap.Entry<FormulaSpatialValue>[] | null;
+    /**
+     * Used before loading a new state
+     */
+    protected _clearAll(): void;
+    /**
+     * Removes every formula this grid holds and what hangs off them: their precedents wherever those
+     * live (a cross-sheet precedent is indexed under the grid it reads), their dynamic precedents,
+     * and their volatile nodes.
+     *
+     * @remarks
+     * The other half of {@link _clearAll}, which owns only what is the grid's alone. Formulas and
+     * precedents belong to the container, so a load over a grid that already has content would
+     * otherwise register a second block on the same cells.
+     */
+    protected _clearFormulas(): void;
+    /**
+     * @internal
+     * Opens the grid from `json` now, whatever the engine's status: the engine's own content (an
+     * external book's cached values) is loaded this way; a model's goes through {@link seed}.
+     */
+    _seedNow(json: ICalcGrid.JSON, options?: ICalcGrid.SeedOptions): CalcResponse;
+    /** What a `toJSON` request answers: the grid's content as the engine holds it now. */
+    protected _toJSONNow(options?: ICalcGrid.ToJSONOptions): ICalcGrid.JSON | null;
+}
+export declare namespace CalcGridBackend {
+    /**
+     * Options available when creating a CalcGridBackend.
+     */
+    interface ConstructorOptions {
+        /**
+         * The calculation instance that will be used to calculate the grid.
+         *
+         * @remarks
+         * Required as this will contain the context
+         */
+        context: IFormulaContext;
+        /**
+         * handler for calculation callbacks.
+         *
+         * @remarks
+         * The container contains information shared across all grids
+         */
+        container: IContextContainer;
+        /**
+         * For status listening
+         */
+        calculation: ICalculation | null;
+        /**
+         * A callback that is called when the calculation is completed.
+         *
+         * @remarks
+         * This will persist through clones.
+         */
+        onCalculated?: (results: ICalcGrid.Results) => void;
+        /**
+         * A unique id that never changes for the grid.
+         */
+        uuid?: string;
+        /**
+         * Returns the entire coordinate bounds for this grid.
+         * If not provided, defaults to the maximum sheet dimensions.
+         */
+        getEntireCoords?: () => IRange.Coords;
+        /**
+         * `true` for a grid whose coordinates are a synthetic anchor rather than positions in a real
+         * sheet — a named formula's compilation host, or the editor's temporary formula.
+         *
+         * @remarks
+         * Stamped onto every {@link FormulaSpatialValue} this grid creates; see
+         * `FormulaSpatialValue.unanchored` for what it buys. Defaults to `false` (a sheet).
+         */
+        unanchored?: boolean;
+        /**
+         * The sheet grid this grid is the coordinate space of. See {@link ICalcGrid.getShadowOf}.
+         */
+        shadowOf?: string;
+        /**
+         * `true` when every cell of every block in this grid is its own 1x1 array-entered extent — a
+         * conditional-format body. See {@link ICalcGrid.isArrayFirstCell}.
+         */
+        arrayFirstCell?: boolean;
+        /**
+         * `true` when the body's blank region may be evaluated a tile at a time: once the body's
+         * answer there depends on the position (`ISODD(ROW())`), only the tiles its owner asks for
+         * ({@link CalcGridBackend.getDemanded}) are evaluated, and the rest of the region holds
+         * nothing. For an owner that reads a window of the body at a time - a conditional format,
+         * which paints what is on screen.
+         */
+        paged?: boolean;
+    }
+}
+/** A grid's per-grid maps, as one snapshot of the engine's history holds them. */
+export interface CalcGridMaps {
+    values: ISparseGrid<Scalar>;
+    contentful: ISpatialMap<ContentfulSpatialValue>;
+    spills: ISpatialMap<SpillEntry>;
+    errors: ISpatialMap<string>;
+    pending: ISpatialMap<boolean>;
+    circular: ISpatialMap<CircularEntry>;
+    /** The size a `resize` gave, or `null` for the one the grid was made with. */
+    entireCoords?: IRange.Coords | null;
+    /** The rows the owner hides, or `null` for none. */
+    hiddenRows?: readonly RunCoords[] | null;
+    /** The columns the owner hides, or `null` for none. */
+    hiddenColumns?: readonly RunCoords[] | null;
+    /** Whether the owner is filtered. */
+    filtered?: boolean;
+}
+interface CalcGridSnapshot {
+    calcGrid: CalcGridBackend;
+    /** The source's values as marked; a cut clears the live ones before the move reads. */
+    values: ISparseGrid<Scalar>;
+    /** The source's spills as marked. */
+    spillSpatial: ISpatialMap<SpillEntry>;
+    formulaSpatial: ISpatialMap3D<FormulaSpatialValue>;
+    precedentSpatial: ISpatialMap3D<PrecedentSpatialValue>;
+    volatile: Set<CalcNode> | null;
+}
+export declare function valueCompareValues<T>(a: ISpatialMap.Entry<T>, removing: ISpatialMap.Entry<T>): boolean;
+export {};
+//# sourceMappingURL=CalcGridBackend.d.ts.map

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

@@ -0,0 +1,135 @@
+import { IRange, FormulaError, Scalar } from '@sheetxl/primitives';
+import { RunCoords } from '@sheetxl/utils';
+import { IListener } from '../../listener';
+import { ListenerEmitter } from '../../listener/ListenerEmitter';
+import { ISpatialMap, Tuple } from '../../collections';
+import { IFormulaBlockView } from '../formula';
+import { NamedReference } from '../Types';
+import { ICalculation } from '../ICalculation';
+import { ICalcGrid } from './ICalcGrid';
+import { CalcRequest } from './_CalcRequest';
+/**
+ * A grid's verbs as requests (DESIGN-CALC-SERVICE §4, §13.23): each one a message through the
+ * service's channel, addressed by the grid's id. What the model's grid forwards to - it never
+ * holds the engine's grid, which an `Off` engine does not have.
+ *
+ * @remarks
+ * The engine's own grid answers the same verbs through the same channel, so its engine-side
+ * tests can drive it directly; it adds what only the engine holds.
+ */
+export declare class CalcGridProxy implements ICalcGrid.Backend {
+    protected readonly _gridId: string;
+    protected readonly _sendRequest: CalcGridProxy.ConstructorOptions['send'];
+    _calculation: ICalculation | null;
+    protected _emitter: ListenerEmitter<ICalcGrid, ICalcGrid.IListeners> | null;
+    constructor(options: CalcGridProxy.ConstructorOptions);
+    /**
+     * The engine commit a request lands in: the nested savepoint it was made under, or the
+     * root's own commit (`<id>:0`, so the model's commit id itself is free for the mirror the
+     * engine lands at the root's close). `undefined` for a request naming no snapshot.
+     */
+    protected _landingId(options: ICalcGrid.RequestOptions | undefined): string | undefined;
+    /**
+     * Sends a request through the service's channel (DESIGN-CALC-SERVICE §4): applied now on a
+     * `Running` engine, held in order while it is `Starting`, not recorded on an `Off` one.
+     */
+    protected _send(landingId: string | undefined, request: CalcRequest): Promise<ICalcGrid.Results>;
+    /** @inheritdoc ICalcGrid.getId */
+    getId(): string;
+    /** {@inheritDoc ICalcGrid.resize} */
+    resize(c: IRange.Coords, options?: ICalcGrid.RequestOptions): void;
+    /** {@inheritDoc ICalcGrid.setHidden} */
+    setHidden(axis: IRange.Axis, runs: readonly RunCoords[], options?: ICalcGrid.RequestOptions): void;
+    /** {@inheritDoc ICalcGrid.setFiltered} */
+    setFiltered(filtered: boolean, options?: ICalcGrid.RequestOptions): void;
+    /** {@inheritDoc ICalcGrid.addListeners} */
+    addListeners(listeners: ICalcGrid.IListeners, options?: IListener.Options): IListener.Remove;
+    /** @inheritdoc ICalcGrid.setInputs */
+    setInputs(values: Tuple.Region<Scalar> | null, formulas: readonly ISpatialMap.Entry<string>[] | null, options?: ICalcGrid.SetInputsOptions): Promise<ICalcGrid.Results>;
+    /** {@inheritDoc ICalcGrid.remove} */
+    remove(range: IRange.Coords, options?: ICalcGrid.RequestOptions): Promise<ICalcGrid.Results>;
+    /**
+     * The write, held when the engine is not `Running` - a `Starting` engine still draining its
+     * load, a cold one whose start nobody has asked for yet - and applied at once otherwise. Either
+     * way it resolves with what it minted; the model holds the text meanwhile.
+     */
+    protected _setInputs(values: Tuple.Region<Scalar> | null, formulas: readonly ISpatialMap.Entry<string>[] | null, deleteRange?: IRange.Coords, options?: ICalcGrid.SetInputsOptions): Promise<ICalcGrid.Results>;
+    /** @inheritdoc ICalcGrid.shift */
+    shift(options: ICalcGrid.ShiftOptions): Promise<ICalcGrid.Results>;
+    /** {@inheritDoc ICalcGrid.autoFill} */
+    autoFill(template: IRange.Coords | string, destination: IRange.Coords | string, options?: ICalcGrid.RequestOptions): Promise<ICalcGrid.Results>;
+    /**
+     * {@inheritDoc ICalcGrid.calculate}
+     *
+     * @remarks
+     * A request through the channel, answered once the pass it asks for has been started.
+     */
+    calculate(full?: boolean): Promise<ICalculation.Status>;
+    /** {@inheritDoc ICalcGrid.Backend.requestPass} */
+    requestPass(): void;
+    /** {@inheritDoc ICalcGrid.Backend.demand} */
+    demand(rects: readonly IRange.Coords[]): void;
+    /** {@inheritDoc ICalcGrid.markDirtyRegions} */
+    markDirtyRegions(coords: IRange.Coords[]): void;
+    /** {@inheritDoc ICalcGrid.delete} */
+    delete(options?: ICalcGrid.RequestOptions): void;
+    /** {@inheritDoc ICalcGrid.revert} */
+    revert(options: ICalcGrid.RevertOptions): Promise<ICalcGrid.Results>;
+    /** {@inheritDoc ICalcGrid.close} */
+    close(): void;
+    /** {@inheritDoc ICalcGrid.seed} */
+    seed(json: ICalcGrid.JSON, options?: ICalcGrid.SeedOptions): Promise<ICalcGrid.Results>;
+    /**
+     * {@inheritDoc ICalcGrid.toJSON}
+     *
+     * @remarks
+     * A request: answered in order behind every write sent before it, so a `Starting` engine answers
+     * once the writes held ahead of it have landed.
+     */
+    toJSON(options?: ICalcGrid.ToJSONOptions): Promise<ICalcGrid.JSON | null>;
+    /** {@inheritDoc ICalcGrid.getSnapshot} */
+    getSnapshot(options?: ICalcGrid.GetSnapshotOptions): ICalcGrid.ISnapshot;
+    /**
+     * {@inheritDoc ICalcGrid.getGraphNeighborsAt}
+     *
+     * @remarks
+     * A question: an engine that holds no grid (`Off`) answers with nothing.
+     */
+    getGraphNeighborsAt(coords: IRange.Coords, kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
+    /** {@inheritDoc ICalcGrid.Backend.getNameGraph} */
+    getNameGraph(kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
+    /**
+     * {@inheritDoc ICalcGrid.isVolatileAt}
+     *
+     * @remarks
+     * A question: an engine that holds no grid (`Off`) answers `false`.
+     */
+    isVolatileAt(row: number, column: number): Promise<boolean>;
+    /** {@inheritDoc ICalcGrid.evaluateAt} */
+    evaluateAt(row: number, column: number, options?: number | ICalculation.EvaluateOptions): Promise<Scalar | IRange>;
+    /** {@inheritDoc ICalcGrid.Backend.evaluateScalarAt} */
+    evaluateScalarAt(row: number, column: number, evalIndex?: number): Promise<Scalar>;
+    /** {@inheritDoc ICalcGrid.Backend.setBody} */
+    setBody(options: ICalcGrid.BodyOptions): Promise<ICalcGrid.Results>;
+    /**
+     * {@inheritDoc ICalcGrid.setReferenceAt}
+     *
+     * @remarks
+     * A request through the channel: the edit is made against the compiled formula, in order with
+     * the writes before it, and a refusal rejects.
+     */
+    setReferenceAt(row: number, column: number, index: number, precedent: IRange.FixableCoords | IRange.FixableCellCoords | NamedReference | FormulaError.Ref): Promise<IFormulaBlockView | null>;
+    /** {@inheritDoc ICalcGrid.setReferenceModeAt} */
+    setReferenceModeAt(row: number, column: number, index: number, side?: ICalculation.ReferenceSide, mode?: number): Promise<IFormulaBlockView | null>;
+}
+export declare namespace CalcGridProxy {
+    interface ConstructorOptions {
+        /** The grid's id: what every request is addressed to. */
+        id: string;
+        /** The service's channel (`Calculation._sendRequest`). */
+        send: (gridId: string, landingId: string | undefined, request: CalcRequest) => Promise<ICalcGrid.Results>;
+        /** For the engine's status, and `ready()` ahead of an evaluation. */
+        calculation?: ICalculation | null;
+    }
+}
+//# sourceMappingURL=CalcGridProxy.d.ts.map