@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.2

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

@@ -1,209 +1,435 @@
-import { IRange, FormulaError, Scalar, IFormulaContext } from '@sheetxl/primitives';
+import { IRange, Scalar, IRuntime, FormulaError } from '@sheetxl/primitives';
+import { CoordUtils } from '@sheetxl/utils';
+import { ITypes } from '../../type';
 import { IListener } from '../../listener';
 import { ListenerEmitter } from '../../listener/ListenerEmitter';
-import { Tuple, ISpatialQuery, ISparseGrid, ISpatialMap, ISpatialMap3D } from '../../collections';
-import { IContextContainer, CalcNode } from '../state';
-import { SpillEntry, FormulaSpatialValue, ContentfulSpatialValue, PrecedentSpatialValue, CircularEntry } from '../spatial';
-import { IFormulaBlock } from '../formula';
-import { ReferenceCoords } from '../Types';
+import { ITransaction } from '../../transaction';
+import { ISpatialMap, ISpatialQuery, ISparseGrid, Tuple } from '../../collections';
+import { RangeStats } from '../../primitives/RangeStats';
 import { ICalculation } from '../ICalculation';
+import { IFormulaBlockView } from '../formula';
+import { NamedReference } from '../Types';
+import { ContentfulSpatialValue, SpillEntry, CircularEntry } from '../spatial';
 import { ICalcGrid } from './ICalcGrid';
