@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.10

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';
@@ -17,7 +18,9 @@ export declare class CalcExecutor {
     protected _container: IContextContainer;
     protected _context: IFormulaContext;
     private readonly _requestCalculate;
-    protected _pendingCalcs: Set<CalcNode>;
+    protected _pendingCalcs: Map<CalcNode, number>;
+    /** Debounced drain of {@link _pendingCalcs} into the volatile set; one instance for the executor's lifetime. */
+    private readonly _flushPendingCalcs;
     /**
      * The last pass's circular roster: every node it evaluated by demand (a `doMarkAndPlan` that
      * could not order, or the iteration guard's hand-over) plus every node whose dynamic read
@@ -51,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;
@@ -68,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
@@ -81,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
@@ -90,6 +142,63 @@ export declare class CalcExecutor {
         evaluations: number;
         retries: number;
     };
+    /**
+     * Counters and per-phase timings over every plan since construction — the measurement rig the
+     * performance plan's §1.6 rollout asks for, and what validates the §1.2/§1.3 caches while
+     * {@link planCacheMode} is `'assert'`.
+     */
+    protected _planStats: CalcExecutor.PlanStats;
+    /**
+     * The plan caches of CALC-PERFORMANCE-PLAN.md §1.2/§1.3.
+     *
+     * - `'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 — `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
+     *   plus epsilon.
+     * - `'off'`: stamps are neither written nor consulted.
+     */
+    planCacheMode: 'off' | 'assert' | 'on';
+    /** Next order-stamp plan id to hand out; ids are unique across passes. */
+    protected _planIdNext: number;
+    /** Id of the last fully-ordered plan that stamped (§1.2); `0` = none yet. */
+    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
+     * the same epoch has the identical affected closure and the same valid order, so discovery and
+     * the sort are skipped outright: the plan is reused verbatim and each node gets only its
+     * per-pass reset. TWO slots, because one was not enough for the common workflow — "type a value,
+     * then fill it down": the single-cell pass overwrote the remembered bulk plan every time. Slots
+     * are recycled least-recently-USED (a hit refreshes a memo's clock), so the two plans in play
+     * both stay resident: bulk → small edits → same bulk hits, and two alternating bulk edits both
+     * hit. NOT "keep the largest": a full calc's plan is the same size as a bulk edit's over the
+     * same sheet, and that tie evicted the bulk memo on the very next small edit. Per executor, not
+     * module scope (§1.5).
+     */
+    protected _planMemos: [CalcExecutor.PlanMemo, CalcExecutor.PlanMemo];
+    /** The memos' LRU clock. Its own counter, NOT `PlanStats.passes`: a stats reset must not reorder the slots. */
+    protected _planMemoClock: number;
+    /**
+     * Nodes with an async promise in flight. Per executor, NOT module scope — module scope would
+     * cross-pollute workbook instances (undo to 0 formulas needs to clear these; TODO - revisit
+     * how we manage promises).
+     */
+    protected _pendingPromises: Set<CalcNode>;
     _gridUpdates: Map<string, ICalcGrid.IncrementalUpdates> | null;
     _addDynamicPrecedent: ((node: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind) => void) | null;
     constructor(container: IContextContainer, context: IFormulaContext, requestCalculate: () => void);
@@ -116,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 _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 _iterRead;
+    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.
@@ -143,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 _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 _writeEarly;
+    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. */
@@ -184,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;
     /**
@@ -221,11 +508,17 @@ export declare class CalcExecutor {
      * carrying the {@link CycleRole} its reads gave it. Describes the last pass only.
      */
     getCircularNodes(): readonly CalcNode[];
-    /** @internal Demand-pass counters since construction: evaluations and `NeedsFirst` retries. */
+    /**
+     * @internal
+     * Demand-pass counters since construction — evaluations and `NeedsFirst` retries — plus the
+     * plan-phase counters and timings (see {@link _planStats}).
+     */
     getDemandStats(): {
         evaluations: number;
         retries: number;
-    };
+    } & CalcExecutor.PlanStats;
+    /** @internal Zeroes every counter/timing so a measurement window starts clean (`Calculation._resetStats`). */
+    resetStats(): void;
     /**
      * Collects and marks all volatile CalcNodes.
      *
@@ -253,6 +546,28 @@ export declare class CalcExecutor {
      * Uses Kahn's algorithm.
      */
     doMarkAndPlan(cycleId: number, markId: number, initial: FixedPackedArray<CalcNode>, plan: FixedPackedArray<CalcNode>, forceDemand?: boolean): boolean;
+    /**
+     * The remembered plan whose seed set is exactly this pass's, at this epoch — or `null`. The
+     * 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
+     * one if there is one, else the least recently used.
+     */
+    private _rememberPlan;
     doEvaluate(cycleId: number, getUpdates: (scope: string) => ICalcGrid.IncrementalUpdates, scheduleRecalculation: (cycleId: number, calcNode?: CalcNode) => void, commit: (calcNodes: CalcNode[], calcNodesLength: number) => void, forceFull: boolean, plan: FixedPackedArray<CalcNode>): ISpatialMap | undefined;
 }
 export declare namespace CalcExecutor {
@@ -276,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. */
@@ -285,17 +600,90 @@ 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() */
         oldVolatiles: Set<CalcNode>;
     }
