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

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

@@ -12,27 +12,6 @@ import { NamedReference } from '../Types';
 import { ContentfulSpatialValue, SpillEntry, CircularEntry } from '../spatial';
 import { ICalcGrid } from './ICalcGrid';
 import { FormulaEntry } from './FormulaEntry';
-/**
- * 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;
@@ -134,8 +113,10 @@ export declare class CalcGrid implements ICalcGrid {
     getContentful(transaction?: ITransaction | null): ISpatialMap<ContentfulSpatialValue>;
     /** {@inheritDoc ICalcGrid.getSpills} */
     getSpills(transaction?: ITransaction | null): ISpatialMap<SpillEntry>;
+    /** {@inheritDoc ICalcGrid.getBlockedSpills} */
+    getBlockedSpills(): ISpatialQuery<SpillEntry>;
     /** {@inheritDoc ICalcGrid.getPending} */
-    getPending(transaction?: ITransaction | null): ISpatialMap<boolean>;
+    getCalcStatus(transaction?: ITransaction | null): ISpatialMap<ICalcGrid.CalcStatus>;
     /** {@inheritDoc ICalcGrid.getCalcErrors} */
     getCalcErrors(transaction?: ITransaction | null): ISpatialMap<string>;
     /** {@inheritDoc ICalcGrid.getCirculars} */
