@sheetxl/sdk 0.8.0-beta.10 → 0.8.0-beta.12

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

@@ -20,7 +20,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 +29,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
@@ -61,6 +61,10 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
     readonly _shadowOf: string | null;
     /** @see CalcGridBackend.ConstructorOptions.arrayFirstCell */
     readonly _arrayFirstCell: boolean;
+    /** @see CalcGridBackend.ConstructorOptions.paged */
+    readonly _paged: boolean;
+    /** The tiles of a paged body's blank region its owner reads now: see {@link getDemanded}. */
+    protected _demanded: readonly IRange.Coords[];
     _container: IContextContainer;
     _context: IFormulaContext;
     protected _isProcessingJSON: boolean;
@@ -73,7 +77,7 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
     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
+     * place the response half of the boundary is crossed on the way out (DESIGN-CALC-SERVICE §11); every site
      * that pushes calls this rather than `_options.onCalculated`.
      */
     protected _onCalculated: (response: CalcResponse) => void;
@@ -198,6 +202,18 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
     getShadowOf(): string | null;
     /** @inheritdoc ICalcGrid.isArrayFirstCell */
     isArrayFirstCell(): boolean;
+    /** Whether this grid's body may evaluate its blank region a tile at a time: see `ConstructorOptions.paged`. */
+    isPaged(): boolean;
+    /**
+     * The tiles of the body's blank region its owner reads now, in this grid's coordinates. A paged
+     * body evaluates its blank region only inside them; empty for a grid that is not paged.
+     */
+    getDemanded(): readonly IRange.Coords[];
+    /**
+     * Take the owner's tiles. A tile that is new or released is dirtied: the next pass evaluates a
+     * new one and clears what a released one holds.
+     */
+    protected _demandNow(rects: readonly IRange.Coords[]): void;
     /** {@inheritDoc ICalcGrid.getEntireCoords} */
     getEntireCoords(): IRange.Coords;
     /**
@@ -242,6 +258,12 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
      * the model's question.
      */
     getDirectDependentsAt(coords: IRange.Coords): IRange.Coords[];
+    /**
+     * Pushes `dep` and the landed output of every spill anchored in it. An anchor rewrites its whole
+     * spill when it re-evaluates, and this is the hop that lets a transitive walk reach what reads the
+     * spill's far end, not just its anchor. A blocked spill landed on its anchor alone, so adds nothing.
+     */
+    private _pushWithSpills;
     /**
      * The direct precedents of a range: one hop upstream, as of the last calculation.
      *
@@ -285,29 +307,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. */
@@ -316,6 +315,7 @@ 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. */
@@ -459,6 +459,14 @@ export declare namespace CalcGridBackend {
          * conditional-format body. See {@link ICalcGrid.isArrayFirstCell}.
          */
         arrayFirstCell?: boolean;
+        /**
+         * `true` when the body's blank region may be evaluated a tile at a time: once the body's
+         * answer there depends on the position (`ISODD(ROW())`), only the tiles its owner asks for
+         * ({@link CalcGridBackend.getDemanded}) are evaluated, and the rest of the region holds
+         * nothing. For an owner that reads a window of the body at a time - a conditional format,
+         * which paints what is on screen.
+         */
+        paged?: boolean;
     }
 }
 /** A grid's per-grid maps, as one snapshot of the engine's history holds them. */
@@ -467,7 +475,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

