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

package/types/src/calculation/compiler/Types.d.ts

@@ -1,5 +1,5 @@
 import { IFunction, IRange, IRuntime } from '@sheetxl/primitives';
-import { ISymbolRegistry } from '../symbol';
+import { ISymbolRegistry, SheetCtx } from '../symbol';
 import { ICalculation } from '../ICalculation';
 import { ASTNode, ASTVisitor } from './ASTTypes';
 /**
@@ -33,14 +33,19 @@ export interface IFormulaCompiler {
      */
     scope?: string | null, 
     /**
-     * A structural transform applied to the parsed tree before compilation (pre-link) — the READ
-     * half of the dialect hook. A format reader (io-xlsx) supplies its legacy unwrap here; typed
-     * text compiles without one.
+     * Compile in the legacy entry era: the whole tree evaluates in implicit-intersection value
+     * mode (`ICalculation.JSON.legacyIntersect`). A loaded block that is not an array anchor, in a
+     * calculation in that era; typed text compiles without it.
      */
-    formulaTransform?: ICalculation.FormulaTransform): CompiledFormula;
+    legacyIntersect?: boolean, 
+    /**
+     * How SHEET scopes bind — a body linked inside an external book names that book's sheets
+     * (`SheetCtx.book`). A committed cell formula passes nothing and may mint a link.
+     */
+    sheetCtx?: SheetCtx): CompiledFormula;
     /**
      * Excel-parity **Formula AutoCorrect** at the TEXT level: repair `expression` by appending the
-     * trailing closers (`)` / `}`) its unmatched openers imply. Purely lexical — brackets inside
+     * trailing closers (`]` / `)` / `}`) its unmatched openers imply. Purely lexical — brackets inside
      * string literals / structured references never count (they lex as single tokens), and the repair
      * is NOT validated here: the caller re-compiles and accepts it only when it parses clean (see
      * `ICalculation.IFormula.autoCorrect`).
@@ -162,10 +167,24 @@ export interface CompiledFormula {
      */
     bindings: number[];
     /**
-     * Represents all references as absolute ranges.
+     * Reusable scratch for resolving references to absolute ranges: ONE pre-allocated
+     * `IRange.Coords` per {@link referencesRelative} entry, mutated in place at each resolution.
      *
      * @remarks
-     * A cache
+     * The invariant every consumer must keep: **slot `k` always means declared reference `k`**
+     * (`CompiledPrecedent.value` is the slot for a leaf), and a resolution overwrites EVERY field
+     * of the slot — bounds and `scope` (`null` when unscoped, never left over from a previous
+     * resolution). Both resolution passes go through `toSimpleAbsoluteRange`, so the slots carry
+     * NO `$` marks: nothing on the evaluation path reads them from a resolved-absolute coords,
+     * and `_appendRootPrecedents` requires their absence (it stamps `$` onto copies from the
+     * compiler's per-axis flags, and only ever sets). Indexing by anything else (an execute
+     * position, an eval index) makes one object stand for different references between passes,
+     * and any field written conditionally then leaks across them — a bare `$A4` once inherited a
+     * stale cross-sheet scope this way and dereferenced against the wrong grid.
+     *
+     * The objects are yielded to callers (`evaluations`, precedent lists) and are only valid
+     * until the block's next resolution — a consumer that retains one across evaluations (or an
+     * `await`) must copy it.
      */
     referencesAbsolute: IRange.Coords[];
     /**
@@ -191,6 +210,16 @@ export interface CompiledFormula {
      * Because we manage as cells but update as ranges we need to track the start and end of the references.
      */
     referenceIndices: number[];
+    /**
+     * Positions in {@link referenceIndices} (so in `getReferences()`) of the cell and range
+     * literals that are value operands, in text order - the cells an entered formula inherits its
+     * number format from. A literal at a reference-typed parameter, a name, a structured reference
+     * and a `#REF!` are not listed.
+     *
+     * @remarks
+     * A cache, computed once at compile time from {@link ast}.
+     */
+    formatReferenceIndices: number[];
     /**
      * The formula's editor tokens (syntax highlighting, function/argument hints). Computed lazily and
      * cached on first call — most compiles (grid cells) never need them. On a parse failure this returns
@@ -223,7 +252,7 @@ export interface CompiledFormula {
      * @remarks
      * A cache, computed once at compile time from {@link ast}. What `IFormulaContext.filterTotals`
      * needs to answer per CELL, and computing it here is what keeps that answer free: the alternative
-     * is re-inspecting a neighbour's formula on every recalculation of every enclosing total.
+     * is re-inspecting a neighbor's formula on every recalculation of every enclosing total.
      *
      * "Anywhere in its tree", not "is the outermost call" — measured, `=SUM(SUBTOTAL(9,A1:A3))` is
      * excluded from an enclosing SUBTOTAL exactly as a bare `=SUBTOTAL(9,A1:A3)` is. Resolved through
@@ -231,6 +260,47 @@ export interface CompiledFormula {
      * `_xlfn.`-prefixed one both answer correctly.
      */
     hasTotals: boolean;
