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

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

@@ -1,12 +1,17 @@
-import { FormulaError, IRange } from '@sheetxl/primitives';
+import { FormulaError, IRange, Scalar } from '@sheetxl/primitives';
 import { ISpatialMap } from '../../collections/ISpatialMap';
-import { IFormulaBlock } from '../formula';
+import { SparseGrid } from '../../collections/SparseGrid';
+import { IFormulaBlock, FormulaRecord } from '../formula';
 import { CalcNode, IContextContainer } from '../state';
-import { ReferenceCoords, SetReferenceOptions } from '../Types';
+import { ReferenceCoords, SetReferenceOptions, PrecedentTemplate } from '../Types';
 import { ICalculation } from '../ICalculation';
+import { TouchedWindows } from './TouchedWindows';
 /**
- * This extends IFormulaBlock with spatial behavior.
+ * Carries each node's fixed (array-entered) extent from one block's nodes onto another's of the
+ * same shape, translated by the given offsets. Used wherever a block's nodes are re-minted fresh
+ * rather than cloned - a copy, or a re-image of the same block.
  */
+export declare function copyFixedRefs(from: FormulaSpatialValue, to: FormulaSpatialValue, deltaCol?: number, deltaRow?: number): void;
 export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.IUpdatableValue<FormulaSpatialValue> {
     protected _container: IContextContainer;
     gridId: string | null;
@@ -23,7 +28,39 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
      */
     ref: IRange.Coords;
     formula: IFormulaBlock | null;
-    calcs: CalcNode[][];
+    /**
+     * The block's nodes, DENSE - one per cell - for a block the pass evaluates cell by cell; `null`
+     * for a block that shares one answer over its blank region (PLAN-WATCHES-BLANK-AWARE §4c), which
+     * keeps its nodes in {@link _nodes} instead, and `null` while nothing has touched the block.
+     * Never indexed from outside: {@link nodeAt}, {@link nodeAtOrNull}, {@link forEachNodeIn},
+     * {@link mintNodesIn} and {@link forEachNode} are the reads, and they are the same calls for
+     * either shape.
+     *
+     * @remarks
+     * Nodes are runtime state, not the formula: they exist from the first touch ({@link nodeAt},
+     * {@link mintNodesIn}) and are dropped when the block leaves its map ({@link release}). A block
+     * that nothing has touched, or that was released, holds no node for any cell, which the executor
+     * reads as "never collected: a value". A superseded block is still held by every earlier
+     * commit's map, so what it keeps is what the history keeps; a restore mints again on demand.
+     */
+    calcs: CalcNode[][] | null;
+    /**
+     * A gated block's nodes, keyed by cell. **A node exists only where its cell has been touched**
+     * by a collection, is the representative, or is the anchor: a whole-column body over a few
+     * hundred data cells holds a few hundred nodes, and a whole-sheet one is possible at all. A
+     * sparse set of values that is looked up by cell, walked by rectangle, split, merged and
+     * shifted is what `SparseGrid` is; column-stored like the values grid, so a formula filled down
+     * a data column is one run. `null` until the first touch, as {@link calcs} is.
+     */
+    protected _nodes: SparseGrid<CalcNode> | null;
+    /** Whether the nodes are held sparsely - a fact of the formula and the block's size, fixed at construction; {@link densify} turns it off. */
+    protected _sparse: boolean;
+    /**
+     * The top-left node once it exists. It outlives a {@link release}: array entry is recorded on
+     * its `ext` (`fixedRef`), and a read of it alone ({@link getAnchorNode}) must not mint a dense
+     * block's every node. Placed back into whichever store is minted next.
+     */
+    protected _anchor: CalcNode | null;
     /**
      * The precedent entries that were actually registered for this block.
      *
@@ -57,10 +94,255 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
      * `setReferenceAt` — which is exactly what a shift performs.
      */
     readonly unanchored: boolean;
-    constructor(coords: IRange.Coords, gridId: string | null, formula: IFormulaBlock | null, container: IContextContainer, unanchored: boolean, calcs?: CalcNode[][]);
+    /**
+     * `true` when every cell of this block is its own 1x1 array-entered formula — the grid's
+     * {@link ICalcGrid.isArrayFirstCell}, read once at construction.
+     *
+     * @remarks
+     * Excel's rule for a conditional-format formula (DESIGN-LIFT-AND-DEMAND §2): the whole tree is
+     * array mode (`CalculationContext.isImplicitIntersect`), the tree is evaluated under a first-cell
+     * demand so a lift builds only `[0,0]` ({@link IFormulaBlock.demandFirstCell}), and the commit
+     * keeps `[0,0]` of a result that is still a range. Every cell therefore stores a scalar, which
+     * is what lets the blank region share one answer. No extent is recorded per node: the block is
+     * a property of the grid, and a sparse block stays sparse.
+     */
+    readonly arrayFirstCell: boolean;
+    /**
+     * How many static precedent edges each of this block's cells has — the same count at every
+     * cell, since they all run the one formula. What sizes a node's run of input slots.
+     */
+    paramLength: number;
+    /**
+     * The block's edges in relative form, when they are the same rects at every cell's own offset
+     * ({@link IFormulaBlock.getPrecedentTemplate}); `null` when they are not. Under a template the
+     * nodes store no edge list at all — {@link getPrecedentsAt} materializes one on demand.
+     */
+    protected _template: PrecedentTemplate | null;
+    /**
+     * {@link getPrecedentsAt}'s buffer, and the cell it currently holds. One per block, mutated in
+     * place, exactly like the executor's `_ReuseSearch*` coords and for the same reason: this is
+     * asked once per cell in each of the hot phases, and a fresh array there is the allocation the
+     * template exists to remove.
+     *
+     * The contract that makes it safe is the one those share — **the coords are valid until the
+     * next ask, so a caller reads them within its own loop and never holds one across a call that
+     * could ask again.** Every consumer does: the in-degree walk and `doEvaluate` finish a cell's
+     * edges before moving to the next (and `doEvaluate` copies the one it keeps, into
+     * `ReferenceRange`), and the lazy reads that run DURING an evaluation ask for the cell being
+     * evaluated, which is the cell already in the buffer.
+     */
+    protected _scratch: (IRange.Coords | FormulaError.Known)[] | null;
+    /**
+     * The persistent coords object behind each edge of {@link _scratch}, carrying the `$` marks the
+     * template stamps once. Held separately because a slot of `_scratch` can be an ERROR — a range
+     * whose endpoints cannot be unioned — and the object has to be there to write into next time.
+     */
+    protected _scratchCoords: IRange.FixableCoords[] | null;
+    protected _scratchRow: number;
+    protected _scratchCol: number;
+    /**
+     * Blank-aware evaluation (PLAN-WATCHES-BLANK-AWARE §4): the block's touched windows, cached per
+     * collection ({@link getTouched}), and what the pass decided about the blank region's
+     * representative. Per block INSTANCE — a block is re-minted on every edit, shift and split, so
+     * none of this survives a change to the block, and none of it has to.
+     */
+    protected _touched: TouchedWindows | null;
+    protected _touchedCycleId: number;
+    protected _touchedMarkId: number;
+    /** The collection {@link forEachTouchedNode} last minted the touched nodes for. */
+    protected _touchedMintedCycleId: number;
+    protected _touchedMintedMarkId: number;
+    /**
+     * The node standing for the blank region — its first cell — as of the last {@link getTouched};
+     * `null` when the block has no blank cell, or was never asked.
+     */
+    representative: CalcNode | null;
+    /** The representative's finalized scalar, shared with the blank region as runs; see {@link blankCycleId}. */
+    blankValue: Scalar | undefined;
+    /** The cycle and plan mark {@link blankValue} was written under; a plan that has not written it yet does. */
+    blankCycleId: number;
+    blankMarkId: number;
+    /**
+     * The blank rectangles {@link blankValue} was last written over, in a grid other formulas read;
+     * `null` before the first share and after a pass that evaluated the region cell by cell. What a
+     * later share is compared against to find the cells whose value it moved; {@link getTouched}
+     * takes out the cells that have become touched since, which hold their own values again.
+     */
+    blankShared: readonly IRange.Coords[] | null;
+    /** The blank partition {@link blankShared} was last brought in line with; set with it. */
+    protected _blankSharedAgainst: readonly IRange.Coords[] | null;
+    /** Records what a share covered, or `null` when the region goes back to per-cell values. */
+    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
+     * 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 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
+     * of that pass only.
+     */
+    blankFallbackCycleId: number;
+    /**
+     * Loaded with cells that carried no cached value (`CalcGridBackend._seedNow`'s repair). Such a cell
+     * has never been evaluated, and it was not ENTERED either, so Excel gives it no entry
+     * evaluation: joining a cycle, it starts the sweeps from `""` (DESIGN-CIRCULAR-CALC §2.4).
+     * Read only where the grid holds nothing for the cell — once evaluated, the value is the start.
+     * Carried through the rebuilds that keep the nodes (shift, split, merge), not by a copy.
+     */
+    uncalculated: boolean;
+    constructor(coords: IRange.Coords, gridId: string | null, formula: IFormulaBlock | null, container: IContextContainer, unanchored: boolean, nodes?: FormulaSpatialValue.NodeSource[]);
+    /** Every source block's nodes, at this block's cells - see {@link FormulaSpatialValue.NodeSource}. */
+    getNodeSource(): FormulaSpatialValue.NodeSource[];
+    /** Whether the nodes are held sparsely - see {@link _nodes}. */
+    isSparse(): boolean;
+    /** The node at the block's top-left, minted alone if the block has none yet. */
+    getAnchorNode(): CalcNode;
+    /** The node at an absolute cell, or `null` when the cell is outside the block or has no node. */
+    nodeAtOrNull(row: number, col: number): CalcNode | null;
+    /**
+     * The node at an absolute cell inside the block, minted now if the block has none there: a
+     * sparse block mints the one cell, a dense block its whole array.
+     *
+     * @remarks
+     * For one cell. A rectangle of cells goes through {@link mintNodesIn}, which writes them in one
+     * run rather than one at a time.
+     */
+    nodeAt(row: number, col: number): CalcNode;
+    /** The sparse store, created now, holding the anchor when one is already minted. */
+    protected _newSparseStore(): SparseGrid<CalcNode>;
+    /** The dense array, minted now over every cell, keeping the anchor already minted. */
+    protected _mintDense(): CalcNode[][];
+    /** The static edges a fresh node of this block stores at a cell - what {@link _createCalcs} gives every cell. */
+    protected _freshPrecedents(row: number, col: number): CalcNode['precedents'];
+    /**
+     * Drops the nodes. Called as the block leaves its map, so the maps of earlier commits, which
+     * still hold it, do not hold a generation of nodes with it. The anchor stays (see
+     * {@link _anchor}); everything else is minted again on the first touch after a restore.
+     */
+    release(): void;
+    /**
+     * Visits the nodes that EXIST inside a rectangle (absolute, clipped to the block). For a dense
+     * block that is every cell of it; for a sparse one, the touched cells and the representative.
+     */
+    forEachNodeIn(rowFrom: number, rowTo: number, colFrom: number, colTo: number, fn: (node: CalcNode) => void): void;
+    /**
+     * Visits EVERY cell of a rectangle (absolute, clipped to the block), minting the nodes a sparse
+     * block lacks first - in one write per call, column-major, as the store keeps them. This is
+     * how a cell comes to have a node: a collection found it touched, or a discovery walk found it
+     * reading a formula.
+     */
+    mintNodesIn(rowFrom: number, rowTo: number, colFrom: number, colTo: number, fn: (node: CalcNode) => void): void;
+    /** Visits every node the block has. */
+    forEachNode(fn: (node: CalcNode) => void): void;
+    /**
+     * The static precedent edges of the cell at (`row`, `col`), absolute — the same answer
+     * `resolvedPrecedentsAt` gives, translated from the block's template rather than resolved.
+     *
+     * @remarks
+     * Only meaningful on a block that HAS a template; `nodePrecedents` is what decides. The answer
+     * is the block's shared buffer — see {@link _scratch} for how long it stays valid.
+     */
+    getPrecedentsAt(row: number, col: number): (IRange.Coords | FormulaError.Known)[];
+    /**
+     * Whether the pass may evaluate ONE cell of this block's blank region and share its answer with
+     * the rest (PLAN-WATCHES-BLANK-AWARE §4) — the block-level gate over the formula's compile-time
+     * one ({@link isBlankCacheable}).
+     *
+     * @remarks
+     * A template is the shape the touched predicate needs (one relative edge per reference, the
+     * same at every cell); an array-entered block has its own fitted write; a one-cell block has
+     * nothing to share. The two pass-side verdicts — {@link blankRefused}, {@link blankFallbackCycleId}
+     * — close the gate after the fact.
+     */
+    isBlankAware(cycleId: number): boolean;
+    /**
+     * The block's touched windows for one collection — computed on first ask, from the grids its
+     * relative edges land on, and answered from the cache for the rest of the collection. Sets
+     * {@link representative} to the first blank cell's node (`null` when there is none).
+     *
+     * @remarks
+     * Keyed by `markId` as well as `cycleId`: a pass re-collects after a spill grows or shrinks, and
+     * the content a cell reads may have changed by then — a spill body is content — so the answer
+     * is recomputed for each collection, never carried across one.
+     */
+    getTouched(cycleId: number, markId: number): TouchedWindows;
+    /**
+     * Visits the touched cells of one collection, then the representative when the block has a
+     * blank region: what an input that is the same for every cell of the block reaches.
+     *
+     * @remarks
+     * The touched nodes are minted on the first ask of a collection. A touched cell need not have a
+     * node yet — a block loaded with its values was never collected — and walking only the nodes
+     * that exist would leave such a cell stale.
+     */
+    forEachTouchedNode(cycleId: number, markId: number, fn: (node: CalcNode) => void): void;
+    /** The last {@link getTouched} answer, whatever collection it was for; `null` before the first. */
+    getTouchedCached(): TouchedWindows | null;
+    /**
+     * The answer the block's blank cells share, and where they are. `null` while no representative
+     * has been shared, or once the block is evaluated per cell for good.
+     *
+     * @remarks
+     * The rectangles are the LAST collection's, which may be newer than the value: a cell that was
+     * blank then and is touched now has been evaluated and written since, and a stored value is read
+     * ahead of this — so the region only ever answers for cells nothing was written to.
+     */
+    getBlankRegion(): FormulaSpatialValue.BlankRegion | null;
+    /**
+     * 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.
+     *
+     * @remarks
+     * Inside the block a cell the grid lacks IS a blank-region cell — a touched cell has been evaluated
+     * and written (a committed empty as `null`), and the region is what is left — so a body in a
+     * grid nobody else reads (a watch's, a one-shot evaluation's) writes nothing for the region and
+     * a `Range` over it answers the region as its empty value, by omission rather than by
+     * rectangle. Outside the block nothing is shared, and `coords` wider than the block get `null`:
+     * a watch reads over its location, which is the block's extent once the two are reconciled.
+     */
+    getBlankValueWithin(coords: IRange.Coords): Scalar;
+    /**
+     * Keeps the nodes densely from now on.
+     *
+     * @remarks
+     * A sparse block holds a node only where a cell is touched, which is the right store while the
+     * blank-aware gate is open. Once the gate has closed for good — a per-cell read refused it
+     * ({@link blankRefused}), or the anchor took a fixed extent — every collection reaches every
+     * cell, and minting those through the store pays its per-node bookkeeping for nothing. Both
+     * verdicts are permanent, so this happens at most once per block, and the block is then what a
+     * per-cell block always was. The nodes that exist are MOVED, not cloned: the pass that closed
+     * the gate may be holding them.
+     */
+    densify(): void;
     protected _createCalcs(formula: IFormulaBlock | null, gridId: string | null, coords: IRange.Coords): CalcNode[][];
-    protected _cloneCalcs(calcs: CalcNode[][], colStart: number, rowStart: number, gridId?: string | null): CalcNode[][];
-    toJSON(r1c1?: boolean, formulaTransform?: ICalculation.FormulaTransform): [coords: string, text: string];
+    /** A fresh node for a cell of this block. */
+    protected _newNode(cellRow: number, cellCol: number, gridId: string | null, cellPrecedents: CalcNode['precedents']): CalcNode;
+    /**
+     * The static edges a cloned or minted node of a non-templated block stores; `null` under a
+     * template. The top-left's answer doubles as `paramLength`, so it is resolved once per clone.
+     */
+    protected _clonePrecedents(cellRow: number, cellCol: number, topLeft: CalcNode['precedents']): CalcNode['precedents'];
+    /**
+     * `original` re-minted as this block's node for (`cellRow`, `cellCol`): the same value, promise
+     * and cycle state, fresh slots and stamps - a new position, so nothing that described the old
+     * one is kept.
+     */
+    protected _cloneNode(original: CalcNode, cellRow: number, cellCol: number, gridId: string | null | undefined, cellPrecedents: CalcNode['precedents']): CalcNode;
+    /** The source node for this block's cell (`i`, `j`), whichever source holds it; `null` for none. */
+    protected _sourceNodeAt(sources: FormulaSpatialValue.NodeSource[], i: number, j: number): CalcNode | null;
+    /** A dense node array over this block, each cell cloned from its source node or minted fresh. */
+    protected _cloneDense(sources: FormulaSpatialValue.NodeSource[], gridId: string | null | undefined): CalcNode[][];
+    /** This block's sparse nodes: every source node whose cell lands inside the block, cloned there. */
+    protected _cloneSparse(sources: FormulaSpatialValue.NodeSource[], gridId: string | null | undefined): void;
+    /**
+     * @param coords The extent to serialize as. Defaults to the block's own; a caller that has
+     * coalesced adjacent equal blocks passes the merged extent, whose anchor is this block's.
+     */
+    toJSON(r1c1?: boolean, coords?: IRange.Coords): [coords: string, text: string];
     getCoords(): IRange.Coords;
     /** {@inheritDoc ISpatialMap.IUpdatableValue.getShifted} */
     getShifted(options: ISpatialMap.ShiftDetails<this>): ISpatialMap.Entry<this> | null;
@@ -83,29 +365,54 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
     /** {@inheritDoc IFormulaBlock.getTokensAt} */
     getTokensAt(row: number, column: number, evalIndex?: number): ICalculation.FormulaToken[];
     /** {@inheritDoc IFormulaBlock.getTextAt} */
-    getTextAt(row: number, column: number, r1c1?: boolean, formulaTransform?: ICalculation.FormulaTransform): string;
+    getTextAt(row: number, column: number, r1c1?: boolean, evalIndex?: number, target?: ICalculation.FormulaTarget): string;
+    /** {@inheritDoc IFormulaBlock.getNode} */
+    getNode(): ICalculation.FormulaNode | null;
     /** {@inheritDoc IFormulaBlock.resolvedPrecedentsAt} */
     resolvedPrecedentsAt(row: number, column: number, includeInvalidIntersect?: boolean, verticalAbs?: boolean[], horizontalAbs?: boolean[]): readonly (Readonly<IRange.FixableCoords> | FormulaError.Known)[];
+    /** {@inheritDoc IFormulaBlock.getPrecedentTemplate} */
+    getPrecedentTemplate(): PrecedentTemplate | null;
     /** {@inheritDoc IFormulaBlock.getReferences} */
     getReferences(row: number, column: number): ReferenceCoords[];
+    /** {@inheritDoc IFormulaBlockView.getReferencesAt} */
+    getReferencesAt(row: number, column: number): ReferenceCoords[];
+    /** {@inheritDoc IFormulaBlock.getFormatReferences} */
+    getFormatReferences(): IRange.FixableCoords[];
     /** {@inheritDoc IFormulaBlock.getReferenceAt} */
     getReferenceAt(row: number, column: number, index: number): ReferenceCoords;
     /** {@inheritDoc IFormulaBlock.setReferenceAt} */
     setReferenceAt(index: number, reference: ReferenceCoords, options?: SetReferenceOptions): this;
+    /**
+     * This block over fresh calc nodes: what {@link setReferenceAt} mints when it rewrites a
+     * reference, for a slot whose text does not change.
+     *
+     * @remarks
+     * A structured reference resolves through its table, so a shift that moves the cells it designates
+     * leaves its text alone. Its node still has to be re-minted like any other whose precedent moved:
+     * a node's input slot holds the reference range it last read, and a stale one would serve the
+     * pre-shift cells for as long as nothing writes into the range.
+     */
+    remint(): this;
     /** {@inheritDoc IFormulaBlock.reanchorReferences} */
     reanchorReferences(toGridId: string, force?: boolean): this;
-    /** {@inheritDoc IFormulaBlock.replaceSheetReferences} */
-    replaceSheetReferences(fromSheetDisplay: string, toSheetDisplay: string): this;
+    /** {@inheritDoc IFormulaBlock.replaceScopeIds} */
+    replaceScopeIds(fromScopeId: string | null, toScopeId: string | null): this;
     /** {@inheritDoc IFormulaBlock.wrapImplicit} */
     wrapImplicit(rowIndex: number, colIndex: number, setSpillCells: Set<string>): this;
     /** {@inheritDoc IFormulaBlock.getError} */
     getError(): FormulaError.Parse | null;
+    /** {@inheritDoc IFormulaBlock.getRecord} */
+    getRecord(): FormulaRecord;
     /** {@inheritDoc IFormulaBlock.getNamedIds} */
     getNamedIds(): string[];
     /** {@inheritDoc IFormulaBlock.getReferencedSymbolIds} */
     getReferencedSymbolIds(): string[];
     /** {@inheritDoc IFormulaBlock.hasTotals} */
     hasTotals(): boolean;
+    /** {@inheritDoc IFormulaBlock.isBlankCacheable} */
+    isBlankCacheable(arrayMode?: boolean): boolean;
+    /** {@inheritDoc IFormulaBlock.demandFirstCell} */
+    demandFirstCell(): void;
     /** @inheritdoc IFormulaBlock.isReferenceOnly */
     isReferenceOnly(): boolean;
     /** {@inheritDoc IFormulaBlock.isEquals} */
@@ -117,4 +424,25 @@ export interface FormulaCopyToOptions extends ISpatialMap.CopyOptions {
      */
     cutFrom?: IRange.Coords;
 }
+export declare namespace FormulaSpatialValue {
+    /**
+     * Where a block being built takes its nodes from: the source block's cell
+     * (`originRow + i`, `originCol + j`), in the source's own block coordinates, is the new
+     * block's cell (`i`, `j`). A split reads one source at an offset; a merge reads two, the
+     * second at a negative origin; a shift, re-image or re-anchor reads the block itself at
+     * (0, 0). A cell no source holds gets a fresh node.
+     */
+    interface NodeSource {
+        readonly block: FormulaSpatialValue;
+        readonly originRow: number;
+        readonly originCol: number;
+    }
+    /** See {@link FormulaSpatialValue.getBlankRegion}. */
+    interface BlankRegion {
+        /** The representative's finalized scalar. */
+        readonly value: Scalar | undefined;
+        /** The blank rectangles, in the block's own grid coordinates. */
+        readonly rects: readonly IRange.Coords[];
+    }
+}
 //# sourceMappingURL=FormulaSpatialValue.d.ts.map

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

@@ -6,10 +6,10 @@ import { ISpatialMap } from '../../collections';
  *
  * There are three {@link ITypes.FormulaArrayKind | kinds}:
  * * `dynamic` - the extent was derived from the result during a calculation cycle.
- * * `dynamicSpillError` - the spill was blocked. This can arise either from a direct input via the
- *   api or from a collision detected during a calculation cycle.
- * * `static` - a legacy array-entered (Ctrl+Shift+Enter) block, whose extent is fixed and
- *   authoritative rather than derived. Degenerate 1x1 static entries are legal and meaningful.
+ * * `error` - the spill was blocked. This can arise either from a direct input via the api or
+ *   from a collision detected during a calculation cycle.
+ * * `fixed` - an array-entered (Ctrl+Shift+Enter) block, whose extent is authoritative rather than
+ *   derived. Degenerate 1x1 fixed entries are legal and meaningful.
  */
 export declare class SpillEntry {
     private _c;
@@ -21,11 +21,26 @@ export declare class SpillEntry {
     getKind(): ITypes.FormulaArrayKind;
     getError(): boolean;
     /**
-     * True for a legacy array-entered block, whose extent must not be re-derived from the result.
+     * True for an array-entered block, whose extent must not be re-derived from the result.
      */
     isFixed(): boolean;
     getCoords(): IRange.Coords;
     setError(error: boolean, cycleId: number): ISpatialMap.Entry<this>;
+    /**
+     * Refuses a shift that would change part of a fixed block - Excel's "You can't change part of
+     * an array." A block the shift lands entirely before or after translates whole; a delete that
+     * swallows the whole block deletes it; anything that would split, trim, or grow it throws.
+     *
+     * @param intersect The inserted or deleted range, in pre-shift coordinates.
+     * @param isColumn `true` for a column shift (left/right), `false` for a row shift (up/down).
+     * @param isInsert `true` for an insert, `false` for a delete.
+     *
+     * @remarks
+     * Called from {@link getShifted}, and hoisted ahead of the maps' shift by the callers that lift
+     * intersecting spills before shifting (`markFixedSpills`), which would otherwise never hand a
+     * partially covered block to this node.
+     */
+    checkShift(intersect: IRange.Coords, isColumn: boolean, isInsert: boolean): void;
     /**
      * Translate the coordinates of the spill
      */

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

@@ -0,0 +1,86 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { ISparseGrid } from '../../collections';
+import { PrecedentTemplate } from '../Types';
+/**
+ * What the touched-window predicate reads of one grid a block's edges land on.
+ *
+ * @remarks
+ * A shadow grid (a watch body) hands over the grid it SHADOWS: its own results are not content the
+ * body reads, and must not inflate the bounds. Never the sheet's used range — that unions borders,
+ * fills, merges and tables, and a shadow grid has no sheet of its own.
+ *
+ * The `bounds` handed to either query are the predicate's own scratch coords, valid for the call:
+ * read them, never keep them.
+ */
+export interface TouchedGrid {
+    /**
+     * The grid's values — `getCoords()` is the value bounds ("where any constant or result lives"),
+     * `getRuns` its content runs.
+     */
+    readonly values: ISparseGrid<Scalar>;
+    /**
+     * The extents of every formula block intersecting `bounds`, in this grid. A formula cell whose
+     * current result is empty is still not blank: it can change within the pass.
+     */
+    searchFormulas(bounds: IRange.Coords): readonly IRange.Coords[];
+}
+/**
+ * The cells of a block partitioned by whether any RELATIVE precedent region of theirs holds
+ * content. Both lists are disjoint rectangles in the block's own coordinates, sorted row-major,
+ * and together they tile the block exactly.
+ */
+export interface TouchedWindows {
+    /** The cells whose relative inputs hold content, or land on a formula cell. */
+    readonly touched: readonly IRange.Coords[];
+    /** The complement within the block: every cell here evaluates to the representative's value. */
+    readonly blank: readonly IRange.Coords[];
+}
+/**
+ * The touched windows of a block — which of its cells have content, or a formula cell, in any
+ * relative precedent region of theirs — and, by complement, its blank region. A pure function of
+ * the block's precedent template and of the referenced grids' content; it never visits a cell,
+ * and allocates nothing but its answer.
+ *
+ * @remarks
+ * Two cuts per relative edge, in order, both O(things that exist):
+ *
+ * - **Bounds.** The referenced grid's value bounds (`getCoords()`), mapped back through the edge
+ *   to the block cells that could read them and clipped to the block. Empty means every cell of
+ *   the block reads past all content through this edge, and nothing more is asked.
+ * - **Content.** The grid's runs over what those cells can read, each mapped back the same way. A
+ *   run is one rectangle however long, so a dense column costs one rectangle, not a million.
+ *
+ * Unioned with the extents of the formula blocks the edge can land on, mapped back the same way:
+ * a formula cell whose result is empty right now can change within the pass, so a cell reading it
+ * is not blank.
+ *
+ * An absolute edge (`$B$1` — both axes fixed) is the same input for every cell and does not
+ * partition; it is skipped. Anchoring is per axis and per endpoint: `$A13` varies by row only, so
+ * its content maps to whole rows of the block.
+ *
+ * The bounds cut counts formula RESULTS as content, and a block's own cells write results — so for
+ * `=A1=B1` down column C the bounds say every row is touched, and only the content cut over A and
+ * B finds them blank. A watch body is the other way round: its results live in a shadow grid, so
+ * the bounds alone shrink a whole-column `$A13` to the sheet's rows. Both cuts are needed.
+ *
+ * Refused outright (the whole block reported touched): an edge on a grid `resolveGrid` cannot
+ * answer, a range edge whose endpoints name different grids, and a mixed-anchored axis that could
+ * invert inside the block.
+ *
+ * @param template The block's precedent template — one relative edge per static reference.
+ * @param block The block's extent, in its own grid's coordinates.
+ * @param resolveGrid The grid an edge's scope names; `null` for the block's own grid.
+ */
+export declare function computeTouchedWindows(template: PrecedentTemplate, block: IRange.Coords, resolveGrid: (scope: string | null) => TouchedGrid | null): TouchedWindows;
+/** Whether two window lists tile the same cells the same way; both are in the predicate's order. */
+export declare const sameWindows: (a: readonly IRange.Coords[], b: readonly IRange.Coords[]) => boolean;
+/**
+ * Appends to `out` the parts of `window` that none of `holes` covers, as disjoint rectangles.
+ *
+ * @remarks
+ * Each hole that meets a piece replaces it with what is left above, below, left and right of the
+ * overlap. The pieces a hole leaves cannot meet that hole again, so they are appended behind the
+ * walk, which runs backwards over the pieces that were there when the hole was taken up.
+ */
+export declare const subtractWindows: (window: IRange.Coords, holes: readonly IRange.Coords[], out: IRange.Coords[]) => void;
+//# sourceMappingURL=TouchedWindows.d.ts.map

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

@@ -3,4 +3,5 @@ export * from './CircularEntry';
 export * from './ContentfulSpatialValue';
 export * from './FormulaSpatialValue';
 export * from './PrecedentSpatialValue';
+export * from './TouchedWindows';
 //# sourceMappingURL=index.d.ts.map

package/types/src/calculation/state/CalcInputs.d.ts

@@ -0,0 +1,41 @@
+import { CalcNode } from './CalcNode';
+/**
+ * The backing array. Valid until the next {@link reserveInputs} that grows it, so read it once per node
+ * rather than holding it across a phase.
+ */
+export declare const getInputValues: () => any[];
+/** Drops every reservation. Called once per mark phase, before any node is given slots. */
+export declare const resetInputs: () => void;
+/**
+ * Empties the arena — every reservation dropped AND every slot cleared. Called when a pass
+ * finishes.
+ *
+ * @remarks
+ * The clearing is the point, and it is not tidiness. A range-typed slot holds a `ReferenceRange`,
+ * which holds the grid it reads; a scalar slot can hold a spilled `IRange`. Left in place those
+ * outlive the pass that made them, and the arena is module scope — so the last pass over a
+ * workbook would pin that workbook's grids for as long as the process lives, or until some later
+ * pass happened to reserve over the same slots. {@link reserveInputs} clears what it hands out,
+ * which covers correctness but not this: a pass that plans ten nodes after one that planned a
+ * million rewrites ten slots and leaves 999,990 pinned.
+ */
+export declare const releaseInputs: () => void;
+/**
+ * Gives `node` a run of `length` cleared slots and records the offset on it. `length` is the
+ * node's precedent count; a node with none is given `-1`, which every accessor reads as empty.
+ */
+export declare const reserveInputs: (node: CalcNode, length: number) => void;
+/**
+ * Slot `index` of `node`, or `undefined` where the node holds no slots — a node with no
+ * precedents, and one no mark phase has reached (the temporary formula `Calculation.evaluate`
+ * builds), whose reads are meant to fall through to the grid.
+ */
+export declare const getInputAt: (node: CalcNode, index: number) => any;
+/** Writes slot `index` of `node`. A node holding no slots is written nowhere, as it has nothing to read back. */
+export declare const setInputAt: (node: CalcNode, index: number, value: any) => void;
+/**
+ * Clears `node`'s slots in place — what a demand evaluation does before reading every precedent
+ * lazily, since nothing was pushed to it.
+ */
+export declare const clearInputs: (node: CalcNode, length: number) => void;
+//# sourceMappingURL=CalcInputs.d.ts.map