@@ -233,8 +214,6 @@ export declare class CalcGrid implements ICalcGrid {
     _demand(rects: readonly IRange.Coords[]): 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 */
@@ -281,15 +260,6 @@ export declare class CalcGrid implements ICalcGrid {
      * @internal
      */
     _seedContent(): ICalcGrid.JSON | null;
-    /**
-     * 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, the rows and columns the owner hides and - with `includeData` - the values
-     * are all this grid's own; a volatile region is kept only where a formula still sits.
-     *
-     * 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>[];
@@ -349,37 +319,12 @@ export declare class CalcGrid implements ICalcGrid {
      * first; the record lists every block.
      */
     protected _adopt(results: ICalcGrid.Results, vended?: readonly VendSnapshot[]): void;
-    /**
-     * 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 _applyValueVend(results: ICalcGrid.Results, snapshots: readonly VendSnapshot[]): void;
     /** {@inheritDoc ICalcGrid.close} */
     close(): void;
     get [Symbol.toStringTag](): string;
 }
 export declare namespace 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 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>;
@@ -389,6 +334,8 @@ export declare namespace CalcGrid {
         contentfulSpatial: ISpatialMap<ContentfulSpatialValue>;
         /** The array extents: what the file said, what an array entry wrote, what the engine vended. */
         spillSpatial: ISpatialMap<SpillEntry>;
+        /** See {@link ICalcGrid.getBlockedSpills}. */
+        blockedSpillSpatial: ISpatialMap<SpillEntry>;
         /**
          * 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
@@ -396,13 +343,9 @@ export declare namespace CalcGrid {
          */
         volatile: IRange.Address[] | null;
         /** Cells the engine has not answered for yet. */
-        pendingSpatial: ISpatialMap<boolean>;
+        calcStatusSpatial: ISpatialMap<ICalcGrid.CalcStatus>;
         /** Engine FAILURES by cell, as a message. Not error values - those are in the values. */
         calcErrorsSpatial: ISpatialMap<string>;
-        /**
-         * 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}.
-         */
         circularSpatial: ISpatialMap<CircularEntry>;
         /**
          * Error VALUES by cell, as the WRITE path knows them: fresh for what the model entered and
@@ -437,7 +380,8 @@ export declare namespace CalcGrid {
         values: ISparseGrid<Scalar>;
         contentful: ISpatialMap<ContentfulSpatialValue>;
         spills: ISpatialMap<SpillEntry>;
-        pending: ISpatialMap<boolean>;
+        blockedSpills: ISpatialMap<SpillEntry>;
+        calcStatus: ISpatialMap<ICalcGrid.CalcStatus>;
         calcErrors: ISpatialMap<string>;
         circulars: ISpatialMap<CircularEntry>;
         errorValues: ISpatialMap<boolean>;

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

@@ -9,9 +9,6 @@ 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.
@@ -20,7 +17,7 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
     _values: ISparseGrid<Scalar>;
     _spillSpatial: ISpatialMap<SpillEntry>;
     _errorSpatial: ISpatialMap<string>;
-    _pendingSpatial: ISpatialMap<boolean>;
+    _calcStatusSpatial: ISpatialMap<ICalcGrid.CalcStatus>;
     _circularSpatial: ISpatialMap<CircularEntry>;
     _contentfulSpatial: ISpatialMap<ContentfulSpatialValue>;
     _notifyValues: ISpatialMap;
@@ -29,7 +26,7 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
     _notifySpillsInsert: ISpatialMap.Entry<SpillEntry>[];
     _notifySpillsRemove: IRange.Coords[];
     _notifyFormats: ISpatialMap;
-    _notifyPending: ISpatialMap<boolean>;
+    _notifyCalcStatus: ISpatialMap<ICalcGrid.CalcStatus | false>;
     _notifyCircular: ISpatialMap<CircularEntry | false>;
     /**
      * Regions of this grid whose formula blocks were minted, re-imaged or removed since the last
@@ -75,11 +72,6 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
      * 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);
     /**
@@ -307,29 +299,6 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
      * 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. */
@@ -338,12 +307,13 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
     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;
+    protected _evaluateBlockNow(block: IFormulaBlock, 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;
+    _isVolatileNow(row: number, column: number): boolean;
     protected _formulaAt(row: number, column: number): ISpatialMap.Entry<FormulaSpatialValue> | null;
     /**
      * Create non error spill entries for move/copy.
@@ -379,6 +349,7 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
      * 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[];
+    _rederivePrecedentsNow(blocks: ISpatialMap.Entry<FormulaSpatialValue>[]): void;
     /**
      * 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.
@@ -421,6 +392,12 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
      * external book's cached values) is loaded this way; a model's goes through {@link seed}.
      */
     _seedNow(json: ICalcGrid.JSON, options?: ICalcGrid.SeedOptions): CalcResponse;
+    /**
+     * Whether `coords` is the anchor of a spill saved with its result: a result's first cell can be
+     * blank, which leaves no value at the anchor, and the spill's other cells are what say it ran. An
+     * extent with nothing in it is a writer that does not calculate, and is still owed its evaluation.
+     */
+    protected _isSavedSpill(coords: IRange.Coords): boolean;
     /** What a `toJSON` request answers: the grid's content as the engine holds it now. */
     protected _toJSONNow(options?: ICalcGrid.ToJSONOptions): ICalcGrid.JSON | null;
 }
@@ -497,7 +474,7 @@ export interface CalcGridMaps {
     contentful: ISpatialMap<ContentfulSpatialValue>;
     spills: ISpatialMap<SpillEntry>;
     errors: ISpatialMap<string>;
-    pending: ISpatialMap<boolean>;
+    calcStatus: ISpatialMap<ICalcGrid.CalcStatus>;
     circular: ISpatialMap<CircularEntry>;
     /** The size a `resize` gave, or `null` for the one the grid was made with. */
     entireCoords?: IRange.Coords | null;

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

@@ -8,15 +8,6 @@ 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'];
@@ -29,10 +20,6 @@ export declare class CalcGridProxy implements ICalcGrid.Backend {
      * 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;
@@ -96,8 +83,6 @@ export declare class CalcGridProxy implements ICalcGrid.Backend {
      * 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}
      *

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

@@ -1,6 +1,7 @@
 import { IRange, Scalar } from '@sheetxl/primitives';
 import { Tuple, ISparseGrid, ISpatialMap, ISpatialMap3D } from '../../collections';
 import { CalcNode } from '../state';
+import { ICalcGrid } from './ICalcGrid';
 import { ContentfulSpatialValue, FormulaSpatialValue, SpillEntry, PrecedentSpatialValue, CircularEntry, PrecedentKind } from '../spatial';
 import { ReferenceCoords } from '../Types';
 export declare function anchorCompareValues(a: ISpatialMap.Entry<FormulaSpatialValue>, removing: ISpatialMap.Entry<FormulaSpatialValue>): boolean;
@@ -58,9 +59,11 @@ export declare function clearErrorIndex(errorSpatial: ISpatialMap<string>, coord
  * @remarks
  * This code will inline spill errors but spill results are handled in calculations.
  */
-export declare function applyContentful(cycleId: number, removes: readonly IRange.Coords[] | null | undefined, inserts: ISpatialMap.Entry[] | null | undefined, contentfulSpatial: ISpatialMap<ContentfulSpatialValue>, spillSpatial: ISpatialMap<SpillEntry>, values: ISparseGrid<Scalar>, addDirty?: (colStart: number, rowStart: number, colEnd: number, rowEnd: number) => void, notifyValuesSpatial?: ISpatialMap, notifySpills?: (insert: ISpatialMap.Entry<SpillEntry>, remove: ISpatialMap.Entry<SpillEntry>) => void, notifyPending?: ISpatialMap<boolean>, errorSpatial?: ISpatialMap<string>, // notifyErrorSpatial,
+export declare function applyContentful(cycleId: number, removes: readonly IRange.Coords[] | null | undefined, inserts: ISpatialMap.Entry[] | null | undefined, contentfulSpatial: ISpatialMap<ContentfulSpatialValue>, spillSpatial: ISpatialMap<SpillEntry>, values: ISparseGrid<Scalar>, addDirty?: (colStart: number, rowStart: number, colEnd: number, rowEnd: number) => void, notifyValuesSpatial?: ISpatialMap, notifySpills?: (insert: ISpatialMap.Entry<SpillEntry>, remove: ISpatialMap.Entry<SpillEntry>) => void, notifyCalcStatus?: ISpatialMap<ICalcGrid.CalcStatus | false>, errorSpatial?: ISpatialMap<string>, // notifyErrorSpatial,
 isColumn?: boolean, notifyCalc?: boolean, // should notify. this is to differentiate between user set values and calc set values
-circularSpatial?: ISpatialMap<CircularEntry>): IRange.Coords | null;
+circularSpatial?: ISpatialMap<CircularEntry>, // the circular index: a written cell leaves it, like errorSpatial
+calcStatusSpatial?: ISpatialMap<ICalcGrid.CalcStatus>, // the pending index: a written cell leaves it now, not at the next pass's end
+blockedSpillSpatial?: ISpatialMap<SpillEntry>): IRange.Coords | null;
 /**
  * Creates a map from tuples
  *
@@ -120,6 +123,12 @@ export interface PrecedentFormulaUpdates {
      * evaluate, but until then no precedent leads the dirty sweep to them.
      */
     dynamicDependents?: ISpatialMap.Entry<FormulaSpatialValue>[];
+    /**
+     * {@link movePrecedents}: the replacement formulas a cut changed only by moving an EDGE of their
+     * reference. They still read only the cut's own sheet, and a contracted one may no longer reach
+     * anything the cut touched, so the caller marks them dirty itself.
+     */
+    edged?: ISpatialMap.Entry<FormulaSpatialValue>[];
 }
 /**
  * Splits precedents at the insertion boundary.
@@ -154,23 +163,7 @@ export declare function splitPrecedentsInsert(precedents: ISpatialMap3D<Preceden
  * INVARIANT: All resulting formula entries must have logically identical formulas.
  */
 export declare function splitPrecedentsDelete(precedents: ISpatialMap3D<PrecedentSpatialValue>, coords: IRange.Coords): PrecedentFormulaUpdates | null;
-/**
- * Splits precedents at the cut boundary to isolate the moveable sub-block.
- *
- * @remarks
- * For move operations: isolates the sub-block of formula cells whose natural bounds
- * are fully enclosed by the move coords. The inner piece will be moved; outer pieces stay.
- *
- * Natural bounds = the precedent size for a single formula cell.
- * A formula cell at block-relative offset `r` has natural row range:
- *   `[P.rowStart + r, P.rowStart + r + nh - 1]`
- * where `nh = (P.rowEnd - P.rowStart) - (F.rowEnd - F.rowStart) + 1`.
- *
- * Excel rule: only move if the natural bounds fit entirely within the cut rect.
- *
- * INVARIANT: All resulting formula entries must have logically identical formulas.
- */
-export declare function splitPrecedentsMove(precedents: ISpatialMap3D<PrecedentSpatialValue>, coords: IRange.Coords): PrecedentFormulaUpdates | null;
+export declare function splitPrecedentsMove(precedents: ISpatialMap3D<PrecedentSpatialValue>, from: IRange.Coords, to: IRange.Coords): PrecedentFormulaUpdates | null;
 /**
  * This shifts precedents that cross an intersection boundary.
  *
@@ -192,13 +185,18 @@ export declare function shiftPrecedents(getPrecedentSpatial: () => ISpatialMap3D
  * whose precedent points INTO the moved region.
  *
  * @remarks
- * Pre-condition: splitPrecedentsCut has already been applied so no precedent straddles the boundary.
- * After split, each precedent is either fully inside or fully outside the `from` region.
+ * Pre-condition: {@link splitPrecedentsMove} has already been applied so no precedent straddles the
+ * boundary. After split, each precedent is either fully inside or fully outside the `from` region,
+ * or takes one EDGE cut the same way in every cell.
  *
  * For a move (cut+paste), the data moves rigidly from `from` to `to`.
- * Both edges of the precedent shift by the same delta — a uniform translation.
+ * Both edges of an enclosed precedent shift by the same delta — a uniform translation. A precedent
+ * whose edge the cut took has that edge moved first ({@link edgeMoveReferenceAxis}); those formulas
+ * are also answered in `edged` when nothing of theirs translated, because they still read only
+ * the cut's own sheet.
  *
- * Formulas inside the move range are skipped (they move with their data).
+ * Formulas inside the move range are skipped (they move with their data), and so are those inside
+ * `to`, which are the moved ones.
  */
 export declare function movePrecedents(precedentSpatial: ISpatialMap3D<PrecedentSpatialValue>, getDynamicPrecedents: () => Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>, from: IRange.Coords, to: IRange.Coords): PrecedentFormulaUpdates | null;
 /**

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

@@ -11,28 +11,6 @@ import { FormulaEntry } from './FormulaEntry';
 import { ContentfulSpatialValue, SpillEntry, CircularEntry } from '../spatial';
 import { NamedReference, NamedNodeInfo } from '../Types';
 import { ICalculation } from '../ICalculation';
-/**
- * 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.
@@ -74,28 +52,7 @@ export interface ICalcGrid {
      * This allows for incremental dirty updates.
      */
     markDirtyRegions(coords: IRange.Coords[]): void;
-    /**
-     * 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.
-     */
     getStateId(): string;
-    /**
-     * The values as the model holds them: the literals it entered and the answers the engine
-     * vended, one map (DESIGN-CALC-SERVICE §13.24).
-     *
-     * @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.
-     */
     getValues(transaction?: ITransaction | null): ISparseGrid<Scalar>;
     /**
      * The contentful index: which cells hold a value, summarized per run. Derived from
@@ -110,13 +67,18 @@ export interface ICalcGrid {
      * made; the current record when omitted.
      */
     getSpills(transaction?: ITransaction | null): ISpatialMap<SpillEntry>;
+    /**
+     * The blocked spills, each at the extent it would take, for showing that region. A blocked spill
+     * occupies none of it: its anchor holds the `#SPILL!`, so nothing that reads cells needs this.
+     */
+    getBlockedSpills(): ISpatialQuery<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>;
+    getCalcStatus(transaction?: ITransaction | null): ISpatialMap<ICalcGrid.CalcStatus>;
     /**
      * Engine FAILURES by cell (a formula that could not be evaluated), as a message. Not error
      * VALUES - those are {@link getErrorValues}.
@@ -124,11 +86,6 @@ export interface ICalcGrid {
      * made; the current record when omitted.
      */
     getCalcErrors(transaction?: ITransaction | null): ISpatialMap<string>;
-    /**
-     * 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.
@@ -351,24 +308,6 @@ export interface ICalcGrid {
      * @param options See {@link ICalcGrid.RequestOptions}.
      */
     setFiltered(filtered: boolean, options?: ICalcGrid.RequestOptions): void;
-    /**
-     * Opens the grid from a seed: a statement of its whole content (DESIGN-CALC-SERVICE §6).
-     *
-     * @param json The content, the same record a save writes.
-     * @param options {@link ICalcGrid.SeedOptions}
-     *
-     * @remarks
-     * 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.
-     *
-     * 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}).
-     */
     seed(json: ICalcGrid.JSON, options?: ICalcGrid.SeedOptions): Promise<ICalcGrid.Results>;
     /**
      * Returns a JSON representation of the calcGrid.
@@ -405,12 +344,7 @@ 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' | 'getEntireCoords' | 'getFormulaAt' | 'getFormulas' | 'getValues' | 'getContentful' | 'getSpills' | 'getPending' | 'getCalcErrors' | 'getCirculars' | 'getErrorValues' | 'getValuesEpoch' | 'getVolatileRegions' | 'getRangeStats'> & {
+    type Backend = Omit<ICalcGrid, 'getStateId' | 'getEntireCoords' | 'getFormulaAt' | 'getFormulas' | 'getValues' | 'getContentful' | 'getSpills' | 'getBlockedSpills' | 'getCalcStatus' | 'getCalcErrors' | 'getCirculars' | 'getErrorValues' | 'getValuesEpoch' | '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. */
@@ -422,12 +356,6 @@ export declare namespace ICalcGrid {
          * last set; see `CalcGridBackend.getDemanded`. Evaluated by the next pass.
          */
         demand(rects: readonly IRange.Coords[]): 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
@@ -443,8 +371,11 @@ export declare namespace ICalcGrid {
         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;
+        /**
+         * Re-derive the formulas that mention this grid's name once the body is in: a defined name's.
+         * `'load'` when the body is the one the file holds, so a formula loaded with it keeps its value.
+         */
+        recompile?: boolean | 'load';
         /**
          * Applied ahead of the other requests a start holds: a defined name must be bound before any
          * formula that mentions it is examined.
@@ -522,7 +453,8 @@ export declare namespace ICalcGrid {
         valueRemoves?: IRange.Coords[];
         /**
          * Contains any spills that were inserted. The value is the
-         * {@link ITypes.FormulaArrayKind | kind} of the block that produced it.
+         * {@link ITypes.FormulaArrayKind | kind} of the block that produced it. An `error` is at the
+         * extent it would take, as it is in {@link spillRemoves}.
          */
         spillInserts?: ISpatialMap.Entry<ITypes.FormulaArrayKind>[];
         /**
@@ -556,7 +488,7 @@ export declare namespace ICalcGrid {
          * @remarks
          * These are guaranteed to not overlap.
          */
-        pendingUpdates?: ISpatialMap.Entry<boolean>[];
+        calcStatusUpdates?: ISpatialMap.Entry<ICalcGrid.CalcStatus | false>[];
         /**
          * Cells that entered or left a reference cycle (or the set downstream of one). A `null`
          * value is a removal.
@@ -565,18 +497,6 @@ 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.
@@ -609,6 +529,16 @@ export declare namespace ICalcGrid {
         /** For a paged region, the tiles this pass evaluated. */
         readonly evaluated?: readonly IRange.Coords[];
     }
+    /**
+     * Why a cell is in the calc-status index: its own function asked for a result that has not
+     * arrived (`Working`), or it was calculated from such a value and is calculated again when it
+     * arrives (`Waiting`). A removal travels as `false` in a delta.
+     */
+    const CalcStatus: {
+        readonly Working: 1;
+        readonly Waiting: 2;
+    };
+    type CalcStatus = typeof CalcStatus[keyof typeof CalcStatus];
     /**
      * Returns from `ICalcGrid.beginUpdates()`.
      *
@@ -620,28 +550,17 @@ export declare namespace ICalcGrid {
         values: ISparseGrid<Scalar>;
         spillSpatial: ISpatialMap<SpillEntry>;
         errorSpatial: ISpatialMap<string>;
-        pendingSpatial: ISpatialMap<boolean>;
+        calcStatusSpatial: ISpatialMap<ICalcGrid.CalcStatus>;
         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;
-        notifyPending: ISpatialMap<boolean>;
+        notifyCalcStatus: ISpatialMap<ICalcGrid.CalcStatus | false>;
         notifyCircular: ISpatialMap<CircularEntry | false>;
-        pendingConflating: ISpatialMap.IConflatingEntries<boolean> | null;
+        calcStatusConflating: ISpatialMap.IConflatingEntries<ICalcGrid.CalcStatus | false> | null;
         circularConflating: ISpatialMap.IConflatingEntries<CircularEntry | false> | null;
         errorRemovesConflating: ISpatialMap.IConflatingEntries<null> | null;
         errorInsertsConflating: ISpatialMap.IConflatingEntries<string> | null;