@@ -67,6 +67,8 @@ export declare class CalcGridProxy implements ICalcGrid.Backend {
     calculate(full?: boolean): Promise<ICalculation.Status>;
     /** {@inheritDoc ICalcGrid.Backend.requestPass} */
     requestPass(): void;
+    /** {@inheritDoc ICalcGrid.Backend.demand} */
+    demand(rects: readonly IRange.Coords[]): void;
     /** {@inheritDoc ICalcGrid.markDirtyRegions} */
     markDirtyRegions(coords: IRange.Coords[]): void;
     /** {@inheritDoc ICalcGrid.delete} */
@@ -94,8 +96,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;
@@ -43,7 +44,14 @@ export declare function errorValueEntriesOf(grid: ISparseGrid<Scalar>): ISpatial
  * region leaves the index and its runs are re-read for errors.
  */
 export declare function indexWrittenRuns(errorSpatial: ISpatialMap<string>, grid: ISparseGrid<Scalar>, bounds: IRange.Coords): void;
-/** Removes a cleared region from the error index (a spill's old extent, a deleted range). */
+/**
+ * Removes a cleared region from the error index (a spill's old extent, a deleted range).
+ *
+ * @remarks
+ * Exactly the region: the index joins like errors side by side into one entry, so an entry may
+ * run past `coords`, and only its part inside them goes. (`ISpatialMap.delete` drops every entry
+ * it touches whole, which would forget the errors beside a one-cell write.)
+ */
 export declare function clearErrorIndex(errorSpatial: ISpatialMap<string>, coords: IRange.Coords): void;
 /**
  * Updates contentful and invalidates spills.
@@ -51,9 +59,10 @@ 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>): IRange.Coords | null;
 /**
  * Creates a map from tuples
  *

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

@@ -1,7 +1,6 @@
-import { IRange, IFormulaContext, Scalar } from '@sheetxl/primitives';
+import { IRange, IRuntime, Scalar } from '@sheetxl/primitives';
 import { ISparseGrid } from '../../collections';
 import { ITransaction } from '../../transaction';
-import { IContextContainer } from '../state';
 import { IFormulaBlockView } from '../formula';
 import { ICalcGrid } from './ICalcGrid';
 import { CalcGrid } from './CalcGrid';
@@ -22,8 +21,7 @@ export declare class FormulaHost {
     protected readonly _id: string;
     protected readonly _grid: CalcGrid;
     protected readonly _transactions: ITransaction.IStore | null;
-    protected readonly _container: IContextContainer;
-    protected readonly _context: IFormulaContext;
+    protected readonly _runtime: IRuntime;
     /**
      * The body as this side knows it: what was last handed to the grid, refined by what the grid
      * answered. Held here so that the owner of a formula never has to read it back out of the grid -
@@ -42,9 +40,21 @@ export declare class FormulaHost {
     } | null;
     /** The last body written as authored has not been answered: the grid's entry predates it. */
     protected _bodyPending: boolean;
+    /**
+     * A paged body's tiles the owner has asked for, by index from the body's top row, oldest ask
+     * first: what is sent as the demand. Capped (see {@link request}); the oldest go first.
+     */
+    protected _wanted: Map<number, true>;
+    /** The tiles the last pass evaluated, by index: see {@link ICalcGrid.BlankRegion.evaluated}. */
+    protected _evaluated: Set<number>;
+    /** A demand is waiting to be sent at the end of the current flush. */
+    protected _demandQueued: boolean;
+    /** A demand was sent since the last pass's results. */
+    protected _demandSent: boolean;
     protected readonly _onDispose: (() => void) | undefined;
     protected readonly _onCalculated: ((results: ICalcGrid.Results) => void) | undefined;
     protected readonly _onResync: (() => void) | undefined;
+    protected readonly _waitUntil: ((work: Promise<void>) => void) | undefined;
     constructor(options: FormulaHost.ConstructorOptions);
     /** The grid's id. */
     getId(): string;
@@ -86,12 +96,39 @@ export declare class FormulaHost {
      * rewrite a structural change made since - replaces it when it arrives.
      */
     getBody(): FormulaHost.Body | null;
+    /**
+     * Whether a body is written: answered, or sent and not yet answered. `false` when nothing has
+     * been written, and again after a restore to a version from before the write (see {@link _resync}).
+     */
+    hasBody(): boolean;
     /**
      * What the engine pushed after a pass over the body: a rewrite nobody asked for (a structural
      * change on the sheet the body reads), and the blank region.
      * @internal
      */
     _onComplete(results: ICalcGrid.Results): void;
+    /**
+     * Whether the body's value at a cell is its answer, asking for it when it is not.
+     *
+     * @remarks
+     * A body whose blank region is paged (`CalcGridBackend.ConstructorOptions.paged`) evaluates
+     * that region only inside the tiles - 256 rows across the body - its owner reads.
+     * A cell elsewhere holds nothing yet: this asks for its tile, once per flush however many cells
+     * ask, and the pass that evaluates it delivers as any pass does. Every other cell, and every
+     * cell of a body that is not paged, already holds its answer.
+     *
+     * The owner reads a window at a time (what is on screen), so the tiles asked for most recently
+     * are the ones kept: past 64 tiles the oldest is released, and what it held is cleared
+     * by the next pass.
+     *
+     * @returns `true` when the value at the cell is the body's answer there.
+     */
+    request(row: number, column: number): boolean;
+    /** The index of the tile holding `row`, counted from the body's top row. */
+    protected _tileOf(row: number, extent: IRange.Coords): number;
+    /** Sends the wanted tiles once the current flush is over, and asks for the pass. */
+    protected _queueDemand(): void;
+    protected _sendDemand(extent: IRange.Coords): void;
     /**
      * Take what the grid reports about the body: the answer to a write, or a rewrite nobody asked
      * for (a structural change on the sheet the body reads).
@@ -157,6 +194,12 @@ export declare class FormulaHost {
     getBlock(): IFormulaBlockView | null;
     /** The model's grid the body lives in. @internal */
     _getCalcGrid(): CalcGrid;
+    /**
+     * Whether the grid holds state at the current commit: `false` after a restore to a version from
+     * before the grid was made, when nothing written here lands anywhere (see `CalcGrid._revive`).
+     * @internal
+     */
+    _isLive(): boolean;
     /**
      * The body as the model's grid holds it, answered or not: its text is the engine's once the
      * engine has answered, and the text as written until then. `null` when nothing is written.
@@ -217,14 +260,16 @@ export declare namespace FormulaHost {
         grid: CalcGrid;
         /** The store the grid is versioned in: a write made outside an operation amends its current commit. */
         transactions?: ITransaction.IStore | null;
-        container: IContextContainer;
-        context: IFormulaContext;
+        /** The runtime a range over the body's values reads with. */
+        runtime: IRuntime;
         /** Called when the host is disposed, for whoever keeps track of live hosts. */
         onDispose?: () => void;
         /** Told after every pass that wrote the grid. */
         onCalculated?: (results: ICalcGrid.Results) => void;
         /** Told after a restore or revert has replaced the body under the host (see {@link FormulaHost._resync}). */
         onResync?: () => void;
+        /** Counts work the host starts for its owner as calculation in flight: see `ICalculation.waitUntil`. */
+        waitUntil?: (work: Promise<void>) => void;
     }
     /** A body as its host holds it. */
     interface Body {

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

@@ -116,7 +116,7 @@ export interface ICalcGrid {
      * @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}.
@@ -141,6 +141,15 @@ export interface ICalcGrid {
      * collapses into a plain read once the executor emits those deltas.
      */
     getErrorValues(): ISpatialMap<boolean>;
+    /**
+     * A counter that moves whenever the values change in place, where {@link getValues} keeps its
+     * identity (an engine's answers landing, a load).
+     *
+     * @remarks
+     * With the identity of {@link getValues}, the key a view derived from the values is cached
+     * against: equal identity and equal epoch mean the values have not moved.
+     */
+    getValuesEpoch(): number;
     /**
      * 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
@@ -287,8 +296,10 @@ export interface ICalcGrid {
      */
     setReferenceModeAt(row: number, column: number, index: number, side?: ICalculation.ReferenceSide, mode?: number): Promise<IFormulaBlockView | null>;
     /**
-     * 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.
+     * Whether the formula at the cell is volatile: its text, closed over the names it mentions,
+     * the computed reads its last evaluation registered, or the node a pass registered volatile —
+     * a question answered in order behind the writes sent before it. On a grid at a synthetic
+     * anchor (a name's), which no pass evaluates, the text is all there is.
      *
      * @param row The row of the cell to evaluate.
      * @param column The column of the cell to evaluate.
@@ -399,7 +410,7 @@ export declare namespace ICalcGrid {
      * 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' | 'getVolatileRegions' | 'getRangeStats'> & {
+    type Backend = Omit<ICalcGrid, 'getStateId' | 'getEntireCoords' | 'getFormulaAt' | 'getFormulas' | 'getValues' | 'getContentful' | 'getSpills' | '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. */
@@ -407,11 +418,10 @@ export declare namespace ICalcGrid {
         /** 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.
+         * The tiles of a paged body's blank region the owner reads now - all of them, replacing the
+         * last set; see `CalcGridBackend.getDemanded`. Evaluated by the next pass.
          */
-        getNameGraph(kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
+        demand(rects: readonly IRange.Coords[]): void;
     };
     /**
      * A body written as it was authored, for a grid that holds one (a name's, a watch's): the engine
@@ -540,7 +550,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.
@@ -575,15 +585,34 @@ export declare namespace ICalcGrid {
     /**
      * The cells of a body that a pass shares one answer for rather than writing, and that answer:
      * what every such cell reads as.
+     *
+     * @remarks
+     * A PAGED region shares nothing: the body's answer there depends on the position, and only the
+     * tiles its owner asked for are evaluated ({@link evaluated}). Every other cell of
+     * {@link rects} holds nothing and has no answer yet.
      */
     interface BlankRegion {
-        /** The shared answer. */
+        /** The shared answer; `undefined` for a paged region. */
         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;
+        /** The region is evaluated a tile at a time rather than shared. */
+        readonly paged?: boolean;
+        /** 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()`.
      *
@@ -595,7 +624,7 @@ 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;
@@ -614,9 +643,9 @@ export declare namespace ICalcGrid {
         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;
@@ -665,10 +694,14 @@ export declare namespace ICalcGrid {
          */
         range: IRange.Coords | string;
     }
-    interface ISnapshot extends IHistory.ISnapshot<ICalcGrid.SnapshotDestination, ICalcGrid.Backend, IRange.Coords, any, ICalcGrid.Results> {
+    interface ISnapshot extends IHistory.ISnapshot<ICalcGrid.SnapshotDestination, ICalcGrid.Backend, IRange.Coords, any, Promise<ICalcGrid.Results>> {
         /**
          * Copies the snapshot's formulas to the destination grid.
          *
+         * @remarks
+         * The engine answers when it has the blocks; the destination holds the formulas pending in
+         * the meantime, so a paste starts this and does not wait for it.
+         *
          * @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`.
@@ -828,7 +861,7 @@ export declare namespace ICalcGrid {
          * {@link ITypes.FormulaArrayKind | kinds} of array formula it is.
          *
          * @remarks
-         * See {@link ISheet.JSON.formulaArray} for what does and does not earn an entry.
+         * See {@link IWorksheet.JSON.formulaArray} for what does and does not earn an entry.
          */
         formulaArray?: IRange.JSONReferenceTuple<ITypes.FormulaArrayKind>[];
         /**

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

@@ -13,7 +13,7 @@ import { ICalcGrid } from './ICalcGrid';
  * @remarks
  * Not part of {@link ICalcGrid}: a caller sees the verbs and their promises. This is what the
  * in-process channel holds in place of a worker port's queue, and what the clone boundary audits
- * (plan step 6): a held call carries what the verb's arguments carry, which is what a proxy
+ * (DESIGN-CALC-SERVICE §11): a held call carries what the verb's arguments carry, which is what a proxy
  * would post.
  *
  * @internal Deliberately not exported from the barrel.
@@ -107,6 +107,14 @@ export type CalcRequest =
     type: 'markDirty';
     coords: readonly IRange.Coords[];
 }
+/**
+ * The tiles of a paged body's blank region its owner reads now - all of them, replacing the
+ * last set. See `CalcGridBackend.ConstructorOptions.paged`.
+ */
+ | {
+    type: 'demand';
+    rects: readonly IRange.Coords[];
+}
 /**
  * The model restored to `options.commitId`: the engine restores its own history there and re-vends
  * what changed. Only a `Running` engine acts on it - see `Calculation._sendRequestNow`.
@@ -158,15 +166,13 @@ export type CalcRequest =
 }
 /**
  * The graph around cells of this grid, answered in the response (`ICalcGrid.GraphNeighbors`,
- * cells in calc currency). A question. `asName` walks the defined name this grid holds the body
- * of instead: its own precedents or dependents, cells and names.
+ * cells in calc currency). A question.
  */
  | {
     type: 'graph';
     kind: 'precedents' | 'dependents';
     direct: boolean;
-    coords?: IRange.Coords;
-    asName?: boolean;
+    coords: IRange.Coords;
 }
 /** Whether the formula at a cell is volatile, answered in the response. A question. */
  | {
@@ -188,7 +194,7 @@ export type CalcRequest =
  */
  | {
     type: 'sheets';
-    sheets: readonly (readonly [id: string, name: string | null])[];
+    sheets: readonly (readonly [id: string, name: string | null, gridless?: boolean])[];
     options?: ICalcGrid.RequestOptions;
 }
 /**
@@ -207,6 +213,18 @@ export type CalcRequest =
     changes: readonly (readonly [id: string, name: NameSymbols | null])[];
     options?: ICalcGrid.RequestOptions;
 }
+/**
+ * The graph around a defined name - its precedents or dependents, cells in calc currency and
+ * names - answered in the response (`ICalcGrid.GraphNeighbors`). A question of the service, not
+ * of the name's grid: its readers are found by its id, so a name that has not compiled is asked
+ * without making it a grid.
+ */
+ | {
+    type: 'nameGraph';
+    nameId: string;
+    kind: 'precedents' | 'dependents';
+    direct: boolean;
+}
 /**
  * A nested savepoint of the model rolled back inside an operation that goes on: what the requests
  * made under it did goes with it. After them in the channel, so it undoes exactly those.
@@ -236,6 +254,8 @@ export interface CalcGridSpec {
     unanchored?: boolean;
     /** See `CalcGridBackend.ConstructorOptions.arrayFirstCell`. */
     arrayFirstCell?: boolean;
+    /** See `CalcGridBackend.ConstructorOptions.paged`. */
+    paged?: boolean;
     /** The grid's size, fixed: a name's. A sheet's is its seed's. */
     entireCoords?: IRange.Coords;
     /** The grid whose size this one has, whatever it is then: a body on a sheet. */
@@ -277,6 +297,8 @@ export type GridRequest = Exclude<CalcRequest, {
     type: 'tables';
 } | {
     type: 'names';
+} | {
+    type: 'nameGraph';
 } | {
     type: 'rollback';
 } | {

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

@@ -0,0 +1,21 @@
+import { Scalar } from '@sheetxl/primitives';
+import { IListLike, IReadableList } from '../../collections';
+/**
+ * The run a result is stored as in a grid of CELL values: the engine's value grid, and the range
+ * an `evaluate()` call answers with.
+ *
+ * @remarks
+ * A cell holds a scalar: a number, text, a boolean, a blank, an error or rich data. Anything else
+ * an evaluation can produce, such as a function value (`=HSTACK(SUM,A1:A2)`, a `LAMBDA` left
+ * unconsumed), is calculation-private, and the cell's verdict on it is `#CALC!`, the one a
+ * top-level result gets (`FormulaBlock.finalizeValue`). Applying it where the run is MADE means
+ * every reader of the grid (the sheet, a spill, a saved file, the renderer) sees `#CALC!` without
+ * knowing what it stood for, and nothing private leaves the engine.
+ *
+ * A typed run never holds an object and is wrapped as it is; a repeating run is looked at once per
+ * period; a run made of other runs (a referenced column: its cells, then a blank stretch to the
+ * sheet's end) is looked at per leaf by the same rules; any other run is classified once, which is
+ * what storing it typed costs anyway.
+ */
+export declare const createCellValueRun: (values: IListLike<Scalar> | Scalar[]) => IReadableList<Scalar>;
+//# sourceMappingURL=_CellValueRun.d.ts.map

package/types/src/calculation/spatial/FormulaSpatialValue.d.ts

@@ -89,6 +89,11 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
      * Deliberately NOT "is a named body". Anything holding a formula at a synthetic anchor wants the
      * same treatment, and the shift code should not have to know what a name is.
      *
+     * A calculation pass never evaluates such a block: its anchor is no cell, so there is nothing
+     * to write an answer to, and whatever reads the body runs it inline at its own position. It is
+     * evaluated on demand only (`ICalcGrid.evaluateAt`), and `isVolatileAt` answers for it from the
+     * formula text alone, there being nothing a pass registered (`CalcGridBackend._isVolatileNow`).
+     *
      * Required at construction rather than defaulted: the block is immutable and re-minted on every
      * reference rewrite, so an unthreaded copy would silently revert to `false` on the first
      * `setReferenceAt` — which is exactly what a shift performs.
@@ -175,11 +180,20 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
     setBlankShared(blank: readonly IRange.Coords[] | null): void;
     /**
      * The pass refused to share the representative's answer for a reason the text hides — a
-     * position read, a draw, a computed reference (`CalcScope.perCellRead`). Those are facts of the
+     * position read the formula's variants cannot rule out, a draw, a computed reference
+     * (`CalcScope.perCellRead`, `CalcScope.positionRead`). Those are facts of the
      * formula, so the block keeps per-cell evaluation for good rather than paying one wasted
      * representative evaluation and a second plan iteration every pass.
      */
     blankRefused: boolean;
+    /**
+     * The representative's answer depends on the position and the block's grid is paged
+     * (`CalcGridBackend.ConstructorOptions.paged`): the blank region is not shared but evaluated
+     * inside the tiles the grid's owner asks for ({@link getDemandedBlank}), and holds nothing
+     * elsewhere. A fact of the formula like {@link blankRefused}, so it is kept; the block stays
+     * sparse and has no representative.
+     */
+    blankPaged: boolean;
     /**
      * The cycle whose representative could not stand for the region for a reason that may not
      * recur — a range result, a cycle role, a promise: the block is evaluated per cell for the rest
@@ -292,6 +306,11 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
      * ahead of this — so the region only ever answers for cells nothing was written to.
      */
     getBlankRegion(): FormulaSpatialValue.BlankRegion | null;
+    /**
+     * The cells of the last collection's blank region inside the tiles the grid's owner reads now
+     * (`CalcGridBackend.getDemanded`): what a paged block evaluates beyond its touched cells.
+     */
+    getDemandedBlank(): IRange.Coords[];
     /**
      * What a cell of `coords` that the grid does not store reads as: the blank region's shared
      * value when a region is shared and `coords` lie inside the block, `null` otherwise.
@@ -409,10 +428,16 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
     getReferencedSymbolIds(): string[];
     /** {@inheritDoc IFormulaBlock.hasTotals} */
     hasTotals(): boolean;
+    /** {@inheritDoc IFormulaBlock.hasDataTable} */
+    hasDataTable(): boolean;
+    /** {@inheritDoc IFormulaBlock.hasVolatile} */
+    hasVolatile(): boolean;
     /** {@inheritDoc IFormulaBlock.isBlankCacheable} */
     isBlankCacheable(arrayMode?: boolean): boolean;
     /** {@inheritDoc IFormulaBlock.demandFirstCell} */
     demandFirstCell(): void;
+    /** {@inheritDoc IFormulaBlock.getPositionVariants} */
+    getPositionVariants(): IFormulaBlock[] | null;
     /** @inheritdoc IFormulaBlock.isReferenceOnly */
     isReferenceOnly(): boolean;
     /** {@inheritDoc IFormulaBlock.isEquals} */
@@ -439,10 +464,12 @@ export declare namespace FormulaSpatialValue {
     }
     /** See {@link FormulaSpatialValue.getBlankRegion}. */
     interface BlankRegion {
-        /** The representative's finalized scalar. */
+        /** The representative's finalized scalar; `undefined` for a paged region. */
         readonly value: Scalar | undefined;
         /** The blank rectangles, in the block's own grid coordinates. */
         readonly rects: readonly IRange.Coords[];
+        /** See {@link FormulaSpatialValue.blankPaged}. */
+        readonly paged?: boolean;
     }
 }
 //# sourceMappingURL=FormulaSpatialValue.d.ts.map