+import { FormulaEntry } from './FormulaEntry';
 /**
- * ICalcGrid implementation
+ * The grid as the model holds it (DESIGN-CALC-SERVICE §13.23, §13.24): the synchronous half of
+ * every implementation, in front of a backend that answers late or not at all.
+ *
+ * @remarks
+ * Owns what a cell holds - the formulas as the model wrote them, text per run; the values, both
+ * the literals it entered and the answers the engine vended; and the indexes over them (the
+ * contentful summary, the array extents, the error values, the calc status) - versioned in the
+ * model's own transaction store, so an undo restores them with everything else the operation
+ * wrote. Each formula entry carries the view of the compiled block the backend vends for it.
+ * Every write lands here first, in the caller's transaction, and is then forwarded to the backend
+ * as the same verb; what the backend answers with is folded into the snapshot the request named
+ * and every later one, where what the request was made against is still there, and dropped where
+ * something newer wrote ({@link _adopt}, {@link _applyValueVend}). So an undo lands on maps that
+ * already carry the engine's answer for them, with no round trip.
+ *
+ * The backend is an {@link ICalcGrid.Backend}: the in-process engine grid, a message-passing
+ * proxy under a worker, and nothing at all is what an `Off` engine amounts to (the channel
+ * records nothing, so the text here is the whole truth until a start seeds the engine from it).
+ * The same code in every case; only the delegate differs.
  */
 export declare class CalcGrid implements ICalcGrid {
+    protected readonly _backend: ICalcGrid.Backend;
+    protected readonly _calculation: ICalculation | null;
+    protected readonly _transactions: ITransaction.IStore;
+    protected readonly _stateId: string;
+    protected readonly _host: CalcGrid.HostOptions;
+    protected readonly _valuesAxis: IRange.Axis;
+    protected readonly _runtime: IRuntime;
+    /** The aggregate cache over the values; bound to the map INSTANCE, so it follows every clone. */
+    protected _rangeStats: RangeStats;
     /**
-     * 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;
-    _notifySpillsInsert: ISpatialMap.Entry<SpillEntry>[];
-    _notifySpillsRemove: IRange.Coords[];
-    _notifyFormats: ISpatialMap;
-    _notifyPending: ISpatialMap<boolean>;
-    _notifyCircular: ISpatialMap<CircularEntry | false>;
-    _cloneKey?: CalcGrid;
-    _version: number;
-    _iterationId: number;
-    _gridId: string;
-    _options: CalcGrid.ConstructorOptions;
-    _getEntireCoords: () => IRange.Coords;
-    /**
-     * @see CalcGrid.ConstructorOptions.unanchored
-     */
-    readonly _unanchored: boolean;
-    _container: IContextContainer;
-    _context: IFormulaContext;
-    _calculation: ICalculation | null;
+     * Bumped whenever the value map is mutated IN PLACE (a vend that landed on this grid's own
+     * instance, a load): what {@link getErrorValues} invalidates its cached view by, since the
+     * map's identity does not change then.
+     */
+    protected _errorEpoch: number;
+    /** The reconciled error-VALUE view; see {@link getErrorValues}. */
+    protected _errorReconciled: {
+        values: ISparseGrid<Scalar>;
+        epoch: number;
+        spatial: ISpatialMap<boolean>;
+    } | null;
+    /** Savepoints a write was made under that rolled back since: their answers are dropped. */
+    protected _deadSavepoints: Set<string> | null;
+    /**
+     * Its own store, never open, so every event is delivered as it happens: what an
+     * `onInputsWritten` listener writes has to join the operation still open, and every answer is
+     * told, not merged into the first.
+     */
     protected _emitter: ListenerEmitter<ICalcGrid, ICalcGrid.IListeners> | null;
-    protected _isProcessingJSON: boolean;
-    protected _onCalculated: (results: ICalcGrid.Results) => void;
-    constructor(options?: CalcGrid.ConstructorOptions);
-    /** @inheritdoc ICalcGrid.beginUpdates */
-    beginUpdates(): ICalcGrid.IncrementalUpdates;
-    /** {@inheritDoc ICalcGrid.calculate} */
-    calculate(full?: boolean): Promise<ICalculation.Status>;
-    /** {@inheritDoc ICalcGrid.addListeners} */
-    addListeners(listeners: ICalcGrid.IListeners, options?: IListener.Options): IListener.Remove;
-    /** @inheritdoc ICalcGrid.clone */
-    shift(options: ICalcGrid.ShiftOptions): this;
-    /** @inheritdoc ICalcGrid.clone */
-    clone(cloneKey?: any): this;
-    /** @inheritdoc ICalcGrid.setInputs */
-    setInputs(values: Tuple.BoundedTuples<Scalar> | null, formulas: readonly ISpatialMap.Entry<string>[] | null): IRange.Coords[];
-    /** {@inheritDoc ICalcGrid.remove} */
-    remove(range: IRange.Coords): IRange.Coords[];
-    /** {@inheritDoc ICalcGrid.autoFill} */
-    autoFill(template: IRange.Coords | string, destination: IRange.Coords | string): this;
-    /** {@inheritDoc ICalcGrid.getEntireCoords} */
-    delete(): void;
-    /** {@inheritDoc ICalcGrid.markDirtyRegion} */
-    markDirtyRegions(coords: IRange.Coords[]): void;
-    /** @inheritdoc ICalcGrid.getId */
-    getId(): string;
-    /** {@inheritDoc ICalcGrid.getEntireCoords} */
-    getEntireCoords(): IRange.Coords;
-    /** {@inheritDoc ICalcGrid.getBoundingRange} */
-    getBoundingRange(): IRange.Coords | null;
-    /** @inheritdoc ICalcGrid.getValues */
-    getValues(): ISparseGrid<Scalar>;
-    /** {@inheritDoc ICalcGrid.getDirtyRegions} */
-    getDirtyRegions(): ISpatialQuery;
+    protected _closed: boolean;
+    constructor(options: CalcGrid.ConstructorOptions);
+    /**
+     * Open this grid's maps from a content record, replacing what they hold: the formulas, the
+     * values, their contentful summary, the error ones among them, the array extents the record
+     * carries and the volatile regions it lists. The same record the backend is opened from.
+     */
+    protected _loadContent(json: ICalcGrid.JSON, write: CalcGrid.Writer): void;
+    /** The backend this grid forwards to. @internal */
+    _getBackend(): ICalcGrid.Backend;
+    /** {@inheritDoc ICalcGrid.getStateId} */
+    getStateId(): string;
+    /**
+     * This grid's record: the current one, or the one `transaction` sees.
+     *
+     * @remarks
+     * A read through the store makes the writes a cell buffer holds first ({@link getStateId} is
+     * in its list), which is what keeps a reader from seeing the sheet without them. The paths that
+     * answer a cell FROM those held writes must not make them, so they read through the buffer's
+     * own transaction.
+     */
+    protected _getState(transaction?: ITransaction | null): Readonly<CalcGrid.State>;
+    /**
+     * This grid's record as it was at a commit; the current one for the operation in progress;
+     * `undefined` for a commit the store no longer has on its live history.
+     */
+    protected _getStateAt(commitId: string): Readonly<CalcGrid.State> | undefined;
+    /** {@inheritDoc ICalcGrid.getFormulaAt} */
+    getFormulaAt(row: number, column: number): FormulaEntry | null;
     /** {@inheritDoc ICalcGrid.getFormulas} */
-    getFormulas(): ISpatialQuery<IFormulaBlock>;
+    getFormulas(transaction?: ITransaction | null): ISpatialQuery<FormulaEntry>;
+    /** {@inheritDoc ICalcGrid.getValues} */
+    getValues(transaction?: ITransaction | null): ISparseGrid<Scalar>;
+    /** {@inheritDoc ICalcGrid.getContentful} */
+    getContentful(transaction?: ITransaction | null): ISpatialMap<ContentfulSpatialValue>;
     /** {@inheritDoc ICalcGrid.getSpills} */
-    getSpills(): ISpatialQuery<SpillEntry>;
-    /** {@inheritDoc ICalcGrid.getSnapshot} */
-    getSnapshot(options?: ICalcGrid.GetSnapshotOptions): ICalcGrid.ISnapshot;
-    /** {@inheritDoc ICalcGrid.getDirectDependentsAt} */
-    getDirectDependentsAt(coords: IRange.Coords): IRange.Coords[];
-    /** {@inheritDoc ICalcGrid.getDirectPrecedentsAt} */
-    getDirectPrecedentsAt(coords: IRange.Coords): IRange.Coords[];
+    getSpills(transaction?: ITransaction | null): ISpatialMap<SpillEntry>;
+    /** {@inheritDoc ICalcGrid.getPending} */
+    getPending(transaction?: ITransaction | null): ISpatialMap<boolean>;
+    /** {@inheritDoc ICalcGrid.getCalcErrors} */
+    getCalcErrors(transaction?: ITransaction | null): ISpatialMap<string>;
+    /** {@inheritDoc ICalcGrid.getCirculars} */
+    getCirculars(transaction?: ITransaction | null): ISpatialMap<CircularEntry>;
+    /** {@inheritDoc ICalcGrid.getVolatileRegions} */
+    getVolatileRegions(): IRange.Address[] | null;
+    /** {@inheritDoc ICalcGrid.getRangeStats} */
+    getRangeStats(): RangeStats;
+    /** {@inheritDoc ICalcGrid.getErrorValues} */
+    getErrorValues(): ISpatialMap<boolean>;
     /**
-     * One hop of a transitive walk, taken on whichever GRID the coord names.
+     * A write to this grid's own maps, in the caller's transaction: each map the write asks for is
+     * cloned once, and a map the open savepoint has already cloned is handed back and updated in
+     * place. Nothing asked for is nothing copied.
      *
      * @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.
+     * The model's own mutation paths take the writer directly ({@link _beginWrite}): a literal
+     * entry, a clear or a shift writes the values beside what it writes of its own, in one
+     * transaction, and cannot be expressed as one call.
      * @internal
      */
-    private _directAcrossGrids;
-    /** {@inheritDoc ICalcGrid.getDependentsAt} */
-    getDependentsAt(coords: IRange.Coords): IRange.Coords[];
-    /** {@inheritDoc ICalcGrid.getPrecedentsAt} */
-    getPrecedentsAt(coords: IRange.Coords): IRange.Coords[];
-    /** {@inheritDoc ICalcGrid.getFormulaBlockAt} */
-    getFormulaBlockAt(row: number, column: number): IFormulaBlock | null;
-    /** {@inheritDoc ICalcGrid.getReferencesAt} */
-    getReferencesAt(row: number, column: number): ReferenceCoords[];
+    _beginWrite(options?: ICalcGrid.RequestOptions, isInput?: boolean): CalcGrid.Writer;
+    /** One write, begun and committed: what the verbs use. */
+    protected _write(mutate: (write: CalcGrid.Writer) => void, options?: ICalcGrid.RequestOptions, isInput?: boolean): void;
+    /** A bookkeeping write: folded into the commit the store is at, or the operation in progress. */
+    protected _amend(update: Partial<CalcGrid.State>): void;
+    /** {@inheritDoc ICalcGrid.setInputs} */
+    setInputs(values: Tuple.Region<Scalar> | null, formulas: readonly ISpatialMap.Entry<string>[] | null, options?: ICalcGrid.SetInputsOptions): Promise<ICalcGrid.Results>;
+    /**
+     * What a write of inputs changes beside the formulas: the values, which cells hold one, the
+     * array extents the write replaces or enters, and the error and cycle indexes over the cells.
+     */
+    protected _writeInputValues(write: CalcGrid.Writer, tuples: Tuple.GridTuple<Scalar> | undefined, formulas: readonly ISpatialMap.Entry<string>[] | null, arrayFixed: IRange.Coords | undefined): void;
+    /**
+     * What emptying cells changes beside the formulas: the values go, and with them their
+     * contentful summary, the error and cycle indexes over them, and the extent of an array
+     * anchored among them.
+     */
+    protected _removeInputValues(write: CalcGrid.Writer, coords: IRange.Coords): void;
+    /** {@inheritDoc ICalcGrid.remove} */
+    remove(coords: IRange.Coords, options?: ICalcGrid.RemoveOptions): Promise<ICalcGrid.Results>;
+    /**
+     * What a shift moves beside the formulas: the values and their contentful summary, the array
+     * extents - a fixed array the range touches is set aside and put back where the shift takes it -
+     * and the error values. An insert refuses to push content off the grid.
+     */
+    protected _shiftInputValues(write: CalcGrid.Writer, range: IRange.Coords, direction: IRange.Direction): void;
+    /** What an insert checks every extent it moves against: the grid's own bounds. */
+    protected _insertValidator(): CoordUtils.CoordValidator;
+    /** {@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.getSnapshot} */
+    getSnapshot(options?: ICalcGrid.GetSnapshotOptions): ICalcGrid.ISnapshot;
+    /**
+     * Copy the entries over `from` in `snapshot` into this grid's map at `to`, in the current
+     * transaction, and return them as the text the backend is handed.
+     * @internal
+     */
+    _copyFormulaEntries(snapshot: ISpatialMap<FormulaEntry>, from: IRange.Coords, to: IRange.Coords, copyOptions: FormulaEntry.CopyOptions, options?: ICalcGrid.RequestOptions): ISpatialMap.Entry<string>[];
+    /** {@inheritDoc ICalcGrid.seed} */
+    seed(json: ICalcGrid.JSON, options?: ICalcGrid.SeedOptions): Promise<ICalcGrid.Results>;
+    /** {@inheritDoc ICalcGrid.revert} */
+    revert(options: ICalcGrid.RevertOptions): Promise<ICalcGrid.Results>;
+    /** {@inheritDoc ICalcGrid.delete} */
+    delete(options?: ICalcGrid.RequestOptions): void;
+    /**
+     * Whether the grid is in the model as the store is now: not closed, made at or before the
+     * current snapshot, and not deleted there.
+     * @internal
+     */
+    _isLive(): boolean;
     /** {@inheritDoc ICalcGrid.setReferenceAt} */
-    setReferenceAt(row: number, column: number, index: number, precedent: IRange.FixableCoords | IRange.FixableCellCoords | FormulaError.Ref): this;
+    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>;
+    /** {@inheritDoc ICalcGrid.calculate} */
+    calculate(full?: boolean): Promise<ICalculation.Status>;
+    /** {@inheritDoc ICalcGrid.markDirtyRegions} */
+    markDirtyRegions(coords: IRange.Coords[]): void;
+    /**
+     * Send a formula this grid holds to the engine again, without writing it here: an engine grid
+     * made since it was written. The answer lands as any answer does.
+     * @internal
+     */
+    _resendFormula(coords: IRange.Coords, text: string): Promise<ICalcGrid.Results>;
+    /** Whether a sheet owns this grid: see {@link CalcGrid.HostOptions.isOwned}. @internal */
+    _isOwned(): boolean;
+    /** {@inheritDoc ICalcGrid.Backend.requestPass} @internal */
+    _requestPass(): void;
+    /** {@inheritDoc ICalcGrid.getGraphNeighborsAt} */
+    getGraphNeighborsAt(coords: IRange.Coords, kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
+    /** {@inheritDoc ICalcGrid.Backend.getNameGraph} @internal */
+    _getNameGraph(kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
+    /** {@inheritDoc ICalcGrid.evaluateAt} */
+    evaluateAt(row: number, column: number, options?: number | ICalculation.EvaluateOptions): Promise<Scalar | IRange>;
+    /** `true` once closed: its state is gone. @internal */
+    _isClosed(): boolean;
+    /**
+     * Whether the snapshot the store is at holds this grid's maps: a restore to a commit older than
+     * the grid leaves it none. @internal
+     */
+    _hasState(): boolean;
+    /** {@inheritDoc ICalcGrid.Backend.evaluateScalarAt} @internal */
+    _evaluateScalarAt(row: number, column: number, evalIndex?: number): Promise<Scalar>;
+    /**
+     * Write a body as authored: the engine anchors it and answers with the record, which lands here
+     * as any answer does. Nothing is written here first - the text is the engine's to make.
+     * @internal
+     */
+    _setBody(options: ICalcGrid.BodyOptions): Promise<ICalcGrid.Results>;
     /** {@inheritDoc ICalcGrid.isVolatileAt} */
-    isVolatileAt(row: number, column: number): boolean;
-    protected _formulaAt(row: number, column: number): ISpatialMap.Entry<FormulaSpatialValue> | null;
+    isVolatileAt(row: number, column: number): Promise<boolean>;
+    /** {@inheritDoc ICalcGrid.addListeners} */
+    addListeners(listeners: ICalcGrid.IListeners, options?: IListener.Options): IListener.Remove;
+    protected _notify<T>(key: keyof ICalcGrid.Events, params: T): void;
+    /** {@inheritDoc ICalcGrid.getEntireCoords} */
+    getEntireCoords(): IRange.Coords;
+    /** {@inheritDoc ICalcGrid.resize} */
+    resize(options?: ICalcGrid.RequestOptions): void;
+    /** {@inheritDoc ICalcGrid.getId} */
+    getId(): string;
+    /** {@inheritDoc ICalcGrid.toJSON} */
+    toJSON(options?: ICalcGrid.ToJSONOptions): Promise<ICalcGrid.JSON | null>;
     /**
-     * Create non error spill entries for move/copy.
+     * What a start seeds the backend from: this map's formulas and every value the host holds. A
+     * host with nothing yet still seeds (an empty record), so the engine runs its full pass and
+     * answers for it.
+     * @internal
      */
-    protected _createCopySpillEntries(spillSpatial: ISpatialMap<SpillEntry>, from: IRange.Coords, to: IRange.Coords, reuseInserts?: ISpatialMap.Entry<SpillEntry>[] | null, reuseRemoves?: ISpatialMap.Entry<SpillEntry>[] | null): ISpatialMap.Updates;
+    _seedContent(): ICalcGrid.JSON | null;
     /**
-     * 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.
+     * This grid's content as its calc JSON (DESIGN-CALC-SERVICE §6.6): the same record a save
+     * writes, and what a start opens the backend from. The formulas, the array extents, the
+     * volatile regions and - with `includeData` - the values are all this grid's own; a volatile
+     * region is kept only where a formula still sits.
      *
-     * @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.
+     * A pending entry is written as its own text; a compiled one images its block where it sits.
+     * @internal
+     */
+    _content(options?: ICalcGrid.ToJSONOptions): ICalcGrid.JSON | null;
+    /** The array extents a load carries, as spill entries. */
+    protected _spillsFromJSON(formulaArray: readonly IRange.JSONReferenceTuple<ITypes.FormulaArrayKind>[]): ISpatialMap.Entry<SpillEntry>[];
+    protected _entriesFromJSON(formulas: readonly IRange.JSONReferenceTuple<string>[]): ISpatialMap.Entry<FormulaEntry>[];
+    /**
+     * What the backend pushed (a pass's results, a seed's): the formula half is adopted here, then
+     * the host hears the whole record.
+     * @internal
+     */
+    _onCalculated(results: ICalcGrid.Results): void;
+    /**
+     * What a verb's answer goes through: the formula half adopted, unless the savepoint the
+     * request was made under (read now, as the request is made) has rolled back since.
+     */
+    protected _adopter(): (results: ICalcGrid.Results) => ICalcGrid.Results;
+    /**
+     * The block a reference edit answered with, adopted into the entry over that cell, inside the
+     * batch that asked for the edit.
+     */
+    protected _adoptAt(row: number, column: number, block: IFormulaBlockView | null): IFormulaBlockView | null;
+    /**
+     * The snapshots a record lands in, oldest first: the one it names, every later one on the
+     * live history, and the operation in progress if there is one.
      *
-     * @remarks
-     * This modifies the insert in place.
+     * @returns `null` when the record answers for a snapshot off the live history (undone, rolled
+     * back, pruned) or one this grid did not exist at: nothing it says is true anywhere. A record
+     * naming no snapshot, or the operation in progress, is current by construction.
      */
-    protected _reanchorFormulas(inserts: ISpatialMap.Entry<FormulaSpatialValue>[], gridExplicitId?: string | null, targetScope?: string | null, force?: boolean): void;
+    protected _vendSnapshots(commitId: string | undefined): VendSnapshot[] | null;
     /**
-     * Will copy tiles and invalidate relative precedents that are out
-     * of bounds.
+     * The snapshot before the one a record names, or `null` when it is the first: a map instance
+     * the record's snapshots share with it is history's, and is cloned before the record lands.
      */
-    protected _copyTo(snapshot: CalcGridSnapshot, from: IRange.Coords, to: IRange.Coords): void;
+    protected _vendParentState(requested: VendSnapshot): Readonly<CalcGrid.State> | null;
+    /** Fold a vend's maps into a snapshot: a bookkeeping write, never an edit. */
+    protected _writeVend(snapshot: VendSnapshot, update: Partial<CalcGrid.State>): void;
     /**
-     * Will update absolute precedents from precedentEntries relative precedents get shifted
+     * Adopt the formula half of a result record: the views the backend vends, onto the entries
+     * they were compiled for.
+     *
+     * @remarks
+     * A block that spells the entry's formula (`sum(a1)` compiled to `SUM(A1)`, or the same block
+     * vended again on a full pass) is patched into the entry IN PLACE: it is the same formula, so
+     * every snapshot that holds the entry carries it, and a handle taken before the vend reads
+     * the block through the same object. A block whose formula differs - a reference re-imaged
+     * by a shift, a `#REF!` - or a change to the map's shape (a split, a cleared region, a block
+     * minted where the map held nothing) is model state: it is written to a clone of the map and
+     * folded into the snapshot the record names, so an undo restores the map as it was before the
+     * operation that caused it, and never the pending text of a request that has been answered.
+     *
+     * The record is applied to the snapshot it names first, then to every later snapshot on the
+     * live history, where it changes only what nothing newer has written: an entry is settled
+     * when the named snapshot holds the same entry at the same cells, and a region is settled when
+     * every entry over it is - the newer write's own resolution carries the truth for the rest. A
+     * record naming a snapshot off the live history is dropped whole: the backend's revert
+     * re-vends every block a restore exposes. On a full record every entry's block is dropped
+     * first; the record lists every block.
      */
-    protected _moveTo(snapshot: CalcGridSnapshot, from: IRange.Coords, to: IRange.Coords): void;
-    protected _notifyCalculated(cycleId: number, options: ICalculation.CalculateOptions | boolean): Promise<ICalcGrid.Results>;
-    protected _setInputs(values: Tuple.BoundedTuples<Scalar> | null, formulas: readonly ISpatialMap.Entry<string>[] | null, deleteRange?: IRange.Coords): IRange.Coords[];
+    protected _adopt(results: ICalcGrid.Results, vended?: readonly VendSnapshot[]): void;
     /**
-     * Used before loading a new state
+     * Land the value half of a record - values, spills, errors, pending and circular marks - in the
+     * snapshots it answers for, by ownership (DESIGN-CALC-SERVICE §13.18).
+     *
+     * @remarks
+     * Every item has one owner, and a snapshot's formula map says which: a cell holding a formula
+     * entry is the engine's, one holding none is the model's, a spill cell is the engine's through
+     * its anchor. So an item lands in a snapshot where that snapshot's map holds, over the item,
+     * what the requested snapshot's map held: the requested snapshot itself everywhere, a later one
+     * wherever nothing newer wrote. An item that a later write cut into is split at the ownership
+     * boundary when its payload is per cell (a value run, a pending or error mark, which the maps
+     * merge across neighbors) and left whole when it is one thing (a spill extent, a cycle). A full
+     * record clears an engine-owned map, keeping what a later snapshot owns.
+     *
+     * The maps are the snapshots' own instances, shared by reference until a write clones them, so
+     * each distinct instance is written once, settled for every snapshot that holds it. In-process
+     * the list is the requested snapshot alone and this is one write, as it always was. Nothing
+     * here goes through the caller's transaction: these are the backend's answers, regenerated by
+     * any pass.
      */
-    protected _clearAll(): void;
-    /** {@inheritDoc ICalcGrid.fromJSON} */
-    fromJSON(json: ICalcGrid.JSON, options?: ICalcGrid.FromJSONOptions): ICalcGrid.Results | undefined;
-    /** {@inheritDoc ICalcGrid.fromJSON} */
-    toJSON(options?: ICalcGrid.ToJSONOptions): Promise<ICalcGrid.JSON | null>;
+    protected _applyValueVend(results: ICalcGrid.Results, snapshots: readonly VendSnapshot[]): void;
+    /** {@inheritDoc ICalcGrid.close} */
+    close(): void;
+    get [Symbol.toStringTag](): string;
 }
 export declare namespace CalcGrid {
     /**
-     * Options available when creating a CalcGrid.
+     * Everything the grid holds for the model, versioned in the model's own store
+     * (DESIGN-CALC-SERVICE §13.23, §13.24): what the model wrote and what the backend answered
+     * with, one record per commit, so an undo restores them with the operation that wrote them.
      */
-    interface ConstructorOptions {
-        /**
-         * The calculation instance that will be used to calculate the grid.
-         *
-         * @remarks
-         * Required as this will contain the context
-         */
-        context: IFormulaContext;
+    interface State {
+        /** The formulas as the model wrote them, one entry per run, with the backend's view where it has vended one. */
+        formulaSpatial: ISpatialMap<FormulaEntry>;
+        /** The values: the literals the model entered and the answers the engine vended, one map. */
+        cellValuesGrid: ISparseGrid<Scalar>;
+        /** Which cells hold a value, per run: the summary index over {@link cellValuesGrid}. */
+        contentfulSpatial: ISpatialMap<ContentfulSpatialValue>;
+        /** The array extents: what the file said, what an array entry wrote, what the engine vended. */
+        spillSpatial: ISpatialMap<SpillEntry>;
         /**
-         * handler for calculation callbacks.
-         *
-         * @remarks
-         * The container contains information shared across all grids
+         * The volatile regions the file listed: what an `Off` save writes back and a seed carries,
+         * kept where a formula still sits under them. What the engine knows once it is up it answers
+         * itself; this list is not shifted by a structural change.
          */
-        container: IContextContainer;
+        volatile: IRange.Address[] | null;
+        /** Cells the engine has not answered for yet. */
+        pendingSpatial: ISpatialMap<boolean>;
+        /** Engine FAILURES by cell, as a message. Not error values - those are in the values. */
+        calcErrorsSpatial: ISpatialMap<string>;
         /**
-         * For status listening
+         * Cells in a reference cycle or downstream of one, by cycle (DESIGN-CIRCULAR-CALC.md §7.2).
+         * Maintained from the executor's deltas, like {@link pendingSpatial}.
          */
-        calculation: ICalculation | null;
+        circularSpatial: ISpatialMap<CircularEntry>;
         /**
-         * A callback that is called when the calculation is completed.
-         *
-         * @remarks
-         * This will persist through clones.
+         * Error VALUES by cell, as the WRITE path knows them: fresh for what the model entered and
+         * stale for formula cells, which is why {@link CalcGrid.getErrorValues} reconciles it against
+         * the values rather than answering from it. It collapses into the values once the executor
+         * emits error deltas.
          */
-        onCalculated?: (results: ICalcGrid.Results) => void;
+        errorSpatial: ISpatialMap<boolean>;
+        /** The grid was deleted - a sheet's removal - in this snapshot or before it. */
+        deleted: boolean;
+    }
+    /**
+     * The maps a write may change. Each is cloned once, on first ask, under the caller's key; a map
+     * the write never asks for is left as it is and copies nothing.
+     */
+    interface Writer {
+        /** The maps as they stand, for the reads a write makes on its way. Never clones. */
+        readonly current: Readonly<State>;
         /**
-         * A unique id that never changes for the grid.
+         * Reading one clones it, once; assigning one replaces it, for the shifts and rebuilds that
+         * answer with a map rather than editing the one they were given.
          */
-        uuid?: string;
+        formulas: ISpatialMap<FormulaEntry>;
+        values: ISparseGrid<Scalar>;
+        contentful: ISpatialMap<ContentfulSpatialValue>;
+        spills: ISpatialMap<SpillEntry>;
+        pending: ISpatialMap<boolean>;
+        calcErrors: ISpatialMap<string>;
+        circulars: ISpatialMap<CircularEntry>;
+        errorValues: ISpatialMap<boolean>;
+        /** The volatile regions are a list, not a map: replaced, never edited. */
+        volatile: IRange.Address[] | null;
+        /** An array extent the write set aside, moved or put back: reported with it. */
+        noteArray(extent: IRange.Coords): void;
         /**
-         * Returns the entire coordinate bounds for this grid.
-         * If not provided, defaults to the maximum sheet dimensions.
+         * Land what was asked for, in the caller's transaction. A write that lands more than once -
+         * a shift, which commits per range so a table sees what moved - lands the same maps again,
+         * as they stand.
          */
-        getEntireCoords?: () => IRange.Coords;
+        commit(): void;
+    }
+    /** What the host of a grid supplies: the sheet, for a grid that is a sheet's. */
+    interface HostOptions {
         /**
-         * `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).
+         * This grid has an owner in the model - a sheet. It seeds the engine at a start even when it
+         * holds nothing, so the engine runs its full pass and answers for it; a grid the engine made
+         * for itself (a name's host, a conditional format's body) does not.
          */
-        unanchored?: boolean;
+        isOwned?: boolean;
+        /** The grid a copy lands on, by id: another sheet's, or this one. */
+        getGrid?: (gridId: string) => CalcGrid | null;
+    }
+    interface ConstructorOptions extends HostOptions {
+        /** What the verbs forward to, and what answers. */
+        backend: ICalcGrid.Backend;
+        /** For the engine's status: an `Off` save is answered from this map. */
+        calculation?: ICalculation | null;
+        /** The model's store; every map this grid holds versions in it. A transient one with no model. */
+        transactions?: ITransaction.IStore;
+        /** What the aggregate cache over the values measures with. */
+        runtime: IRuntime;
+        /** The orientation of the value tuples a write carries. */
+        valuesAxis?: IRange.Axis;
     }
 }
-interface CalcGridSnapshot {
-    calcGrid: CalcGrid;
-    formulaSpatial: ISpatialMap3D<FormulaSpatialValue>;
-    precedentSpatial: ISpatialMap3D<PrecedentSpatialValue>;
-    volatile: Set<CalcNode> | null;
+/** A snapshot a vend lands in: this grid's record there, and whether it is the operation in progress. */
+interface VendSnapshot {
+    id: string;
+    state: Readonly<CalcGrid.State>;
+    open: boolean;
 }
-export declare function valueCompareValues<T>(a: ISpatialMap.Entry<T>, removing: ISpatialMap.Entry<T>): boolean;
+/** Whether `map` holds this very entry at these cells: what nothing newer has written. @internal */
+export declare const holdsFormulaEntry: (map: ISpatialMap<FormulaEntry>, hit: ISpatialMap.Entry<FormulaEntry>) => boolean;
+/** Whether `map` holds, over `region`, exactly the entries `requested` holds there. @internal */
+export declare const sameFormulaEntries: (requested: ISpatialMap<FormulaEntry>, map: ISpatialMap<FormulaEntry>, region: IRange.Coords) => boolean;
 export {};
 //# sourceMappingURL=CalcGrid.d.ts.map