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

package/types/src/calculation/executor/_WhatIf.d.ts

@@ -1,10 +1,6 @@
 import { IRange, Scalar } from '@sheetxl/primitives';
 import { CalcNode, IContextContainer } from '../state';
 import { WhatIfLayer } from '../state/_WhatIfLayer';
-/**
- * A what-if data table as its `TABLE` formula states it (DESIGN-DATA-TABLES §1): the results'
- * top-left cell and size, and the input cells, all on one grid.
- */
 export interface WhatIfTable {
     gridId: string;
     /** The top-left result cell: where the `TABLE` formula sits. */
@@ -30,21 +26,6 @@ export interface WhatIfHost {
 }
 /** The rectangles of a table's edge: the formula cells, then the axes. All on the table's grid. */
 export declare function whatIfEdge(table: WhatIfTable): IRange.Coords[];
-/**
- * The affected set S of a table (DESIGN-DATA-TABLES §4.3): every node downstream of an input
- * that is upstream of a formula cell or an axis cell, in an order that evaluates a node after
- * the nodes it reads. Widened to the whole downstream closure when a member reads through a
- * dynamic reference, whose edges the index cannot bound.
- *
- * A `TABLE` node is never a member, this table's own included: another table's results are read as
- * they stand, not re-run under this table's substitutions, as Excel reads them (design §2.2 T6).
- * That also keeps the walk from passing through a table's own edges, which would reach the table.
- */
 export declare function whatIfAffectedSet(container: IContextContainer, table: WhatIfTable): CalcNode[];
-/**
- * A table's results under the what-if protocol of DESIGN-DATA-TABLES §2.2, evaluating `affected`
- * (from {@link whatIfAffectedSet}) under each substitution. The layers are the host's; nothing is
- * restored, the caller drops them.
- */
 export declare function runWhatIf(host: WhatIfHost, table: WhatIfTable, affected: readonly CalcNode[]): Scalar[][];
 //# sourceMappingURL=_WhatIf.d.ts.map

package/types/src/calculation/formula/FormulaBlock.d.ts

@@ -176,36 +176,8 @@ export declare class FormulaBlock implements IFormulaBlock {
      * shared named-body block at every level, and only a copy keeps an outer activation's captured
      * environment intact underneath it. See `LambdaValue`.
      */
-    /**
-     * Fills the shared argument buffer for a call that has at least one LAZY argument, deciding per
-     * call whether to defer at all.
-     *
-     * @remarks
-     * The engine declines whenever an eager argument is a CONTAINER, because the call is then about
-     * to LIFT: the body runs once per element and different elements may select different arms, so
-     * every arm is needed. Excel abandons laziness there too — `=IF(B1:B3>0,1,A1+1)` in A1 IS a
-     * circular reference where the scalar-condition form is not (measured, `probe-lazy-args.ps1`).
-     *
-     * A declined argument is evaluated ONCE, here, and handed over as the VALUE rather than as a
-     * filled handle: the lift SAMPLES an arm per element (`IF(A1:A5>2,A1:A5,0)` answers element by
-     * element), and only the marshaller can sample it. The handle it hands the body is rebuilt there,
-     * around the sampled member. So the arm is evaluated once and indexed, never re-evaluated.
-     *
-     * Deferring evaluates nothing, so nothing can re-enter `_reuseArgs` while it is being filled.
-     * The decline path does evaluate, and takes a private array for exactly that reason.
-     */
     protected _fillLazyArgs(argsIndexed: ASTNode[], argsLength: number, regs: any[], frame: ReadonlyMap<number, any> | null, row: number, column: number, depth: number): void;
     protected _createLambdaValue(node: FunctionNode, regs: any[], frame: ReadonlyMap<number, any> | null, row: number, column: number): LambdaValue;
-    /**
-     * The callee verdicts + apply for a `Call` node (design §3.4, §1.1):
-     *
-     * - a lambda value → arity check, bind, evaluate the body;
-     * - a function value (eta `SUM`) → dispatch to the function itself;
-     * - a reference that is not a lambda → `#REF!` (Excel resolved it and failed to CALL it);
-     * - any other value → `#VALUE!` (a failed coercion, same class as `="a"+1`).
-     *
-     * All three error rows are MEASURED (probe-lambda-call.ps1).
-     */
     protected _applyCallee(callee: any, node: ASTNode, regs: any[]): any;
     /**
      * Apply over VALUES — the marshalled-callable twin of {@link _applyCallee}'s lambda branch

package/types/src/calculation/formula/FormulaRecordView.d.ts

@@ -4,11 +4,6 @@ import { ICalculation } from '../ICalculation';
 import { ReferenceCoords, StructuredReference } from '../Types';
 import { CompilerLocale } from '../compiler/CompilerLocale';
 import { FormulaRecord, IFormulaBlockView } from './IFormulaBlock';
-/**
- * What imaging a {@link FormulaRecord} needs beside the record (DESIGN-CALC-SERVICE §8): the
- * symbol map to resolve its stable ids against, the grid the formula sits on, and the reader's
- * locale. The facade supplies the model's own map; the engine never images for it.
- */
 export interface FormulaImager {
     /** Stable ids to display names. */
     readonly symbols: ISymbolRegistry;
@@ -24,16 +19,6 @@ export interface FormulaImager {
      */
     resolveTableReference?(reference: StructuredReference, row: number): IRange.FixableCoords | FormulaError.Known;
 }
-/**
- * A block as the model reads it: the engine's record imaged against the reader's own symbols
- * (DESIGN-CALC-SERVICE §8).
- *
- * @remarks
- * What the facade hands the model for every block the engine vends. The record is plain data and
- * crosses the channel; the imager is the facade's and never does. Text is the same function of
- * (tokens, symbols, anchor, locale) the compiled block images by - only where it runs differs -
- * so what a sheet reads is what the engine would image, by the model's names.
- */
 export declare class FormulaRecordView implements IFormulaBlockView {
     /** The block as data: what this view images. */
     readonly record: FormulaRecord;

package/types/src/calculation/formula/IFormulaBlock.d.ts

@@ -1,18 +1,6 @@
 import { IRange, FormulaError } from '@sheetxl/primitives';
 import { ICalculation } from '../ICalculation';
 import { ReferenceCoords, SetReferenceOptions, PrecedentTemplate, StructuredReference } from '../Types';
-/**
- * A compiled formula as data (DESIGN-CALC-SERVICE §8): what the engine vends for a block, and all
- * the facade needs to image a read view of it for the model (`FormulaRecordView`). Plain data, so
- * it survives `structuredClone`; the syntax tree never crosses.
- *
- * @remarks
- * The tokens carry stable ids in their values - a sheet's, a name's, a table's - and cell
- * coordinates relative to the block's top-left, so one record serves every cell of the block. Text
- * is imaged from them against the reader's own symbol map ({@link FormulaImager}), which is what
- * makes a held copy rename-proof: nothing in the record names a sheet by its name. The model
- * never sees one: it holds the view.
- */
 export interface FormulaRecord {
     /** The block's tokens, stable ids in their values, references relative to the block's top-left. */
     readonly tokens: readonly ICalculation.FormulaToken[];

package/types/src/calculation/formula/LambdaValue.d.ts

@@ -172,20 +172,5 @@ export declare const OMITTED: unique symbol;
  * to convert, so it cannot leak (plan risk 2).
  */
 export declare const readFrameValue: (value: any) => any;
-/**
- * The recursion budget apply enforces via `CalcScope.depth`.
- *
- * @remarks
- * DESKTOP measured (probe-lambda-eval block A, 2026-08-21): its cap sits between 5,000 and 100,000, and the error at it IS `#NUM!` — the
- * error Microsoft's own LAMBDA documentation names for runaway recursion.
- *
- * 512 rather than Online's 1000: each apply level costs a dozen JS frames, and past ~1000 levels a
- * BROWSER stack dies first — not as a catchable `RangeError` at the recursion site, but as
- * arbitrary near-exhaustion failures deep inside the engine (a regex compile inside the number
- * parser was the observed one), which inner catch sites convert to `#VALUE!` values. The budget
- * has to keep the engine comfortably inside every platform's stack; raising it toward the measured
- * desktop number needs the lazy-`IF` (Conditional) carve-out first, since eager `IF` makes every
- * terminating recursion burn to this cap before unwinding.
- */
 export declare const MAX_LAMBDA_DEPTH = 512;
 //# sourceMappingURL=LambdaValue.d.ts.map

package/types/src/calculation/formula/TokenUtils.d.ts

@@ -21,14 +21,7 @@ export declare function absoluteReferences(references: readonly ReferenceCoords[
  * When `symbols` is absent (no registry was used at compile time) the tokens
  * already hold display names and are returned as-is.
  */
-export declare function resolveTokenSymbols(tokens: ICalculation.FormulaToken[], symbols: ISymbolRegistry | null | undefined, canonical?: boolean, 
-/**
- * Re-image for a READER rather than for storage. Only an external book reads differently: stored
- * it is `[n]Sheet1` (a position), displayed it is the book's own spelling, and the book half is
- * split into its own {@link TokenType.ExternalReference} token so an editor can color or elide it
- * (DESIGN-EXTERNAL-LINKS §4B).
- */
-display?: boolean, 
+export declare function resolveTokenSymbols(tokens: ICalculation.FormulaToken[], symbols: ISymbolRegistry | null | undefined, canonical?: boolean, display?: boolean, 
 /**
  * The formula's cell (`scope` is its sheet's name or id), for display only. A single-column
  * reference to the table holding it (`Table1[Qty]`, `Table1[@Qty]`) drops the table name, as Excel

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,6 +113,8 @@ 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} */
     getCalcStatus(transaction?: ITransaction | null): ISpatialMap<ICalcGrid.CalcStatus>;
     /** {@inheritDoc ICalcGrid.getCalcErrors} */
@@ -279,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>[];
@@ -347,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>;
@@ -387,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
@@ -397,10 +346,6 @@ export declare namespace CalcGrid {
         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 calcStatusSpatial}.
-         */
         circularSpatial: ISpatialMap<CircularEntry>;
         /**
          * Error VALUES by cell, as the WRITE path knows them: fresh for what the model entered and
@@ -435,6 +380,7 @@ export declare namespace CalcGrid {
         values: ISparseGrid<Scalar>;
         contentful: ISpatialMap<ContentfulSpatialValue>;
         spills: ISpatialMap<SpillEntry>;
+        blockedSpills: ISpatialMap<SpillEntry>;
         calcStatus: ISpatialMap<ICalcGrid.CalcStatus>;
         calcErrors: ISpatialMap<string>;
         circulars: ISpatialMap<CircularEntry>;

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.
@@ -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 (DESIGN-CALC-SERVICE §11); every site
-     * that pushes calls this rather than `_options.onCalculated`.
-     */
     protected _onCalculated: (response: CalcResponse) => void;
     constructor(options?: CalcGridBackend.ConstructorOptions);
     /**
@@ -321,7 +313,7 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
     /** 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.
@@ -357,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.
@@ -399,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;
 }

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;

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

@@ -62,7 +62,8 @@ export declare function clearErrorIndex(errorSpatial: ISpatialMap<string>, coord
 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>, // the circular index: a written cell leaves it, like errorSpatial
-calcStatusSpatial?: ISpatialMap<ICalcGrid.CalcStatus>): IRange.Coords | null;
+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
  *
@@ -122,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.
@@ -156,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.
  *
@@ -194,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,6 +67,11 @@ 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.
@@ -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' | 'getCalcStatus' | '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. */
@@ -437,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.
@@ -516,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>[];
         /**
@@ -559,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.
@@ -628,17 +554,6 @@ export declare namespace ICalcGrid {
         circularSpatial: ISpatialMap<CircularEntry>;
         contentfulSpatial: ISpatialMap<ContentfulSpatialValue>;
         notifyValues: ISpatialMap;
-        /**
-         * Reports a region whose answer changed without a write to the grid: a blank region the pass
-         * shares one answer for on the block instead of writing (PLAN-WATCHES-BLANK-AWARE §4c).
-         *
-         * @remarks
-         * Accumulated as bounds, not as a region index. Only `Results.bounds` learns of this - there
-         * are no values to vend - and that is one rectangle over every notify source, so the union is
-         * the whole of what a caller can observe.
-         *
-         * `coords` is read, never kept, and its scope is ignored.
-         */
         notifyBlank(coords: IRange.Coords): void;
         notifySpillsInsert: ISpatialMap.Entry<SpillEntry>[];
         notifySpillsRemove: IRange.Coords[];