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

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

@@ -1,33 +1,58 @@
 import { Scalar, IRange, FormulaError } from '@sheetxl/primitives';
-import { ReferenceableClipboard } from '@sheetxl/utils';
+import { RangeStats } from '../../primitives/RangeStats';
 import { ITypes } from '../../type';
+import { ITransaction } from '../../transaction';
 import { IListener } from '../../listener';
 import { IHistory } from '../../history';
-import { ISpatialQuery, ISpatialMap, ISparseGrid, Tuple } from '../../collections';
-import { IFormulaBlock } from '../formula';
+import { ISpatialMap, ISpatialQuery, ISparseGrid, Tuple } from '../../collections';
+import { IFormulaBlockView } from '../formula';
+import { FormulaEntry } from './FormulaEntry';
 import { ContentfulSpatialValue, SpillEntry, CircularEntry } from '../spatial';
-import { ReferenceCoords, NamedReference } from '../Types';
+import { NamedReference, NamedNodeInfo } from '../Types';
 import { ICalculation } from '../ICalculation';
 /**
- * The CalcGrid holds input and outputs of in a 2D space to a scope (usually a sheet).
+ * The CalcGridBackend holds input and outputs of in a 2D space to a scope (usually a sheet).
  *
  * @remarks
  * If inputValues are externally managed then formulas update must also be provided.
+ *
+ * Every mutation is ASYNCHRONOUS and resolves with an {@link ICalcGrid.Results}: the blocks the
+ * engine compiled or re-imaged for the write ({@link ICalcGrid.Results.formulaInserts}) and the
+ * coords it removed ({@link ICalcGrid.Results.formulaRemoves}). Nothing about the grid is readable
+ * synchronously after a write; a caller keeps its own formula text and patches it from the
+ * resolution. A request names the snapshot it was made at ({@link ICalcGrid.RequestOptions.commitId})
+ * and the resolution echoes it ({@link ICalcGrid.Results.commitId}): its coords mean addresses in
+ * THAT snapshot, whatever the caller has done since. A rewrite the engine makes to a grid nobody
+ * called - a cross-sheet reference turned `#REF!` by a delete on another sheet - reaches that grid
+ * through its own `onCalculated`, the way values do, naming the last snapshot the engine applied.
+ *
+ * Every request goes through the service's channel (DESIGN-CALC-SERVICE §4, §7.2). On a `Running`
+ * engine it is applied at once; while the engine is `Starting` it is held, as data, and applied
+ * in send order once the engine is up, behind the seed the grid was opened from; on an `Off`
+ * engine it is not recorded at all and resolves with nothing: the caller's own view is the truth
+ * there, and a later start is seeded from it. An `Off` engine is never started by a request.
  */
 export interface ICalcGrid {
     /**
      * Set a group of cells and formula ranges.
      *
-     * @param values A set of input values as BoundedTuples
+     * @param values A set of input values as Region
      * @param ranges A set of formula strings as ranged entries.
+     * @param options See {@link ICalcGrid.SetInputsOptions}.
+     *
+     * @returns Resolves with the blocks compiled for the written formulas, the remainders of any
+     * block a value split, and the coords cleared.
      */
-    setInputs(values: Tuple.BoundedTuples<Scalar> | null, formulas: readonly ISpatialMap.Entry<string>[] | null): IRange.Coords[];
+    setInputs(values: Tuple.Region<Scalar> | null, formulas: readonly ISpatialMap.Entry<string>[] | null, options?: ICalcGrid.SetInputsOptions): Promise<ICalcGrid.Results>;
     /**
      * Remove all values within a range.
      *
      * @param coords The coordinates to remove.
+     * @param options See {@link ICalcGrid.RemoveOptions}.
+     *
+     * @returns Resolves with the coords cleared and the remainders of any block the range split.
      */
-    remove(coords: IRange.Coords): IRange.Coords[];
+    remove(coords: IRange.Coords, options?: ICalcGrid.RemoveOptions): Promise<ICalcGrid.Results>;
     /**
      * Execute a calculate on a single grid.
      *
@@ -49,107 +74,188 @@ export interface ICalcGrid {
      */
     markDirtyRegions(coords: IRange.Coords[]): void;
     /**
-     * Returns true if there are any dirty regions that need to be calculated.
+     * The key of this grid's record in the model's store (DESIGN-CALC-SERVICE §13.23): what the
+     * grid holds, versioned beside the sheet's own record so that an undo restores both together.
+     *
+     * @remarks
+     * For a cell buffer to name among the records its held writes go to, so that a read of the
+     * grid through the store makes those writes first. The reads themselves take the transaction
+     * to answer for; nothing reads the record by this key.
      */
-    getDirtyRegions(): ISpatialQuery;
+    getStateId(): string;
     /**
-     * Returns the formula block at the given coordinates.
+     * The values as the model holds them: the literals it entered and the answers the engine
+     * vended, one map (DESIGN-CALC-SERVICE §13.24).
      *
-     * @param row The row of the cell to evaluate.
-     * @param column The column of the cell to evaluate.
+     * @remarks
+     * The whole grid, not a narrowed read surface: the sheet reads values on its hottest paths and
+     * sparse grids are heading for buffer-backed runs, which closes the boundary a narrower type
+     * would have bought. Answered from the grid's own store record - never the backend's working
+     * copy, which is on the far side of the boundary and can be behind.
+     * @param transaction Read the record as this transaction sees it, its held writes not yet
+     * made; the current record when omitted.
      */
-    getFormulaBlockAt(row: number, column: number): IFormulaBlock | null;
+    getValues(transaction?: ITransaction | null): ISparseGrid<Scalar>;
     /**
-     * Returns a queryable spatial index of all formulas in the graph.
-     *
-     * @remark
-     * Used by sheet
+     * The contentful index: which cells hold a value, summarized per run. Derived from
+     * {@link getValues} and kept in step with it.
+     * @param transaction Read the record as this transaction sees it, its held writes not yet
+     * made; the current record when omitted.
+     */
+    getContentful(transaction?: ITransaction | null): ISpatialMap<ContentfulSpatialValue>;
+    /**
+     * The array extents: where an array-entered or dynamic formula occupies more than its anchor.
+     * @param transaction Read the record as this transaction sees it, its held writes not yet
+     * made; the current record when omitted.
+     */
+    getSpills(transaction?: ITransaction | null): ISpatialMap<SpillEntry>;
+    /**
+     * The cells the engine has not answered for yet - an async function in flight, a pass still
+     * running.
+     * @param transaction Read the record as this transaction sees it, its held writes not yet
+     * made; the current record when omitted.
+     */
+    getPending(transaction?: ITransaction | null): ISpatialMap<boolean>;
+    /**
+     * Engine FAILURES by cell (a formula that could not be evaluated), as a message. Not error
+     * VALUES - those are {@link getErrorValues}.
+     * @param transaction Read the record as this transaction sees it, its held writes not yet
+     * made; the current record when omitted.
      */
-    getFormulas(): ISpatialQuery<IFormulaBlock>;
+    getCalcErrors(transaction?: ITransaction | null): ISpatialMap<string>;
     /**
-     * Returns 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.
+     * Cells in a reference cycle or downstream of one, by cycle (DESIGN-CIRCULAR-CALC.md §7.2).
+     * @param transaction Read the record as this transaction sees it, its held writes not yet
+     * made; the current record when omitted.
+     */
+    getCirculars(transaction?: ITransaction | null): ISpatialMap<CircularEntry>;
+    /**
+     * Error VALUES (`#DIV/0!`, `#N/A`, ...) by cell: the `Error` scalar kind, entered or computed.
+     * Deliberately not per-type - an entry means "an error value lives here".
      *
-     * @remark
-     * The same index a calculation 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.
+     * @remarks
+     * The reconciled view. The index the write path maintains is fresh for what the model entered
+     * and stale for formula cells (the executor does not emit error deltas yet), so this
+     * reconciles it against the values and caches the result until the values change again. It
+     * collapses into a plain read once the executor emits those deltas.
      */
-    getSpills(): ISpatialQuery<SpillEntry>;
+    getErrorValues(): ISpatialMap<boolean>;
     /**
-     * Returns the current values on the grid.
+     * 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 ({@link isVolatileAt}); this list is not shifted by a structural change.
      */
-    getValues(): ISparseGrid<Scalar>;
+    getVolatileRegions(): IRange.Address[] | null;
     /**
-     * Shifts all values in the graph in a given direction.
+     * The statistics cache over {@link getValues}, for the aggregate reads.
      *
-     * @param options The options for the shift.
+     * @remarks
+     * Here because it caches against the value grid INSTANCE, and the instance changes whenever a
+     * write or a vend clones the map - which is the grid's business, not its reader's.
      */
-    shift(options: ICalcGrid.ShiftOptions): this;
+    getRangeStats(): RangeStats;
     /**
-     * Returns a snapshot of the graph that can be used for copying.
+     * The formula at a cell, as the model holds it: its text the moment it is written, the
+     * compiled block's view once the engine has vended one. `null` where there is none.
      */
-    getSnapshot(options?: ICalcGrid.GetSnapshotOptions): ICalcGrid.ISnapshot;
+    getFormulaAt(row: number, column: number): FormulaEntry | null;
     /**
-     * Autofill the values from a single cell to the entire range.
+     * The formulas as the model holds them, one entry per run, as a read-only spatial query: the
+     * text the moment it is written, the compiled block's view once the engine has vended one.
+     *
+     * @param commitId A commit to answer for, in place of the current state. `null` when the store
+     * no longer has it on its live history (undone, rolled back, pruned) or this grid did not exist
+     * at it.
      *
      * @remarks
-     * This is similar to getSnapshot but doesn't return a promise.
+     * The current map. A past snapshot's is read from the store, at the commit, under
+     * {@link getStateId}.
+     * @param transaction Read the record as this transaction sees it, its held writes not yet
+     * made; the current record when omitted.
      */
-    autoFill(template: IRange.Coords | string, destination: IRange.Coords | string): this;
+    getFormulas(transaction?: ITransaction | null): ISpatialQuery<FormulaEntry>;
     /**
-     * Returns the dependents for a specific range.
+     * Shifts all values in the graph in a given direction.
      *
-     * @param coords The coordinates of the range.
+     * @param options The options for the shift.
      *
      * @remarks
-     * A range a formula resolved at run time — `INDIRECT`, `OFFSET` — is reported like any other,
-     * with the caveat under {@link getDirectPrecedentsAt}.
+     * Shifts THIS grid in place; a caller that versions the grid clones it first.
+     *
+     * @returns Resolves with the blocks re-imaged by the shift (references across the boundary,
+     * `#REF!`, split pieces) at their new coords, and the coords vacated.
      */
-    getDirectDependentsAt(coords: IRange.Coords): IRange.Coords[];
+    shift(options: ICalcGrid.ShiftOptions): Promise<ICalcGrid.Results>;
     /**
-     * Returns the precedents for a specific range.
+     * The model has restored itself to a snapshot (an undo, a redo): the engine restores its own
+     * history to the same id (design §13.13).
      *
-     * @param coords The coordinates of the range.
+     * @param options The snapshot restored to.
      *
      * @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 and should not be cached as one. A written reference is a
-     * property of the formula's text: true before anything calculates, and unchanged until the text
-     * changes. A resolved one is a record of the last calculation, so it moves when the formula's own
-     * inputs move (`INDIRECT(B1&"!A1")` names a different sheet once `B1` does), and it is absent
-     * entirely for a block that has not been calculated yet.
+     * A response to a request that the restore undid is dropped, so the entries the restore put
+     * back have no block until the engine says what it holds for them. The engine knows what
+     * changed between the two snapshots from what its commits recorded.
      *
-     * Its bounds are also the union of everything the block read, which for a scattered read is wider
-     * than the cells actually touched. Deliberately: over-reporting costs a caller a check that comes
-     * back clean, where under-reporting hands it an incomplete answer that looks complete.
+     * @returns Resolves with the blocks over the changed cells, at the coords they have in the
+     * restored snapshot, and those coords as removes: the view re-adopts exactly what the engine
+     * holds there.
+     */
+    revert(options: ICalcGrid.RevertOptions): Promise<ICalcGrid.Results>;
+    /**
+     * Returns a snapshot of the graph that can be used for copying.
      */
-    getDirectPrecedentsAt(coords: IRange.Coords): IRange.Coords[];
+    getSnapshot(options?: ICalcGrid.GetSnapshotOptions): ICalcGrid.ISnapshot;
     /**
-     * Returns all ranges recursively, including those that depend on it indirectly
-     * through the full calculation chain.
+     * Autofill the values from a single cell to the entire range.
      *
      * @remarks
-     * This performs a recursive search downstream to find the total impact of a value change.
+     * Fills THIS grid in place; a caller that versions the grid clones it first.
+     *
+     * @param options See {@link ICalcGrid.RequestOptions}.
+     *
+     * @returns Resolves with the blocks minted over the destination.
      */
-    getDependentsAt(coords: IRange.Coords): IRange.Coords[];
+    autoFill(template: IRange.Coords | string, destination: IRange.Coords | string, options?: ICalcGrid.RequestOptions): Promise<ICalcGrid.Results>;
     /**
-     * Returns all precedents recursively, including those referenced indirectly
-     * through the full calculation chain.
+     * Everything `coords` depends on, or that depends on it - cells AND names, in ONE call.
+     *
+     * @param coords The range to answer for, scoped in calc currency (a sheet's stableId, or bare
+     *   for this grid).
+     * @param kind Which direction to walk.
+     * @param direct `true` for one hop, `false` for the full recursive closure.
      *
      * @remarks
-     * This performs a recursive search upstream to find all root data sources.
+     * The graph question belongs here whole. Composed by a caller it was two calls plus the
+     * knowledge of which of the four walks pairs with which name half - calculation reasoning that
+     * had leaked into the model layer.
+     *
+     * The two halves are found differently, which is the reason they are not one list. A PRECEDENT
+     * name is one the queried formulas MENTION (apply-at-eval leaves no cell edge for it). A
+     * DEPENDENT name is one whose virtual grid a walk result LANDED in - that name's body reading
+     * these cells - and it is reported only while the name is live.
+     *
+     * `cells` stay in calc currency; converting their scope to something addressable is the model's
+     * job, as is turning ids into range objects.
      */
-    getPrecedentsAt(coords: IRange.Coords): IRange.Coords[];
+    getGraphNeighborsAt(coords: IRange.Coords, kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
     /**
-     * Returns the absolute direct precedents for a formula.
+     * Evaluates the formula at a cell and returns its finalized value.
      *
      * @param row The row of the cell to evaluate.
      * @param column The column of the cell to evaluate.
-     * @throws Error if there is not a formula at the coordinates.
+     * @param options An eval index, or {@link ICalculation.EvaluateOptions}.
+     *
+     * @remarks
+     * The engine side of `IFormula.evaluate()`. Evaluating needs the calc scope, which only the
+     * engine has - so it lives on this surface rather than on the block a caller is holding, and
+     * is `async` for the same reason `IFormula.evaluate()` always was.
+     *
+     * Resolves to `null` when no formula is at the cell. The block is resolved HERE rather than
+     * captured by the caller: the engine re-mints a block on every rewrite, so a captured
+     * instance can be a snapshot of the formula as it was.
      */
-    getReferencesAt(row: number, column: number): ReferenceCoords[];
+    evaluateAt(row: number, column: number, options?: number | ICalculation.EvaluateOptions): Promise<Scalar | IRange>;
     /**
      * Sets the reference to an absolute range at a specific cell coordinate.
      *
@@ -161,27 +267,36 @@ export interface ICalcGrid {
      *   {@link IFormulaBlock.setReferenceAt}.
      * @throws Error if the cell is not a formula.
      */
-    setReferenceAt(row: number, column: number, index: number, precedent: IRange.FixableCoords | IRange.FixableCellCoords | NamedReference | FormulaError.Ref): this;
+    setReferenceAt(row: number, column: number, index: number, precedent: IRange.FixableCoords | IRange.FixableCellCoords | NamedReference | FormulaError.Ref): Promise<IFormulaBlockView | null>;
     /**
-     * Return true if the cell at row column is volatile.
+     * Cycles the absolute/relative (`$`) style of the reference at `index` - F4.
      *
-     * @param row The row of the cell to evaluate.
-     * @param column The column of the cell to evaluate.
+     * @param row The row of the cell holding the formula.
+     * @param column The column of the cell holding the formula.
+     * @param index The index of the reference to cycle (aligned to the formula's references,
+     *   `IFormulaBlockView.getReferencesAt`).
+     * @param side Which corner of a range to cycle; `'self'` for a standalone cell.
+     * @param mode An explicit mode, or `undefined` to advance one step in the F4 order.
+     * @throws Error if there is no CELL reference at `index` (a named reference has no `$` style).
      *
      * @remarks
-     *
-     * This is not used internally but is provided to allow api to query.
+     * Read-cycle-write in ONE call. Composed on the client it is three round trips per keypress
+     * (the reference, then the write, then reading the result back), which is the wrong shape
+     * for a proxied engine.
      */
-    isVolatileAt(row: number, column: number): boolean;
+    setReferenceModeAt(row: number, column: number, index: number, side?: ICalculation.ReferenceSide, mode?: number): Promise<IFormulaBlockView | null>;
     /**
-     * Returns a copy on write clone.
+     * Whether the formula at the cell is volatile: found by the engine as it evaluates, so a
+     * question answered in order behind the writes sent before it.
      *
-     * @param cloneKey A performance optimization that will avoid cloning if the same key is used.
+     * @param row The row of the cell to evaluate.
+     * @param column The column of the cell to evaluate.
      *
      * @remarks
-     * If the same clone key is used then the same instance will be returned.
+     *
+     * This is not used internally but is provided to allow api to query.
      */
-    clone(cloneKey?: any): this;
+    isVolatileAt(row: number, column: number): Promise<boolean>;
     /**
      * Add Listeners to graph.
      */
@@ -191,26 +306,31 @@ export interface ICalcGrid {
      */
     getEntireCoords(): IRange.Coords;
     /**
-     * Returns the bounding range for the content.
-     *
-     * @remarks
-     * This includes values and formulas.
+     * The grid's size changed: {@link getEntireCoords} answers the new one. The engine is told in
+     * order with the grid's writes, under the snapshot named, so an undo restores the old size there.
      *
-     * @returns `null` if the grid has no content.
+     * @param options See {@link ICalcGrid.RequestOptions}.
      */
-    getBoundingRange(): IRange.Coords | null;
+    resize(options?: ICalcGrid.RequestOptions): void;
     /**
-     * Loads the json into the graph.
+     * Opens the grid from a seed: a statement of its whole content (DESIGN-CALC-SERVICE §6).
      *
-     * @param json The JSON to load.
-     * @param options {@link ICalcGrid.FromJSONOptions}
+     * @param json The content, the same record a save writes.
+     * @param options {@link ICalcGrid.SeedOptions}
      *
      * @remarks
-     * This will clear all values and formulas including any pending changes or invalidation.
+     * Replaces everything the grid held, so opening twice equals opening once. A seed is a request
+     * like any other: applied at once on a `Running` engine, held in order while the engine is
+     * `Starting`, not recorded on an `Off` one (the owner keeps the content and hands it over again
+     * when the service is started). Its results are a full pass's - `isFull`, every block it
+     * compiled and every array extent it read - and reach the owner through `onCalculated` as it is
+     * applied, in order with every other record the grid pushes; the promise resolves after that.
      *
-     * @returns `undefined` when the calculation is not ready (the load is deferred until start).
+     * A seed trusts the values it carries as a load does. One handed over at `start()` by an owner
+     * the engine has not been following - a sheet written to while `Off` - asks for a full pass
+     * instead ({@link ICalcGrid.SeedOptions.full}).
      */
-    fromJSON(json: ICalcGrid.JSON, options?: ICalcGrid.FromJSONOptions): ICalcGrid.Results | undefined;
+    seed(json: ICalcGrid.JSON, options?: ICalcGrid.SeedOptions): Promise<ICalcGrid.Results>;
     /**
      * Returns a JSON representation of the calcGrid.
      *
@@ -224,16 +344,18 @@ export interface ICalcGrid {
      */
     getId(): string;
     /**
-     * Returns a record for new incremental updates.
+     * Remove the grid from the calculation: every formula that read it reads `#REF!`.
      *
-     * @remarks
-     * This will create a new record for tracking incremental updates.
+     * @param options See {@link ICalcGrid.RequestOptions}; the removal lands under the snapshot
+     * named, and a revert to before it registers the grid again.
      */
-    beginUpdates(): ICalcGrid.IncrementalUpdates;
+    delete(options?: ICalcGrid.RequestOptions): void;
     /**
-     * Remove the grid from the calculation.
+     * Release the grid: its owner is done with it. The engine takes it out of the graph and every
+     * formula that read it computes `#REF!` on its next evaluation. Not undoable - {@link delete} is
+     * the removal an undo brings back.
      */
-    delete(): void;
+    close(): void;
 }
 /**
  * {@inheritDoc ICalcGrid}
@@ -244,7 +366,83 @@ export interface ICalcGrid {
  * {@link ICalcGrid}
  */
 export declare namespace ICalcGrid {
+    /**
+     * What the model's grid forwards to (DESIGN-CALC-SERVICE §13.23): every verb and every read
+     * the engine answers, and nothing the model holds for itself. The in-process engine grid is
+     * one; a message-passing proxy under a worker is another.
+     */
+    type Backend = Omit<ICalcGrid, 'getStateId' | 'getFormulaAt' | 'getFormulas' | 'getValues' | 'getContentful' | 'getSpills' | 'getPending' | 'getCalcErrors' | 'getCirculars' | 'getErrorValues' | 'getVolatileRegions' | 'getRangeStats'> & {
+        /** Write a body as authored; the engine anchors it (see {@link ICalcGrid.BodyOptions}). */
+        setBody(options: ICalcGrid.BodyOptions): Promise<ICalcGrid.Results>;
+        /** {@link ICalcGrid.evaluateAt} coerced to one scalar, as a defined name's `evaluate()` is. */
+        evaluateScalarAt(row: number, column: number, evalIndex?: number): Promise<Scalar>;
+        /** Owe a pass seeded from this grid, run once the current flush is over. */
+        requestPass(): void;
+        /**
+         * The graph around the defined name whose body this grid holds - its precedents or
+         * dependents, cells in calc currency and names - as {@link ICalcGrid.getGraphNeighborsAt}
+         * answers for cells.
+         */
+        getNameGraph(kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
+    };
+    /**
+     * A body written as it was authored, for a grid that holds one (a name's, a watch's): the engine
+     * compiles it where it was authored, binds every bare reference to `scopeGridId`, and writes it
+     * over `coords` imaged at their top-left.
+     */
+    interface BodyOptions {
+        /** Where the body goes: the block's extent. */
+        coords: IRange.Coords;
+        /** The expression as authored. */
+        expression: string;
+        /** The cell the expression was authored at; relative references are offsets from here. */
+        authoredAt: IRange.CellCoords;
+        /** The sheet grid a bare reference in the expression resolves against. */
+        scopeGridId: string;
+        /** Re-derive the formulas that mention this grid's name once the body is in: a defined name's. */
+        recompile?: boolean;
+        /**
+         * Applied ahead of the other requests a start holds: a defined name must be bound before any
+         * formula that mentions it is examined.
+         */
+        priority?: boolean;
+    }
+    /**
+     * What {@link ICalcGrid.getGraphNeighborsAt} answers: the two halves of a graph neighborhood,
+     * both in currency that crosses a wire.
+     */
+    interface GraphNeighbors {
+        /** Neighbor ranges, scoped by GRID (a sheet's stableId), or unscoped for the queried grid. */
+        cells: IRange.Coords[];
+        /** The named formulas in the neighborhood, as plain data ready to become range objects. */
+        names: NamedNodeInfo[];
+    }
+    /**
+     * A cell's format on entry when its formula reads cells (see {@link Results.formatInserts}).
+     *
+     * @remarks
+     * Excel ranks the cell a formula reads ahead of a function's format - `=A1+TODAY()` shows what
+     * `A1` does - and falls back to the function's only when no reference carries one.
+     */
+    interface InheritedFormat {
+        /**
+         * The references the formula reads as values, in text order, relative to the entry's own
+         * top-left: offsets on a relative axis, a position on a fixed one. A range stands for its
+         * top-left cell. The first whose cell's format is not General is the cell's.
+         */
+        references: IRange.FixableCoords[];
+        /** The format the formula's functions supplied, for when none of the references carries one. */
+        fallback: string | null;
+    }
+    /** What a {@link Results.formatInserts} entry carries: a function's format, or what to inherit. */
+    type FormatInsert = string | InheritedFormat;
     interface Results {
+        /**
+         * The snapshot this record answers for: the {@link RequestOptions.commitId} of the request,
+         * or, for a record the engine pushed (a calculation pass), the last commit the engine
+         * applied. The formula coords below are addresses in that snapshot.
+         */
+        commitId?: string;
         /**
          * The id of the calculation that was completed.
          *
@@ -268,12 +466,12 @@ export declare namespace ICalcGrid {
          */
         bounds?: IRange.Coords | null;
         /**
-         * The results of the calculation will either be as `Map` or as a `Tuple.BoundedTuples`.
+         * The results of the calculation will either be as `Map` or as a `Tuple.Region`.
          *
          * @see
          * {@link CalculateOptions.asTuples}
          */
-        valueInserts?: Tuple.BoundedTuples<Scalar>;
+        valueInserts?: Tuple.Region<Scalar>;
         /**
          * Values that have been cleared.
          */
@@ -288,12 +486,16 @@ export declare namespace ICalcGrid {
          */
         spillRemoves?: ISpatialMap.Entry[];
         /**
-         * Formatting updates due to functions.
+         * The number format each realized formula cell takes on entry: a format its functions
+         * supplied (`=TODAY()` a date), or the references it inherits one from.
          *
          * @remarks
-         * Formats are not cleared.
+         * One value per cell, the executor's pick: an {@link InheritedFormat} when the formula has
+         * references that are value operands (`IFormulaBlock.getFormatReferences`), else the
+         * function's string, else nothing. Which format the references carry, and as of when, is the
+         * reader's to resolve. Formats are not cleared.
          */
-        formatInserts?: ISpatialMap.Entry<string>[];
+        formatInserts?: ISpatialMap.Entry<ICalcGrid.FormatInsert>[];
         /**
          * Contains any errors that were inserted.
          */
@@ -319,6 +521,40 @@ export declare namespace ICalcGrid {
          * These are guaranteed to not overlap.
          */
         circularUpdates?: ISpatialMap.Entry<CircularEntry | null>[];
+        /**
+         * Blocks the engine compiled or re-imaged, at the coords they cover, as the read views the
+         * model holds: the vend of the formula half. Every site that mints a block reports it here -
+         * a write, a value splitting a block, a shift, a cross-sheet `#REF!`, a copy, a fill, a
+         * reference edit, the legacy `@` wrap on load.
+         *
+         * @remarks
+         * Applied in order after {@link formulaRemoves}. On {@link isFull} every block on the grid is
+         * listed, so a caller that dropped its blocks on the full pass has them all back. What
+         * crosses is the block as data; the view is imaged from it on the model's side of the
+         * channel, against the model's own symbols (DESIGN-CALC-SERVICE §8).
+         */
+        formulaInserts?: ISpatialMap.Entry<IFormulaBlockView>[];
+        /**
+         * Coords whose formulas the engine removed: cleared, replaced, or moved away by a shift.
+         */
+        formulaRemoves?: IRange.Coords[];
+        /**
+         * For a grid that holds one body (a watch's, a name's): the body's blank region as the pass
+         * left it, `null` when nothing is shared. Absent from a sheet's grid.
+         */
+        blankRegion?: ICalcGrid.BlankRegion | null;
+    }
+    /**
+     * The cells of a body that a pass shares one answer for rather than writing, and that answer:
+     * what every such cell reads as.
+     */
+    interface BlankRegion {
+        /** The shared answer. */
+        readonly value: Scalar | undefined;
+        /** The rectangles it covers, in the grid's coordinates. */
+        readonly rects: readonly IRange.Coords[];
+        /** The body's extent: a read wider than it shares nothing. */
+        readonly extent: IRange.Coords;
     }
     /**
      * Returns from `ICalcGrid.beginUpdates()`.
@@ -335,6 +571,18 @@ export declare namespace ICalcGrid {
         circularSpatial: ISpatialMap<CircularEntry>;
         contentfulSpatial: ISpatialMap<ContentfulSpatialValue>;
         notifyValues: ISpatialMap;
+        /**
+         * Reports a region whose answer changed without a write to the grid: a blank region the pass
+         * shares one answer for on the block instead of writing (PLAN-WATCHES-BLANK-AWARE §4c).
+         *
+         * @remarks
+         * Accumulated as bounds, not as a region index. Only `Results.bounds` learns of this - there
+         * are no values to vend - and that is one rectangle over every notify source, so the union is
+         * the whole of what a caller can observe.
+         *
+         * `coords` is read, never kept, and its scope is ignored.
+         */
+        notifyBlank(coords: IRange.Coords): void;
         notifySpillsInsert: ISpatialMap.Entry<SpillEntry>[];
         notifySpillsRemove: IRange.Coords[];
         notifyFormats: ISpatialMap;
@@ -344,7 +592,7 @@ export declare namespace ICalcGrid {
         circularConflating: ISpatialMap.IConflatingEntries<CircularEntry | false> | null;
         errorRemovesConflating: ISpatialMap.IConflatingEntries<null> | null;
         errorInsertsConflating: ISpatialMap.IConflatingEntries<string> | null;
-        formatsConflating: ISpatialMap.IConflatingEntries | null;
+        formatsConflating: ISpatialMap.IConflatingEntries<ICalcGrid.FormatInsert> | null;
         /**
          * Called when the incremental updates are completed
          *
@@ -356,35 +604,59 @@ export declare namespace ICalcGrid {
          */
         done(cycleId: number, options: ICalculation.CalculateOptions): void;
     }
-    interface GetSnapshotOptions extends ReferenceableClipboard.CopyOptions {
+    /**
+     * Options for {@link ICalcGrid.getSnapshot}: what the engine reads, named.
+     */
+    interface GetSnapshotOptions {
         /**
          * The range to capture the snapshot from. If omitted the entire range will be used.
          */
         range?: IRange.Coords | string;
+        /**
+         * `true` when the capture is for a move: the copy that follows vacates the source.
+         * @defaultValue false
+         */
+        isCut?: boolean;
     }
     /**
      * Provides destination details for the Snapshot when using `IHistory.ISnapshot.copyTo`.
      */
     interface SnapshotDestination {
         /**
-         * The destination calc graph to copy to.
+         * The id of the grid to copy to ({@link ICalcGrid.getId}): the destination is named, never
+         * handed over.
          */
-        calcGrid: ICalcGrid;
+        gridId: string;
+        /**
+         * The model's destination grid, when the caller holds it: what lets a copy land on another
+         * workbook's grid, which no id resolves to here. In-process only; never crosses a channel.
+         */
+        grid?: ICalcGrid;
         /**
          * The range to copy the snapshot to.
          */
         range: IRange.Coords | string;
     }
-    interface ISnapshot extends IHistory.ISnapshot<ICalcGrid.SnapshotDestination, ICalcGrid, IRange.Coords> {
+    interface ISnapshot extends IHistory.ISnapshot<ICalcGrid.SnapshotDestination, ICalcGrid.Backend, IRange.Coords, any, ICalcGrid.Results> {
         /**
-         * Called when the table is copied to a new collection.
+         * Copies the snapshot's formulas to the destination grid.
+         *
+         * @returns Resolves with the blocks minted at the destination (re-anchored, `#REF!` where a
+         * relative reference left the sheet) and, for a cut, the coords vacated at the source. The
+         * copied extent is the result's `bounds`.
          */
-        copyTo(destination: ICalcGrid.SnapshotDestination, options?: ICalcGrid.CopyOptions): Promise<IRange.Coords>;
+        copyTo(destination: ICalcGrid.SnapshotDestination, options?: ICalcGrid.CopyOptions): Promise<ICalcGrid.Results>;
     }
     /**
-     * Options for {@link ISnapshot.copyTo}.
+     * Options for {@link ISnapshot.copyTo}: what the engine reads, named. A caller's clipboard
+     * options (an undo selection, callbacks) are the caller's, and never ride along.
      */
-    interface CopyOptions extends ReferenceableClipboard.CopyOptions {
+    interface CopyOptions extends RequestOptions {
+        /**
+         * `true` for a move: the source is vacated and the precedents of other formulas follow.
+         * Defaults to what the snapshot was captured with.
+         */
+        isCut?: boolean;
         /**
          * When pasting from a smaller range to a larger range copy will repeat or 'wallpaper' the
          * source values.
@@ -409,10 +681,57 @@ export declare namespace ICalcGrid {
          */
         coords?: string[];
     }
+    /**
+     * Options for {@link ICalcGrid.setInputs}.
+     */
+    /**
+     * What every request to the grid carries.
+     */
+    /** Options for {@link ICalcGrid.remove}. */
+    interface RemoveOptions extends RequestOptions {
+        /**
+         * Treat the arrays the range touches as Clear Contents does: a fixed (array-entered) one is set
+         * aside and put back once the cells are empty, the spilled cells of an anchor inside go now,
+         * and one the range cuts through becomes a spill error. A typed delete does not.
+         *
+         * @defaultValue `false`
+         */
+        clearArrays?: boolean;
+    }
+    interface RequestOptions {
+        /**
+         * The id of the transaction snapshot the request is made at: the commit the calling
+         * operation is, or will be. Echoed on {@link Results.commitId}; the resolution's coords are
+         * addresses in this snapshot.
+         */
+        commitId?: string;
+        /**
+         * The savepoint the request is made under (`ITransaction.getSavepointId`): the root's id for
+         * a root-level write, a nested transaction's own for a nested one. What the engine's copy of
+         * the maps is keyed by, so a second write under the same savepoint updates the copy the
+         * first one made; and what a nested rollback names. Omit outside a transaction.
+         */
+        cloneKey?: string;
+    }
+    interface SetInputsOptions extends RequestOptions {
+        /**
+         * The formula being set is array-entered (Ctrl+Shift+Enter) over this extent: it anchors a
+         * `fixed` block whose result is fitted to these coordinates rather than spilling from them.
+         * Applies to the formula entry at the extent's top-left.
+         */
+        arrayFixed?: IRange.Coords;
+    }
+    /**
+     * What a restore tells the grid. See {@link ICalcGrid.revert}.
+     */
+    interface RevertOptions {
+        /** The snapshot the model restored to. */
+        commitId: string;
+    }
     /**
      * Options for shifting the calc graph.
      */
-    interface ShiftOptions {
+    interface ShiftOptions extends RequestOptions {
         /**
          * The range to shift.
          */
@@ -421,41 +740,44 @@ export declare namespace ICalcGrid {
          * The direction to shift.
          */
         direction: IRange.Direction;
+    }
+    /**
+     * What {@link Events.onInputsWritten} reports of a write.
+     */
+    interface InputsWritten {
+        /** Names the grid's inputs as this write left them; a later write names new ones. */
+        inputsId: string;
         /**
-         * If `true` the this will return a clone instance of the graph if there are any modifications.
-         *
-         * @defaultValue false
-         *
-         * @remarks
-         * This allows for a 0-1 clone on write.
+         * The array extents the write set aside, moved or put back - a shift carries a fixed array
+         * with the cells - or `null` when it touched none.
          */
-        cloneIfUpdate?: boolean;
+        arrays: readonly IRange.Coords[] | null;
     }
     /**
      * Events for {@link ICalcGrid}.
      */
     interface Events {
         /**
-         * Called when the calculation has been updated and a calculation has not been started.
+         * The engine answered: values, formulas and status for the cells `results` names. What it
+         * carries is already in this grid's maps when this is called.
          */
-        onInvalidate?(source: ICalcGrid): void;
-        /**
-         * Called when a calculation is started.
-         */
-        onStart?(source: ICalcGrid): void;
+        onComplete?(source: ICalcGrid, results: ICalcGrid.Results): void;
         /**
-         * Called when a calculation is completed.
+         * What a formula read answers changed without a write of the model's: the engine attached
+         * a compiled block, or rewrote a formula's text (`textChanged`).
          */
-        onComplete?(source: ICalcGrid, results: ICalcGrid.Results): void;
+        onFormulasChanged?(source: ICalcGrid, textChanged: boolean): void;
         /**
-         * Called when the calculation engine is unable to calc.
+         * A write the model made landed in this grid: an entry, a removal, a shift, a fill or a copy.
+         * Never a seed, never an answer of the engine's.
          *
          * @remarks
-         * This is not when a specific function fails, but when the calculation engine is unable to complete the calculation.
+         * Called synchronously, inside the operation the write is part of, so what a listener writes
+         * lands in the same commit.
          */
-        onError?(source: ICalcGrid): void;
+        onInputsWritten?(source: ICalcGrid, written: ICalcGrid.InputsWritten): void;
         /**
-         * Called when the CalcGrid is closed.
+         * The grid has closed: its owner closed, or the calculation it belongs to did.
          */
         onClose?(source: ICalcGrid): void;
     }
@@ -490,17 +812,16 @@ export declare namespace ICalcGrid {
         volatile?: IRange.Address[];
     }
     /**
-     * Options for {@link ICalcGrid.fromJSON}.
+     * Options for {@link ICalcGrid.seed}.
      */
-    interface FromJSONOptions {
+    interface SeedOptions {
         /**
-         * A structural transform applied to each formula's parsed tree (pre-link) as it loads —
-         * the READ half of the dialect hook. A format reader (io-xlsx) supplies its legacy unwrap
-         * here; native loads pass nothing.
+         * Recalculate everything the seed carries rather than trusting its values: the seed comes
+         * from an owner the engine was not following (design §13.13, the openpyxl rule).
          *
-         * @see {@link ICalculation.FormulaTransform}
+         * @defaultValue `false`
          */
-        formulaTransform?: ICalculation.FormulaTransform;
+        full?: boolean;
     }
     interface ToJSONOptions {
         /**
@@ -509,14 +830,6 @@ export declare namespace ICalcGrid {
          * @defaultValue `false`
          */
         includeData?: boolean;
-        /**
-         * A structural transform applied to each formula as it serializes (once per formula
-         * block, on the compiled AST) — how the xlsx writer applies its legacy spellings
-         * (see io-xlsx `LegacyFormula.ts`).
-         *
-         * @see {@link ICalculation.FormulaTransform}
-         */
-        formulaTransform?: ICalculation.FormulaTransform;
     }
 }
 //# sourceMappingURL=ICalcGrid.d.ts.map