+    /**
+     * Whether the formula names a VOLATILE function anywhere in its tree — the cell recalculates on
+     * every pass, whether or not that call is ever reached.
+     *
+     * @remarks
+     * Volatility is otherwise marked at RUNTIME, by the body (`IFormulaContext.markVolatile`), which
+     * was equivalent while every argument was evaluated. It stopped being equivalent with lazy
+     * arguments: `=IF(TRUE,1,RAND())` never runs `RAND` and would silently stop recalculating.
+     * Excel keeps it volatile — measured 2026-09-07, `probe-lazy-args.ps1` P1: the cell costs a full
+     * recalculation on every idle F9, for `RAND`, `NOW` and `OFFSET` alike, in an arm no branch
+     * selects. So the mark is a property of the formula TEXT and is collected here.
+     *
+     * The declaration answers it (`Volatile<T>` on the return), so a UDF counts exactly as a
+     * built-in does and no list of names lives in the engine. `IFormulaContext.markVolatile()`
+     * remains on the context for a function that cannot declare — it is not how a built-in says it.
+     */
+    hasVolatile: boolean;
+    /**
+     * Whether every cell of a block running this formula whose RELATIVE inputs are all blank must
+     * evaluate to the same value within one pass — so the engine may evaluate one of them and share
+     * the answer (PLAN-WATCHES-BLANK-AWARE §4).
+     *
+     * @remarks
+     * A property of the formula TEXT, like {@link hasVolatile}, and `false` whenever the text shows
+     * the answer could depend on which cell is asking: an implicit intersection, a name, an
+     * expression callee, or a function the registry does not know. `TODAY()` and `NOW()` are
+     * accepted: volatile, but one value per pass. So are `RAND()` and every function taking a
+     * reference (`ROW()`, `OFFSET`, `FORMULATEXT`, the `SUMIF` family): whether the body reads a
+     * position (or draws) is a per-cell READ (`CalcScope.perCellRead`) that the pass sees when it
+     * evaluates the representative, not a property of the text. The block adds its own gates (a
+     * precedent template, not array-entered) and the pass its run-time ones (no dynamic read, no
+     * per-cell read, a scalar result); this is only the half that can be known from the text.
+     */
+    isBlankCacheable: boolean;
+    /**
+     * {@link isBlankCacheable} for a block evaluated in ARRAY mode throughout — every cell its own
+     * 1x1 array-entered extent (a conditional-format body). The same refusals less the value-mode
+     * one: with nothing intersecting, a value-or-range slot over a multi-cell reference reads the
+     * same cells at every cell.
+     */
+    isBlankCacheableArray: boolean;
     /**
      * Indicates if the formula is reference-only (i.e. it only returns a range and does not return a scalar value).
      */

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

@@ -1,8 +1,9 @@
 import { IRange, IFormulaContext } from '@sheetxl/primitives';
 import { FixedPackedArray } from '../../primitives/PrimitiveUtils';
+import { PendingOverlayGrid } from '../state/_PendingOverlayGrid';
 import { ISpatialMap, ISpatialMap3D } from '../../collections';
 import { FormulaSpatialValue, PrecedentSpatialValue, PrecedentKind } from '../spatial';
-import { ICalcGrid } from '../grid';
+import { ICalcGrid, CalcGridBackend } from '../grid';
 import { IContextContainer, CalcNode } from '../state';
 import { ReadHook } from '../state/_ReadObservedGrid';
 import { CircularReference, CycleHost } from './CircularReference';