+    /** A remembered fully-ordered pass for whole-closure reuse (§1.4) — see `CalcExecutor._planMemos`. */
+    interface PlanMemo {
+        seeds: CalcNode[];
+        seedsLength: number;
+        plan: CalcNode[];
+        planLength: number;
+        /** The `precedentEpoch` the plan was made at; `-1` = empty. */
+        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 {
+        /** In-degree formula lookups answered by the single-entry block cache. */
+        formulaCacheHits: number;
+        formulaCacheMisses: number;
+        /** doMarkAndPlan invocations. */
+        passes: number;
+        /** Passes whose whole affected set carried valid order stamps (fast-path candidates). */
+        fastEligible: number;
+        /** Eligible passes that actually skipped in-degree + Kahn (`'on'` mode only). */
+        fastHits: number;
+        /** Passes whose seed set and precedent epoch matched the last plan (§1.4 candidates). */
+        closureEligible: number;
+        /** Closure-eligible passes that reused the last plan verbatim, skipping discovery too (`'on'` only). */
+        closureHits: number;
+        /** `'assert'` mode: closure-eligible passes whose fresh affected set differed from the last plan. */
+        closureAssertFailures: number;
+        /** Fully-ordered plans that wrote order stamps. */
+        stampedPlans: number;
+        /** `'assert'` mode: eligible passes whose stamp order contradicted a real static edge. */
+        planAssertFailures: number;
+        /** `'assert'` mode: cached `dependents` that did not match a fresh search. */
+        dependentsAssertFailures: number;
+        /** 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;
+        evaluateMs: number;
+    }
     /** Updated spatial maps and committed grid batches returned to Calculation */
     interface ExecuteResult {
         precedentSpatial: ISpatialMap3D<PrecedentSpatialValue>;

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

@@ -3,6 +3,11 @@ import { Tuple, ISpatialMap } from '../../collections';
 import { CalcSignal } from '../../primitives/CalcSignal';
 import { CalcNode } from '../state';
 import { PrecedentSpatialValue, FormulaSpatialValue } from '../spatial';
+/**
+ * Visits the nodes of `block` a discovery walk reaches inside a rectangle (absolute, clipped to the
+ * block), minting those it decides the pass needs.
+ */
+export type MintWindow = (block: FormulaSpatialValue, rowFrom: number, rowTo: number, colFrom: number, colTo: number, fn: (calc: CalcNode) => void) => void;
 /**
  * Raised from a read that landed on unorderable nodes not yet evaluated: the reader is suspended,
  * `nodes` are evaluated first, and the reader is retried from scratch.
@@ -33,10 +38,46 @@ export declare class DownstreamSignal extends CalcSignal {
     readonly node: CalcNode;
     constructor(node: CalcNode);
 }
-export declare function rangeToTuples(range: IRange, offsetMajor?: number, offsetMinor?: number): Tuple.BoundedTuples<Scalar>;
+export declare function rangeToTuples(range: IRange, offsetMajor?: number, offsetMinor?: number): Tuple.Region<Scalar>;
+/**
+ * Fits a result to a fixed (array-entered) extent, per dimension: a dimension of 1 broadcasts, a
+ * longer one is clipped, a shorter one is padded with `#N/A`. Measured against Excel
+ * (`probe-cse.ps1`): `=SEQUENCE(5)` into 3 rows is `1,2,3`; `=SEQUENCE(2)` into 5 rows is
+ * `1,2,#N/A,#N/A,#N/A`; `=SUM(H1:H5)` into 3x3 is the sum nine times; a 1x3 into 3x3 repeats the
+ * row; a 3x1 into 3x3 repeats the column.
+ *
+ * @returns The fitted values, row-major, exactly `rowCount` x `colCount`. A blank source cell stays
+ * blank (`null`), as it does when a dynamic array spills. The fit is a fixed point - fitting the
+ * result again yields the same shape - so nothing downstream needs a "do not resize" guard.
+ */
+export declare function fitToExtent(value: Scalar | IRange, rowCount: number, colCount: number): Scalar[][];
+/**
+ * {@link fitToExtent} as grid tuples over `coords`, in the orientation of the grid they are written
+ * to. `null` when every fitted cell is blank.
+ */
+export declare function fitToTuples(value: Scalar | IRange, coords: IRange.Coords, isColumn: boolean): Tuple.Region<Scalar> | null;
 /**
  * TODO - document and/or rationalize with visitPrecedentBlock
  */
-export declare function visitDependencyBlock(depEntry: ISpatialMap.Entry<PrecedentSpatialValue>, rowIndex: number, colIndex: number, callbackFn: (calc: CalcNode) => void): void;
+export declare function visitDependencyBlock(depEntry: ISpatialMap.Entry<PrecedentSpatialValue>, rowIndex: number, colIndex: number, callbackFn: (calc: CalcNode) => void, mint?: MintWindow | null): void;
+/**
+ * Visit the cells of a dependent block that read a spill's BODY — the extent an anchor at
+ * (`anchorRow`, `anchorCol`) occupies, MINUS the anchor cell itself.
+ *
+ * @remarks
+ * A spill's body cells are written by the anchor but hold no formula of their own, so a reader
+ * that never touches the anchor (`=B4` against a `B2` spill) is invisible to both the precedent
+ * index — keyed at the anchor — and `formulaSpatial`, which knows nothing about the body. The
+ * anchor stands in for its whole extent here, which is what makes such a reader both DIRTY and
+ * ORDERED after it.
+ *
+ * The anchor cell is excluded because {@link visitDependencyBlock} at the anchor already answers
+ * for it: the two together cover the extent exactly once, which is what keeps the in-degree phase
+ * and Kahn's decrement in balance. The exclusion is per FORMULA CELL, not per entry — one entry
+ * can hold a block whose cells straddle the anchor (`D1=B2`, `D2=B3`) — and it applies only when
+ * the anchor is inside the entry at all, since an entry that does not cover the anchor was never
+ * in the anchor's dependents to begin with.
+ */
+export declare function visitSpillBodyBlock(depEntry: ISpatialMap.Entry<PrecedentSpatialValue>, anchorRow: number, anchorCol: number, extentRowEnd: number, extentColEnd: number, callbackFn: (calc: CalcNode) => void, mint?: MintWindow | null): void;
 export declare function valueCompareValues(a: ISpatialMap.Entry<FormulaSpatialValue>, removing: ISpatialMap.Entry<FormulaSpatialValue>): boolean;
 //# sourceMappingURL=CalcExecutorUtils.d.ts.map

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

@@ -72,6 +72,8 @@ export declare class CircularReference implements ICalculation.ICircularReferenc
     getIterationCount(): number;
     /** @inheritdoc ICalculation.ICircularReference.getLastChange */
     getLastChange(): number;
+    /** @inheritdoc ICalculation.ICircularReference.getPreviousChange */
+    getPreviousChange(): number;
     /** The members still on the graph, in row-major order (virtual grids first, then by sheet). */
     protected _liveMembers(): CalcNode[];
     protected _countLive(nodes: Set<CalcNode>): number;