@@ -53,13 +54,41 @@ export declare class CalcExecutor {
      * Lengths of the module scratch lists of one {@link doDemandEvaluate}: `_iterHits`, the
      * `Waiting` nodes the evaluation in progress read under iteration (each flagged
      * `CalcState.IterHit`; consumed when it returns); `_iterMembers`, the members the call marked,
-     * in marking order — the sweep order; `_iterDownstream`, the nodes it marked downstream,
-     * evaluated once more after the sweeps. On the executor rather than local because the lists
-     * grow across the runs a sweep nests.
+     * plus the downstream nodes a sweep found one of them reads (`CalcState.Swept`), in ADDRESS
+     * order once the sweeps begin ({@link _sortIterMembers}); `_iterDownstream`, the nodes it
+     * marked downstream, evaluated once more after the sweeps. On the executor rather than local
+     * because the lists grow across the runs a sweep nests.
      */
     protected _iterHitsLength: number;
     protected _iterMembersLength: number;
     protected _iterDownstreamLength: number;
+    /**
+     * The cycles of the demand run in progress that are still OPEN, under iteration: per cycle
+     * group, the stack index of its lowest started member. A cycle is a strongly connected
+     * component, and it is complete only when that member finishes — until then a node that reads
+     * one of its FINISHED members reaches the open member through it, and the open member reaches
+     * the reader up the stack, so the reader is in the cycle too ({@link _onMemberRead}). Removed
+     * when the member at the index finishes, so empty between runs.
+     */
+    protected _openGroups: Map<number, number>;
+    /**
+     * Cycle groups a later slice joined to another (`from → into`). A slice relabels only the
+     * nodes on the stack, so a group's finished members keep the old id until
+     * {@link _settleGroups} rewrites them; every read of a group in between resolves through here.
+     */
+    protected _groupAlias: Map<number, number>;
+    /** Inside {@link _demandSweep}'s sweeps — where a downstream node a swept node reads joins them. */
+    protected _sweeping: boolean;
+    /**
+     * Whether `_iterMembers` is in address order yet ({@link _sortIterMembers}) — false while the
+     * discovery that finds the cycles appends to it, true from the first sweep on, when a member
+     * that joins has to be placed rather than appended.
+     */
+    protected _iterSorted: boolean;
+    /** Where {@link _demandSweep} stands in the list, so an arrival below it can move it up; `-1` between sweeps. */
+    protected _sweepIndex: number;
+    /** How many nodes `_demandDeferred` holds for the {@link _demandRun} in progress. */
+    protected _deferredLength: number;
     /** The pass the hook answers for; inert otherwise. Set by `doMarkAndPlan`, released with `_gridUpdates`. */
     protected _passActive: boolean;
     protected _passCycleId: number;
@@ -70,6 +99,20 @@ export declare class CalcExecutor {
      * value is right, it is just not in the grid yet.
      */
     protected _flush: (() => void) | null;
+    /**
+     * Per grid, the committed values with the running pass's uncommitted results over them — the
+     * batch and the demand results the plan has not taken yet; what `getGridValues` answers with
+     * while a pass evaluates. Released with {@link _flush}.
+     */
+    _overlays: Map<string, PendingOverlayGrid> | null;
+    /**
+     * The blank regions of the blocks whose representative could not stand for them this plan
+     * (PLAN-WATCHES-BLANK-AWARE §4), and the cells of the regions that WERE shared whose value the
+     * share moved under a reader ({@link _dirtyBlankReaders}) — handed to `doEvaluate`'s incremental
+     * dirty set at the end of the plan, so the next iteration of the pass collects the first cell
+     * by cell and the readers of the second.
+     */
+    protected _fallbackDirty: ISpatialMap | null;
     /**
      * The cycle table (design §7.3): per cycle id, one live {@link CircularReference} holding the
      * nodes the sheet index currently shows as its members and as downstream of it — the object
@@ -83,6 +126,13 @@ export declare class CalcExecutor {
     protected _cycleHost: CycleHost;
     /** Last cycle id handed out by a demand pass; ids are unique across passes. */
     protected _cycleGroupNext: number;
+    /**
+     * Advances whenever the circular index changes — a node's shown role or group moves in
+     * {@link _trackCircular}. A remembered plan (§1.4) whose closure held no cycle node at the
+     * epoch it was made at still holds none while the epoch stands, which is what lets it be
+     * reused with the in-degree phase's cycle tainting skipped. See `fastEligible`.
+     */
+    protected _cycleEpoch: number;
     /**
      * Counters over every demand pass since construction: nodes evaluated by demand and
      * `NeedsFirst` retries. A retry is the cost of the path (a formula run and thrown away), so a
@@ -104,7 +154,7 @@ export declare class CalcExecutor {
      * - `'on'` (default): an eligible pass skips the in-degree + Kahn phases (plan = affected set
      *   sorted by order stamp) and discovery reuses cached `dependents`.
      * - `'assert'` (the §1.6 rollout mode; the diagnostic to flip back to if values ever look
-     *   stale — `__sxlCalc.mode('assert')`): stamps are written and eligibility computed, but every
+     *   stale — `calculation._planCacheMode('assert')`): stamps are written and eligibility computed, but every
      *   pass still runs the full search + Kahn phases; the fast path's order and the cached
      *   `dependents` are VERIFIED against them, mismatches counted in
      *   `planAssertFailures`/`dependentsAssertFailures` and logged. Costs the old planning price
@@ -118,6 +168,15 @@ export declare class CalcExecutor {
     protected _lastPlanId: number;
     /** Length of the last stamped plan — the `orderIndex` range the fast path's bucket order spans. */
     protected _lastStampedLength: number;
+    /**
+     * How many of the last stamped plan's nodes Kahn ordered; the rest — stamps at or past this
+     * index — are its DEMAND APPENDIX: nodes Kahn could not order (a static self-edge such as
+     * `OFFSET(A1,-1,0)` in A1) that are evaluated by demand after everything ordered. A pass that
+     * reuses the stamps or the memo re-flags them for demand (`Circular`, the batch, the roster)
+     * rather than evaluating them on the ordinary path. Equal to `_lastStampedLength` when the last
+     * plan was fully ordered.
+     */
+    protected _lastStampedOrderedLength: number;
     /**
      * Whole-closure reuse (§1.4): remembered fully-ordered passes — seeds, plan, and the
      * `precedentEpoch` each was planned at (`-1` = empty). A pass with the identical seed set at
@@ -166,14 +225,74 @@ export declare class CalcExecutor {
      * batch) is committed on the spot and read; `Done` with a cycle role makes the reader
      * downstream. Any other cell is a value. Inert outside a pass, so a reference built during one
      * and read later (a spill committed afterwards) is plain values.
+     *
+     * `prefetch` is the rectangle an ITERATION was asked for, announced before its first read. Only
+     * the `Unevaluated` decision belongs to it — bringing what the sweep may need forward is free,
+     * and over-eager is harmless (design §4.3) — while `Waiting` and a finished cycle role are left
+     * to the per-position reports the sweep makes, which is what stops an early-exit lookup from
+     * reporting the tail it never opened (plan item 1). It answers whether those reports can say
+     * anything at all: a rectangle holding no node of this pass and nothing the sheet shows in a
+     * cycle is swept unobserved.
      */
     private _onPassRead;
     /**
-     * Under iteration, a read of a `Done` cycle node by the node being evaluated: the reader is
-     * downstream of that cycle (design §6.3) unless it is in one itself. Nothing is aborted — the
-     * reader goes on with the value — so the mark is made here, on the reader.
+     * A read of a `Done` cycle node by the node being evaluated: the reader is downstream of that
+     * cycle unless it is in one itself. Nothing is aborted — the reader goes on — so the mark is
+     * made here, on the reader.
+     *
+     * @remarks
+     * Under iteration this is design §6.3, and the reader goes on with the member's real value.
+     * With iteration off the value is discarded when the evaluation finishes (`_demandRun` writes
+     * what the cell last had), and the reader runs on for the CLASSIFICATION alone: a cell can be
+     * both downstream of one cycle and a member of its own, and aborting at the first read decided
+     * that by read order. `A5 = IF(…, A5 - (A4*A2))` meets `A4` before it meets itself — postfix
+     * evaluation opens the inner product first — so it used to be reported downstream of `A4`'s
+     * cycle and never reached its own, leaving the user an `A4` to fix and an `A5` still circular.
+     * Running on lets the later `Waiting` read close it, and `_markCycleSlice` overwrites the role:
+     * member wins over downstream, never the reverse.
      */
-    private _iterRead;
+    private _markDownstream;
+    /**
+     * A read of a `Done` cycle node inside the demand loop, under iteration. Which of three things
+     * it is depends on where the cycle stands, not on the node alone:
+     *
+     * - **A member of a cycle still open** ({@link _openGroups}): the reader is in that cycle.
+     *   Recorded as a hit, like a read of a `Waiting` node, and the slice is marked when the reader
+     *   returns. This is what makes a cycle its whole strongly connected component however the pass
+     *   entered it. Entered at `reserve = SUM(months)`, a fund-sizing loop first closes through ONE
+     *   month (`reserve → month → minDist → size → … → reserve`); `size` then finishes, and every
+     *   other month reads it finished while `reserve` is still open beneath them. They feed
+     *   `reserve`: left downstream, the sweeps iterate a fragment and settle on a wrong number.
+     * - **A downstream node read by a node being swept**: it feeds the sweep, so it is swept too
+     *   ({@link _sweepAlong}). Nothing the discovery above misses can then leave a swept node
+     *   reading a value that moves only after the sweeps.
+     * - Anything else: the reader is downstream ({@link _markDownstream}).
+     */
+    private _onMemberRead;
+    /**
+     * Adds the downstream node `read` to the sweep list because `reader`, which is swept, reads it.
+     * Downstream of the reader's own cycle it closes a loop through the reader — a member, and
+     * `reader`'s next step if it has none. Downstream of another cycle it lies between the two: it
+     * keeps its role and moves with them (`CalcState.Swept`).
+     */
+    private _sweepAlong;
+    /**
+     * Adds `member` to the sweep list with the value the sweeps start it from, at its ADDRESS
+     * position once {@link _sortIterMembers} has ordered the list — Excel sweeps row-major, always
+     * (design §6.3), and a member that JOINS during the sweeps has to land in that order too or the
+     * order changes partway through the pass. Before the ordering, which is the discovery that finds
+     * the cycles, it appends: the list is sorted once, where it is finalized.
+     */
+    private _addIterMember;
+    /**
+     * Puts the sweep list in address order, once, where it is finalized: every sweep of the pass
+     * then runs in that one order, and {@link _addIterMember} places what joins later.
+     */
+    private _sortIterMembers;
+    /** The group `group` stands for now — itself unless a later slice joined it to another. */
+    private _resolveGroup;
+    /** Rewrites every group a slice joined to another ({@link _groupAlias}) on the pass's roster. */
+    private _settleGroups;
     /**
      * The nodes of this pass inside `coords` that are still `Unevaluated`, written into `into` from
      * slot `length` on; returns the new length.
@@ -193,39 +312,157 @@ export declare class CalcExecutor {
      * (the batch, after everything ordered is committed), and `doEvaluate` again for a single
      * ordered node whose dynamic read landed on a node not yet evaluated — the same suspension,
      * on the ordinary path (§5). Every node evaluated here is flagged `circular`, so the plan
-     * takes its `demandValue` when it reaches it, and its finalized scalar is already in the grid
-     * for later lazy reads; `flush` commits the ordered path's pending batch when a read needs a
-     * value still sitting in it. Flat: the stack is an array, so a 1,560-row chain is 1,560
-     * evaluations, not 1,560 JS frames. A node is retried at most once per `NeedsFirst` it raises,
-     * and with the prefetch of its static precedents that is normally once.
+     * takes its `demandValue` when it reaches it, and its finalized scalar is already in the
+     * overlay's demand layer for later lazy reads (`_pushDemand`); `flush` commits the ordered
+     * path's pending batch when a read needs a value still sitting in it. Flat: the stack is an
+     * array, so a 1,560-row chain is 1,560 evaluations, not 1,560 JS frames. A node is retried at
+     * most once per `NeedsFirst` it raises, and with the prefetch of its static precedents that is
+     * normally once.
      */
     protected doDemandEvaluate(cycleId: number, getUpdates: (scope: string) => ICalcGrid.IncrementalUpdates, worklist: readonly CalcNode[], flush: () => void): void;
     /**
-     * The finalized scalar goes into the grid now, so a later lazy read sees it; `doEvaluate`
-     * commits the same value with the notifications when it reaches the node.
+     * The finalized scalar goes into the overlay's demand layer now, so a later lazy read sees it;
+     * `doEvaluate` takes it from there and commits it with the notifications when it reaches the
+     * node. A sweep rewrites a member once per sweep, and none of those is a persistent write.
      */
-    private _writeEarly;
+    private _pushDemand;
+    /**
+     * The overlay of `gridId` for the `doEvaluate` in progress, made on first use — demand
+     * evaluation runs only inside one, so {@link _overlays} is installed. It commits through the
+     * `flush` of the `doEvaluate` that made it, and only that one.
+     */
+    private _overlayFor;
+    /**
+     * A finalized result fitted to its cell when the block makes every cell its own 1x1
+     * array-entered extent (`FormulaSpatialValue.arrayFirstCell`): element `[0,0]` of a range, so the
+     * cell stores a scalar and registers no spill. Anything else as it is.
+     */
+    private _fitCell;
+    /**
+     * The representative of a gated block has finalized (PLAN-WATCHES-BLANK-AWARE §4): its scalar is
+     * shared with the block's blank region, or the gate is closed and the region is re-collected
+     * cell by cell.
+     *
+     * @remarks
+     * Shared only when nothing the evaluation read was per cell (`CalcScope.perCellRead`: a draw, a
+     * position, a computed reference), the result is a scalar, and the node ran on its own - not a
+     * promise, not pending on one, not in a cycle. A per-cell read is a fact of the formula and
+     * closes the gate for good ({@link FormulaSpatialValue.blankRefused}); the rest may not recur
+     * and close it for this pass ({@link _fallbackBlank}).
+     *
+     * How the region is shared depends on who can read it (§4c). A block in a SHEET grid is read
+     * by other formulas, the sheet and the error index, all through the grid's values, so the
+     * scalar is written as runs - one per column of each blank rectangle, which for a column block
+     * is one run. A block in a grid that SHADOWS a sheet (a watch body, a one-shot evaluation) has
+     * exactly one reader, the range its owner holds, and that range answers the region as its empty
+     * value from the block (`FormulaSpatialValue.getBlankValueWithin`): nothing is written, whatever
+     * the region's size, and what an earlier pass stored there is removed so the block's answer is
+     * the one read.
+     *
+     * @param refuse The caller's own reasons the result cannot stand for the region.
+     */
+    private _finalizeRepresentative;
+    /**
+     * Marks dirty the cells of a shared blank region whose value the share just moved, wherever a
+     * formula reads them, so the pass's next iteration evaluates those readers against the runs now
+     * in the grid.
+     *
+     * @remarks
+     * A blank cell has no node. A formula that reads one - `=A2+1` beside a block of `=$D$1` whose
+     * representative is `A1` - is neither in the representative's dependents, which are searched at
+     * its own cell, nor ordered after it, so left alone it keeps the value the cell had before the
+     * share. The region is handled as a spill's changed extent is: what moved is content other
+     * formulas read, and it is re-collected as a dirty region.
+     *
+     * What moved is the whole region when the shared value differs from the last one, and otherwise
+     * the cells that joined the region since (a cleared input turns a touched cell blank, and the
+     * run replaces the value it computed for itself). A region nothing reads costs one search per
+     * rectangle and no further iteration.
+     *
+     * @param unmoved The rectangles that already held this value; `null` when every cell moved.
+     */
+    private _dirtyBlankReaders;
+    /**
+     * Closes a gated block's gate — for good when `sticky`, for this pass otherwise — and marks its
+     * blank region dirty, so the pass's next iteration collects those cells one by one.
+     *
+     * @remarks
+     * A gate closed for good also settles the block's node store: every collection from here on
+     * reaches every cell, so the nodes go dense ({@link FormulaSpatialValue.densify}) rather than
+     * being minted one by one through the sparse store.
+     */
+    private _fallbackBlank;
+    /**
+     * What the pass reads for `node` right now — a member's starting value, before any demand
+     * result of its own.
+     *
+     * @remarks
+     * A sparse grid answers `undefined` for a cell it holds nothing for, which is every formula that
+     * was entered and has not calculated yet. That is a blank start (`IF(F1="",…)` sees `""`), and
+     * blank as a value is `null`: `undefined` is neither a scalar the grid can store nor a demand
+     * result, where it means "none" (`doEvaluate` takes `0` for it). A named formula's body is a
+     * cell too, at (0,0) of the name's virtual grid.
+     *
+     * A formula LOADED without a value was never entered, and starts from `""` instead — Excel's
+     * start for it, and not blank, so `_demandSweep` gives it no entry evaluation
+     * ({@link FormulaSpatialValue.uncalculated}).
+     */
+    private _valueOnGrid;
+    /**
+     * Puts a prefetched node back where the prefetch found it — `Unevaluated`, with nothing its
+     * evaluation decided — because that evaluation reached a node still on the stack under it
+     * (trap 4b: a prefetch report is not a read, and neither is a prefetched evaluation). The node
+     * below finishes first, and this one is evaluated once nothing is suspended under it: from the
+     * reader's retry if the reader does read it after all, and from the run's own seed queue
+     * otherwise. `Circular` goes too, so a node neither reaches is evaluated by the plan in its own
+     * place rather than taking a demand result it never got.
+     */
+    private _unstartPrefetched;
+    /**
+     * Puts back the speculative evaluations that are suspended under one just put back, and answers
+     * the stack length that leaves. They asked for it, and they were not asked for themselves, so
+     * without it none of them can finish — retrying them would ask for it again, and again.
+     * Unwinding to the first entry no prefetch put there hands the stack back to an evaluation a
+     * READ wants, and what that one asks for next is asked for in earnest: the chain comes back
+     * without the flag, and the cycle it reaches is marked.
+     */
+    private _unwindSpeculative;
     /** The worklist loop of {@link doDemandEvaluate}; re-entered by a sweep for the nodes a read needs first. */
     private _demandRun;
     /**
      * Marks the started (`Waiting`) nodes on the in-progress stack from `read` up to the top as one
      * cycle — the slice a `Waiting` read names (design §4.3). A slice touching a member of an
-     * earlier cycle joins that cycle. The started nodes are on the stack in READ order — each is
-     * there because the one below it read it, and the reader on top read `read` — so the slice is
-     * the walk `getPath` answers: each member is linked to the next, the last back to the first.
+     * earlier cycle joins that cycle, and one touching several joins them all into one. The started
+     * nodes are on the stack in READ order — each is there because the one below it read it, and the
+     * reader on top read `read` — so the slice is the walk `getPath` answers: each member is linked
+     * to the next, the last back to the first. When the reader reached `read` through a finished
+     * member of its cycle, that member is `via` and is the reader's next step instead.
      * The demand state is left as it is: the caller finishes the members (iteration off) or lets
      * them run on (iteration on). Returns the stack index of `read`.
      */
     private _markCycleSlice;
     /**
-     * Iterative calculation (design §6.3) over the members {@link _demandRun} marked, which it
-     * evaluated once each — sweep 1. Every further sweep re-evaluates them in marking order, each
-     * read seeing the latest value (Gauss–Seidel, as Excel: `probe-iterative.ps1`), until no member
-     * moved by `maxChange` or `maxIterations` sweeps ran. The limits are global, as in Excel — one
-     * unsettled member keeps every cycle of the pass sweeping. Downstream nodes read the members
-     * once more afterwards; they never feed a cycle, so they need no sweeping. The members are then
-     * registered as volatile so the next recalculation re-runs them, which is how `=A1+1` advances
-     * per recalc (Excel re-iterates every cycle on every `Calculate()`).
+     * Iterative calculation (design §6.3) over the members {@link _demandRun} marked. Each sweep
+     * evaluates them in ADDRESS order, each read seeing the latest value (Gauss–Seidel in row-major
+     * order, as Excel: `probe-iterative.ps1`), until no member moved by `maxChange` or
+     * `maxIteration` sweeps ran.
+     * The limits are global, as in Excel — one unsettled member keeps every cycle of the pass
+     * sweeping. Downstream nodes read the members once more afterwards; one that feeds a swept node
+     * is swept with them instead (`_onMemberRead`), so the rest feed no cycle and need no sweeping.
+     * Converged means a sweep over a list that did not grow moved nothing by `maxChange`: every
+     * node a swept node reads is then swept itself or does not move in this pass, so the state is a
+     * fixed point and not a fragment's. The members are then registered as volatile so the next
+     * recalculation re-runs them, which is how `=A1+1` advances per recalc (Excel re-iterates every
+     * cycle on every `Calculate()`).
+     *
+     * @remarks
+     * The evaluation that FOUND the members ran in dependency order — `B1 = B2+1` needs `B2` first,
+     * whichever of the two the plan reached first — so its results are not a sweep of this order,
+     * and counting them as one costs a step. The members go back to the values the pass found them
+     * at; a member that had none is then evaluated once, in address order, for the entry evaluation
+     * Excel gave it when it was written (§2.4), and every one of the `maxIteration` sweeps runs on
+     * top of that. Discovery's results are never read: a node that read a member is downstream, and
+     * evaluates again below.
      */
     private _demandSweep;
     /** Clears the `IterHit` flags of the hits not consumed by {@link _demandRun}'s loop and empties the list. */
@@ -234,7 +471,7 @@ export declare class CalcExecutor {
      * One evaluation of a `Done` node under iteration, with the read hook armed. A read that
      * needs a node not yet evaluated (a handed-over node's sweep runs before the batch) runs those
      * by demand and retries; a `Waiting` read cannot occur (nothing is waiting) and a member's
-     * result is a value (`_iterRead`), so nothing aborts.
+     * result is a value (`_markDownstream`), so nothing aborts.
      */
     private _demandEvaluateOne;
     /**
@@ -280,7 +517,7 @@ export declare class CalcExecutor {
         evaluations: number;
         retries: number;
     } & CalcExecutor.PlanStats;
-    /** @internal Zeroes every counter/timing so a measurement window starts clean (`__sxlCalc.reset()`). */
+    /** @internal Zeroes every counter/timing so a measurement window starts clean (`Calculation._resetStats`). */
     resetStats(): void;
     /**
      * Collects and marks all volatile CalcNodes.
@@ -314,6 +551,17 @@ export declare class CalcExecutor {
      * length check first: it is what rejects the common miss (a single-cell pass against a bulk
      * memo) before any node is touched.
      */
+    /**
+     * Flags `plan[from..to)` for demand evaluation the way the cycle-detection branch does when it
+     * appends them: `Circular`, no carried demand value, in the batch and on the roster. Used by
+     * the paths that reuse a plan without rebuilding it (the closure memo, the stamp order).
+     */
+    private _flagDemandAppendix;
+    /**
+     * Drop both plan caches (§1.2 order stamps and §1.4 whole-closure reuse): nothing they hold is
+     * a valid order for the graph any more. The next mark phase plans from scratch and re-stamps.
+     */
+    protected _invalidatePlans(): void;
     private _matchPlanMemo;
     /**
      * Records this pass's seeds and plan for whole-closure reuse (§1.4). The victim slot is a stale
@@ -343,7 +591,7 @@ export declare namespace CalcExecutor {
     }
     /** The two limits of `ICalculation.IterativeCalculation`. */
     interface IterateOptions {
-        maxIterations: number;
+        maxIteration: number;
         maxChange: number;
     }
     /** How a cycle's last iterated evaluation ended — what `ICircularReference` answers. */
@@ -352,12 +600,28 @@ export declare namespace CalcExecutor {
         converged: boolean;
         /** Sweeps run, the first evaluation included. */
         iterationCount: number;
-        /** The largest change any member made in the last sweep. */
+        /**
+         * The largest change THIS cycle's members made in the last sweep.
+         *
+         * @remarks
+         * Convergence is global, as Excel has it — one unsettled member keeps every cycle of the pass
+         * sweeping — but the number a tooltip shows is the asking cycle's own, or A4 reports the 9.8
+         * that A5 moved while it moved 0.98.
+         */
         lastChange: number;
+        /**
+         * The same, for the sweep BEFORE the last — `NaN` when there was only one.
+         *
+         * @remarks
+         * Two numbers say something one cannot: a run that stopped on the cap while still shrinking is
+         * a `maxIteration` that is too low, and one whose change is flat or growing does not settle at
+         * any cap. The sweep has both in hand; nothing else can recover the second.
+         */
+        previousChange: number;
     }
     /** Snapshot of Calculation's persistent state for one pass */
     interface ExecuteState {
-        gridsAll: Map<string, ICalcGrid>;
+        gridsAll: Map<string, CalcGridBackend>;
         formulaSpatial: ISpatialMap3D<FormulaSpatialValue>;
         dirtySpatial: ISpatialMap3D;
         /** Volatiles accumulated before this cycle — drained and cleared by execute() */
@@ -373,6 +637,15 @@ export declare namespace CalcExecutor {
         epoch: number;
         /** `CalcExecutor._planMemoClock` when last written or matched — the LRU key for slot recycling. */
         used: number;
+        /** No node of the plan was shown in a cycle (or downstream of one) when the plan was made. */
+        cycleFree: boolean;
+        /** `CalcExecutor._cycleEpoch` when the plan was made; a hit requires it unchanged. */
+        cycleEpoch: number;
+        /**
+         * Index of the first demand-appendix node in `plan` — `planLength` when the plan was fully
+         * ordered. A hit re-flags `plan[demandStart..planLength)` for demand evaluation.
+         */
+        demandStart: number;
     }
     /** Plan-phase counters and timings — see `CalcExecutor.planCacheMode` and performance plan §1.6. */
     interface PlanStats {
@@ -400,6 +673,12 @@ export declare namespace CalcExecutor {
         /** Discovery searches skipped (or verified) because `dependentsEpoch` was current. */
         dependentsCacheHits: number;
         dependentsCacheMisses: number;
+        /**
+         * Nodes evaluated on the ORDERED path (`evaluateAt` from `doEvaluate`); `evaluations` counts
+         * the demand path. Their sum is every formula run — what blank-aware evaluation
+         * (PLAN-WATCHES-BLANK-AWARE §4) reduces to the touched cells plus one.
+         */
+        evaluated: number;
         discoveryMs: number;
         inDegreeMs: number;
         kahnMs: number;