@sheetxl/sdk 0.7.28-beta.2 → 0.7.28-beta.4

package/types/src/calculation/Calculation.d.ts

@@ -44,6 +44,15 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     protected _pendingPriority: (() => Promise<unknown>)[] | null;
     protected _draining: boolean;
     protected _drainScheduled: boolean;
+    protected _calcOwed: boolean;
+    /** {@link ICalculation.getCalculationMode} — gates the reactive pass in {@link _calculate}. */
+    protected _calcMode: ICalculation.CalculationMode;
+    /** {@link ICalculation.getIterativeCalculation} — handed to the executor per pass. */
+    protected _iterate: boolean;
+    protected _maxIterations: number;
+    protected _maxIterateChange: number;
+    /** The `calcPr` the file carried, kept whole so settings this engine ignores still round-trip. */
+    protected _calcJSON: ICalculation.JSON | null;
     protected _removeNamedItemsListeners: (() => void) | null;
     protected _namedDependents: Map<string, IRange.Coords[]> | null;
     protected _namedDependentsOf: ISpatialMap3D<FormulaSpatialValue> | null;
@@ -218,6 +227,18 @@ export declare class Calculation extends AbstractModel<State, ICalculation.JSON,
     stop(): Promise<void>;
     /** @inheritdoc ICalculation.getStatus */
     getStatus(): ICalculation.Status;
+    /** @inheritdoc ICalculation.getCalculationMode */
+    getCalculationMode(): ICalculation.CalculationMode;
+    /** @inheritdoc ICalculation.setCalculationMode */
+    setCalculationMode(mode: ICalculation.CalculationMode): this;
+    /** @inheritdoc ICalculation.isCalculationRequired */
+    isCalculationRequired(): boolean;
+    /** @inheritdoc ICalculation.getIterativeCalculation */
+    getIterativeCalculation(): ICalculation.IterativeCalculation;
+    /** @inheritdoc ICalculation.setIterativeCalculation */
+    setIterativeCalculation(options: boolean | Partial<ICalculation.IterativeCalculation>): this;
+    /** @inheritdoc ICalculation.toJSON */
+    toJSON(): ICalculation.JSON;
     /** @inheritdoc ICalculation.ready */
     ready(options?: ICalculation.CalculateOptions): Promise<ICalculation.Status>;
     /**
@@ -421,18 +442,6 @@ interface State extends AbstractModel.State {
      * Listeners to individual named items
      */
     itemRemoveListeners: (() => void)[];
-    /**
-     * Indicates if calculation will do iterative calcs
-     */
-    iterate: boolean;
-    /**
-     * The maximum number of iterations to perform when calculating.
-     */
-    maxIterations: number;
-    /**
-     * The maximum change allowed between iterations when performing iterative calculations.
-     */
-    maxIterateChange: number;
 }
 interface CommitView extends AbstractModel.CommitView {
 }

package/types/src/calculation/ICalculation.d.ts

@@ -77,6 +77,63 @@ export interface ICalculation extends IModel {
      * This is similar convenience method for `getCalculation().createFormula(expression).evaluate(options)`.
      */
     evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+    /**
+     * When the engine recalculates on its own — Excel's Calculation Options.
+     *
+     * @remarks
+     * In {@link ICalculation.CalculationMode.Automatic} every commit that dirties a formula
+     * schedules a pass. In {@link ICalculation.CalculationMode.Manual} an edit only marks its
+     * dependents out of date ({@link isCalculationRequired}) and nothing is recalculated — volatile
+     * functions (`NOW`, `RAND`) stop re-rolling too — until {@link calculate}: Excel's F9 (every
+     * sheet), Shift+F9 (`scope`) and Ctrl+Alt+F9 (`full`). {@link ready} resolves at once in manual
+     * mode; a caller that wants current values calls {@link calculate}.
+     *
+     * @defaultValue {@link ICalculation.CalculationMode.Automatic}
+     */
+    getCalculationMode(): ICalculation.CalculationMode;
+    /**
+     * Sets the calculation mode.
+     *
+     * @remarks
+     * Leaving manual mode recalculates whatever is out of date, as Excel does.
+     * {@link ICalculation.CalculationMode.AutomaticExceptTables} is accepted for parity with the
+     * file format and Office Scripts; this engine has no what-if data tables, so it recalculates
+     * exactly as `Automatic` does.
+     */
+    setCalculationMode(mode: ICalculation.CalculationMode): this;
+    /**
+     * Whether any formula is out of date — Excel's `Calculate` indicator in the status bar.
+     *
+     * @remarks
+     * Meaningful in manual mode, where edits accumulate until {@link calculate}. In automatic
+     * mode it is `true` only between an edit and the pass it schedules.
+     */
+    isCalculationRequired(): boolean;
+    /**
+     * How a reference cycle is resolved — Excel's "Enable iterative calculation" and its limits.
+     *
+     * @see {@link ICalculation.IterativeCalculation}
+     */
+    getIterativeCalculation(): ICalculation.IterativeCalculation;
+    /**
+     * Enables, disables or configures iterative calculation.
+     *
+     * @param options `true`/`false` toggles `enabled` alone; an object updates the fields given and
+     * keeps the rest.
+     *
+     * @remarks
+     * Every cell in a cycle is recalculated when this changes: turning iteration on resolves the
+     * cycles the workbook shows as unresolved, turning it off writes `0` to them again.
+     */
+    setIterativeCalculation(options: boolean | Partial<ICalculation.IterativeCalculation>): this;
+    /**
+     * The calculation settings as JSON — what an xlsx carries in `calcPr`.
+     *
+     * @remarks
+     * Sparse: a setting at its default is omitted. Settings a file carried that this engine does
+     * not act on (`calcOnSave`, `fullCalcOnLoad`, `fullPrecision`, …) are kept and written back.
+     */
+    toJSON(): ICalculation.JSON;
     /**
      * Add Listeners.
      *
@@ -105,6 +162,87 @@ export declare namespace ICalculation {
      * tokenizer, the AST, a formula input — is ever handed an expression of unbounded size.
      */
     const MAX_EXPRESSION_LENGTH = 8192;
+    /**
+     * A reference cycle — the answer to "why is this cell `0`".
+     *
+     * @remarks
+     * A cell is in a cycle when calculating it opens its own value, directly or through other cells
+     * — `=A1+1` in A1, `=OFFSET(A1,0,0)` in A1, `=SUMIF(B1,C1,A1)` in A1 while B1 matches C1. With
+     * iterative calculation off (the default, and Excel's) every cell in a cycle, and every cell
+     * downstream of one, evaluates to `0`; nothing on the value says why. This does.
+     *
+     * Reached from a cell — {@link ICell.getCircularReference} answers it for members and for
+     * downstream cells alike — and carried by the `ICellRange.Feature.Circular` regions, so a
+     * range, a sheet or the workbook is asked the way any other error is asked:
+     * `getCounts(Feature.Circular)` for how many, `getRegions(Feature.Circular)` for which, with
+     * this object as each region's payload. There is no list of cycles on the calculation: nobody
+     * starts from the cycle; they start from a cell or a range and want to know more.
+     *
+     * Live, not a snapshot: it reads the engine's cycle table on every call and drops members whose
+     * formula has since been edited away, so a stale handle answers `getMemberCount() === 0`.
+     * Persists until the last member is edited away.
+     */
+    interface ICircularReference {
+        /**
+         * The cell named for the cycle, the way Excel's status bar names one
+         * (`Worksheet.CircularReference` likewise answers a single cell): the first member in
+         * row-major order. `scope` is the sheet name, or `null` when the member lives in a named
+         * formula's body rather than on a sheet.
+         */
+        getRepresentative(): IRange.CellCoords | null;
+        /**
+         * Every cell IN the cycle, in row-major order, `scope` set to the sheet name. Small — a cycle
+         * is the cells that read each other, not everything that reads them (that is
+         * {@link getDownstreamCount}).
+         */
+        getMembers(): readonly IRange.CellCoords[];
+        /** How many cells are IN the cycle, the representative included. */
+        getMemberCount(): number;
+        /** How many cells read the cycle (transitively) and evaluate to `0` because of it. */
+        getDownstreamCount(): number;
+        /**
+         * Whether `coords` is IN the cycle, as opposed to downstream of it. A cell that reads a
+         * member's `0` answers `false` here but still resolves this cycle from
+         * {@link ICell.getCircularReference} — the tooltip for it says "reads a circular reference
+         * at A1", not "is one".
+         */
+        isMember(coords: IRange.CellCoords): boolean;
+        /**
+         * The cycle as a walk of reads from `from` back to itself — each cell reads the next, and
+         * the last reads the first. A cycle has no start, so it is told from the cell that asks:
+         * with `A1 = B1+1` and `B1 = A1+1`, asked from A1 it is `[A1, B1]` (A1 → B1 → A1), asked
+         * from B1 it is `[B1, A1]`. A cycle of one is `[A1]`.
+         *
+         * @remarks
+         * Exact, not inferred from formula text: it is the order the engine found the cycle in,
+         * which is the order the reads happened — a dynamic read (`INDIRECT`, `OFFSET`) is a step
+         * like any other. Interlocking cycles share members; the walk follows the read that closed
+         * the cycle `from` was found in, so it is ONE loop through that cell, not every member
+         * ({@link getMembers} is every member).
+         *
+         * Empty when `from` is not a live member — a downstream cell asks from
+         * {@link getRepresentative}.
+         */
+        getPath(from: IRange.CellCoords): readonly IRange.CellCoords[];
+        /**
+         * Whether iterative calculation was on when the cycle was last evaluated. When `false` the
+         * cycle is unresolved and every member and downstream cell is `0`; the iteration answers
+         * below are then meaningless (`0` sweeps, no change).
+         */
+        isIterative(): boolean;
+        /**
+         * Whether iterative calculation settled it: every member moved by less than the workbook's
+         * `maxIterateChange` in the last sweep. Always `false` with iteration off.
+         */
+        isConverged(): boolean;
+        /** How many sweeps the last evaluation ran — up to the workbook's `maxIterations`. */
+        getIterationCount(): number;
+        /**
+         * The largest change any member made in the last sweep — what stopped the iteration when
+         * {@link isConverged}, what it never got under when not. `0` with iteration off.
+         */
+        getLastChange(): number;
+    }
     /**
      * Represents a formula that can be evaluated.
      */
@@ -572,6 +710,11 @@ export declare namespace ICalculation {
          * two diverge exactly where normalization is lossy — a number (`3.0` → `3`, `1**2` → `100`) or a
          * cell (raw `b2` vs the resolved coords). `undefined` only for a token with no captured source
          * image (e.g. a reference the engine rewrote programmatically rather than one the user typed).
+         *
+         * A reference literal is ONE span: a typed sheet qualifier and a trailing spill anchor ride inside
+         * the `cell`/`named` token's `text` (`Sheet2!A1#`), so the caret rules an editor applies per token
+         * treat the whole reference as one. The anchor keeps its own `postfix` token (carrying the same
+         * {@link referenceIndex}) imaging the empty string, so the concatenation above still holds.
          */
         text?: string;
         /**
@@ -778,8 +921,16 @@ export declare namespace ICalculation {
         /**
          * Called when the calculation has been updated and
          * a calculation has not been started.
+         *
+         * @remarks
+         * In manual mode this is every edit that leaves a formula out of date — see
+         * {@link ICalculation.isCalculationRequired}.
          */
         onStale?(source: ICalculation): void;
+        /**
+         * Called when the calculation mode or the iterative-calculation settings change.
+         */
+        onOptionsChange?(source: ICalculation): void;
         /**
          * Called when a calculation is starting.
          */
@@ -863,6 +1014,38 @@ export declare namespace ICalculation {
         readonly AutomaticExceptTables: "automaticExceptTables";
     };
     type CalculationMode = typeof CalculationMode[keyof typeof CalculationMode];
+    /**
+     * Iterative calculation — Excel's "Enable iterative calculation" with its two limits.
+     *
+     * @remarks
+     * With it off a reference cycle evaluates to `0` and is reported as unresolved. With it on the
+     * cells of the cycle are re-evaluated in turn, each read seeing the latest value, until no cell
+     * moved by {@link maxChange} or {@link maxIterations} sweeps ran — and the results persist into
+     * the next recalculation, which re-runs every cycle the way it re-runs `NOW()`: `=A1+1` in A1 is
+     * a counter that advances by `maxIterations` per recalc. A cycle that stops on the sweep cap is
+     * still reported ({@link ICircularReference.isConverged}); a converged one is not.
+     *
+     * Office Scripts calls the count `maxIteration`; the file format `iterateCount` / `iterateDelta`.
+     */
+    interface IterativeCalculation {
+        /**
+         * @defaultValue `false`
+         */
+        enabled: boolean;
+        /**
+         * The most sweeps one recalculation runs over a cycle.
+         *
+         * @defaultValue `100`
+         */
+        maxIterations: number;
+        /**
+         * Sweeps stop early once every cell in the cycle moved by less than this. A non-numeric
+         * change (text, error) never counts as settled.
+         *
+         * @defaultValue `0.001`
+         */
+        maxChange: number;
+    }
     /**
      * Represents the status of a calculation result
      */

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

@@ -129,6 +129,26 @@ export declare const isRangedNode: (node: ASTNode) => boolean;
  * parse path has no access to — and "SUM is not a defined name" is an honest answer.
  */
 export declare const findNonReferenceIntersectionOperand: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => ASTNode | null;
+/**
+ * Finds a spill-anchor (`#`) operand that cannot possibly be a reference, or `null` if the formula
+ * has none.
+ *
+ * @param root The root of the formula's AST.
+ * @param getFunction Resolves a function's stableId to its declaration, or `null`.
+ *
+ * @remarks
+ * The anchor answers "where did the formula anchored HERE put its result", so its operand is a
+ * location, never a value — Excel's own declaration is `ANCHORARRAY(Range) -> Range|Array`. An
+ * operand that provably computes a value is refused at ENTRY, the same verdict (and the same
+ * predicate — {@link isDefinitelyNotReferenceNode}) as the intersection operand beside it.
+ *
+ * Measured against Excel 16.0 desktop (`spreadsheetbench/formula-tests/probe-anchor.ps1`): `=5#`,
+ * `={1,2}#` and `=SUM(X1:X3)#` cannot be typed at all, while a reference-returning call
+ * (`=INDEX(X1:X3,1)#`, `=OFFSET(B3,0,0)#`) is accepted. A NAME is accepted too — what it resolves
+ * to is not knowable here — and answers `#VALUE!` when it turns out to hold a constant, which is
+ * the runtime half of this same rule.
+ */
+export declare const findNonReferenceAnchorOperand: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => ASTNode | null;
 /**
  * Finds an array constant whose rows are not all the same length — a JAGGED literal such as
  * `{1,2;3}`.

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

@@ -92,8 +92,11 @@ export declare class FormulaParser extends EmbeddedActionsParser {
     /** Matches a single `+` or `-` token. Used as a helper by `_rulePrefixOp` and `_ruleLiteralForArray`. */
     protected _rulePlusMinusOp: import('chevrotain').ParserMethod<[], IToken>;
     /**
-     * Applies zero or more postfix operators (`%` percent, `#` spill anchor) to the node
-     * produced by `_rulePrefixOp`, building a right-growing postfix AST chain.
+     * Applies zero or more `%` percent postfixes to the node produced by `_rulePrefixOp`, building a
+     * right-growing postfix AST chain.
+     *
+     * The other postfix, the spill anchor `#`, is NOT here: it binds tighter than the unary prefixes
+     * and looser than `:`, so it lives inside `_ruleRangeOp`.
      */
     protected _rulePostfixOp: import('chevrotain').ParserMethod<[], ASTNode<TokenType, any>>;
     /**
@@ -106,10 +109,33 @@ export declare class FormulaParser extends EmbeddedActionsParser {
      */
     protected _rulePrefixOp: import('chevrotain').ParserMethod<[], ASTNode<TokenType, any>>;
     /**
-     * Folds the range operators (`:` range, `.:.` / `.:` / `:.` range-trim) — Excel's highest-precedence
-     * operators, binding tighter than the unary prefixes (`_rulePrefixOp`). Left-associative, single level
-     * (`A1:B2:C3` = `(A1:B2):C3`); every operator produces a reference infix node (`isRange = true`) so the
-     * whole span resolves to one reference. This rule sits just above the `_ruleCallOp` leaf.
+     * Folds the range operators (`:` range, `.:.` / `.:` / `:.` range-trim) and the spill anchor `#` —
+     * Excel's highest-precedence operators, binding tighter than the unary prefixes (`_rulePrefixOp`).
+     * Left-associative, single level (`A1:B2:C3` = `(A1:B2):C3`); every operator produces a reference
+     * node (`isRange = true`) so the whole span resolves to one reference. This rule sits just above the
+     * `_ruleCallOp` leaf.
+     *
+     * ── Why `#` is folded HERE, with the range operators ─────────────────────────────────────────
+     *
+     * The anchor is a postfix over the reference accumulated SO FAR, not over the primary in front of
+     * it: `A1:B2#` is `(A1:B2)#`, whose operand is a multi-cell reference — `#REF!` in Excel. What a
+     * `#` before the operator anchors is only its own operand, because that is all that has
+     * accumulated yet — `B3#:B1` is `(B3#):B1`, the rectangle spanning B1 and the whole of B3's spill.
+     *
+     * Measured against Excel 16.0 desktop (`spreadsheetbench/formula-tests/probe-anchor.ps1`); the
+     * xlsx round-trip is the unambiguous witness, since the anchor lowers to an explicit call there:
+     *
+     * | typed | value | stored |
+     * | --- | --- | --- |
+     * | `B1:B3#` | `#REF!` | `_xlfn.ANCHORARRAY(B1:B3)` |
+     * | `B11:B3#` | `#REF!` | `_xlfn.ANCHORARRAY(B3:B11)` — re-imaged as `=B3:B11#` |
+     * | `B3#:B1` | B1:B5 | `_xlfn.ANCHORARRAY(B3):B1` |
+     *
+     * Excel ONLINE parses the same text differently — its grammar attaches `#` to the PRIMARY
+     * (`re = q(primary, any(Pound, StructRef), ...)` in the shipped engine), so it reads `A1:(B2#)`.
+     * Desktop wins. (The one desktop form this fold does not reproduce is `B3#:B5#`, which Excel
+     * stores as `ANCHORARRAY(B3):ANCHORARRAY(B5)` while we anchor the accumulation. Both are `#REF!`
+     * — an anchor over a multi-cell reference either way — so only the re-imaged text differs.)
      */
     protected _ruleRangeOp: import('chevrotain').ParserMethod<[], ASTNode<TokenType, any>>;
     /**

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

@@ -4,6 +4,8 @@ import { ISpatialMap, ISpatialMap3D } from '../../collections';
 import { FormulaSpatialValue, PrecedentSpatialValue, PrecedentKind } from '../spatial';
 import { ICalcGrid } from '../grid';
 import { IContextContainer, CalcNode } from '../state';
+import { ReadHook } from '../state/_ReadObservedGrid';
+import { CircularReference, CycleHost } from './CircularReference';
 /**
  * Executes a calculation cycle: collect → mark-and-plan → evaluate.
  *
@@ -17,16 +19,77 @@ export declare class CalcExecutor {
     private readonly _requestCalculate;
     protected _pendingCalcs: Set<CalcNode>;
     /**
-     * Nodes the topological sort could not order — a reference cycle and everything downstream of it.
-     * Rewritten by every `doMarkAndPlan` that detects one; meaningless otherwise.
+     * 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
+     * landed on its own cell, each carrying its `cycleRole`. The module scratch `_circularNodes`,
+     * this many; a node in it is flagged `CalcState.Rostered`. Emptied when a pass starts.
      */
-    protected _circularNodes: CalcNode[];
+    protected _circularNodesLength: number;
+    /** The nodes the current `doMarkAndPlan` handed to demand evaluation, in worklist order. */
+    protected _demandBatch: CalcNode[];
+    /** {@link _onPassRead} as a bound hook — one closure for the executor's lifetime. */
+    protected _passHook: ReadHook;
     /**
-     * Identifies the cycle last reported, so an unchanged one is not re-announced. A circular
-     * reference persists until the user edits it away, and every pass re-detects it — including
-     * volatile ones, which would otherwise log forever. `null` once a pass completes cycle-free.
+     * Marks a node downstream of the cycle `_taintGroup` names (design §2.1: every cell that reads
+     * a cycle, however it came to, is `0`). It skips evaluation — `Done` with a demand result of
+     * `0` — and taints its own dependents when the plan reaches it. A node already in a cycle keeps
+     * its role.
      */
-    protected _circularReported: string | null;
+    protected _taintDownstream: (calc: CalcNode) => void;
+    protected _taintGroup: number;
+    /**
+     * Iterative calculation for the pass in progress (design §6.3); `null` with it off. Under it a
+     * read of a `Waiting` node is not an abort: the reader goes on with the node's previous value
+     * and the slice is marked once the reader returns (`_iterHits`); a read of a member's result
+     * makes the reader downstream without aborting it either; and {@link _demandSweep}
+     * re-evaluates the members until they settle.
+     */
+    protected _iterate: CalcExecutor.IterateOptions | null;
+    /** Inside {@link doDemandEvaluate} — where a `Waiting` read under iteration is marked in place. */
+    protected _demandActive: boolean;
+    /**
+     * 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.
+     */
+    protected _iterHitsLength: number;
+    protected _iterMembersLength: number;
+    protected _iterDownstreamLength: number;
+    /** The pass the hook answers for; inert otherwise. Set by `doMarkAndPlan`, released with `_gridUpdates`. */
+    protected _passActive: boolean;
+    protected _passCycleId: number;
+    protected _passMarkId: number;
+    /**
+     * Commits `doEvaluate`'s pending batch — installed for the length of a `doEvaluate`. A read
+     * that lands on a node evaluated but not yet committed needs nothing more than this: the
+     * value is right, it is just not in the grid yet.
+     */
+    protected _flush: (() => void) | 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
+     * the index payloads carry and `ICell.getCircularReference()` answers. Persists across passes
+     * (a node moves when a commit writes its delta, `_trackCircular`) and is confirmed against the
+     * graph on read, since a deleted formula's node lingers here until something re-evaluates its
+     * cell. A cycle is created on first sight and dropped when its last node leaves.
+     */
+    protected _cycles: Map<number, CircularReference>;
+    /** What a {@link CircularReference} may ask of this executor; built once, shared by all. */
+    protected _cycleHost: CycleHost;
+    /** Last cycle id handed out by a demand pass; ids are unique across passes. */
+    protected _cycleGroupNext: 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
+     * chain Kahn could not order should show about one per node at most.
+     */
+    protected _demandStats: {
+        evaluations: number;
+        retries: number;
+    };
     _gridUpdates: Map<string, ICalcGrid.IncrementalUpdates> | null;
     _addDynamicPrecedent: ((node: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind) => void) | null;
     constructor(container: IContextContainer, context: IFormulaContext, requestCalculate: () => void);
@@ -45,14 +108,124 @@ export declare class CalcExecutor {
      */
     execute(cycleId: number, options: CalcExecutor.ExecuteOptions, state: CalcExecutor.ExecuteState): CalcExecutor.ExecuteResult | null;
     /**
-     * Reports the reference cycle found by the preceding {@link doMarkAndPlan}.
+     * The read hook of a pass (DESIGN-CIRCULAR-CALC.md §4.3, §5), shared by both paths: armed for
+     * every reference while a node is evaluated by demand, and for dynamic-branch references
+     * (`OFFSET`/`INDIRECT`/`INDEX` results) on the ordinary path. A read that lands on a node of
+     * THIS pass decides: `Waiting` (on the in-progress stack — transitively waiting on the reader)
+     * is a cycle; `Unevaluated` suspends the reader until it is done; `Evaluated` (in the pending
+     * 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.
+     */
+    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.
+     */
+    private _iterRead;
+    /**
+     * The nodes of this pass inside `coords` that are still `Unevaluated`, written into `into` from
+     * slot `length` on; returns the new length.
+     */
+    private _collectUnevaluated;
+    /**
+     * Evaluates `worklist` by demand (DESIGN-CIRCULAR-CALC.md §4.3): each node is evaluated with the
+     * read hook armed; a read that lands on one not yet evaluated suspends the reader and evaluates
+     * that one first (`NeedsFirst`); a read that lands on one already suspended — waiting,
+     * transitively, on the reader — is a cycle (`Circular`), and the in-progress stack from it up
+     * to the reader are the members, written `0`. A node that reads a member is downstream and
+     * writes `0` too. Everything else simply computes: an unorderable static edge that is never
+     * read (`OFFSET`'s anchor, `ROW`'s argument, an untaken `IF` branch) makes no cycle.
+     *
+     * @remarks
+     * Two callers: `doEvaluate` when the plan reaches the nodes `doMarkAndPlan` could not order
+     * (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.
+     */
+    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.
+     */
+    private _writeEarly;
+    /** 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.
+     * 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()`).
+     */
+    private _demandSweep;
+    /** Clears the `IterHit` flags of the hits not consumed by {@link _demandRun}'s loop and empties the list. */
+    private _drainIterHits;
+    /**
+     * 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.
+     */
+    private _demandEvaluateOne;
+    /**
+     * @internal
+     * Every cell the sheets currently show in a cycle or downstream of one, as dirty regions — what
+     * a change of the iterative-calculation setting re-evaluates.
+     */
+    getCycleCells(): ISpatialMap.Entry[];
+    /** Whether the pass in progress found a cycle member. */
+    protected _hasCycle(): boolean;
+    /** Adds `node` to the pass's circular roster, once. */
+    private _addCircular;
+    /** Empties the roster for a new pass, clearing each node's `Rostered` flag on the way out. */
+    private _resetCircular;
+    /**
+     * Records the difference between what the sheet's circular index shows for `node` and what
+     * this pass decided, in the cycle table and in the pass's conflating delta — the same path a
+     * pending status takes to the sheet (design §7.2). Called only when one of the two is set.
+     */
+    protected _trackCircular(node: CalcNode, updates: ICalcGrid.IncrementalUpdates, major: number, minor: number, isColumn: boolean): void;
+    /** The public face of cycle `group`, created on first sight. */
+    private _cycleOf;
+    /**
+     * Whether `node` is still the node registered for its own cell.
      *
      * @remarks
-     * One line per calculation pass, naming a representative cell the way Excel's status bar does
-     * (`Worksheet.CircularReference` likewise returns a single cell, not the whole set). The count
-     * covers everything downstream of the cycle too, so it is normally larger than the cycle itself.
+     * A `CalcNode` is a plain graph object reachable by identity long after the grid has replaced or
+     * dropped its block — the same hazard `doCollectVolatileCalcs` guards against with `isLiveBlock`.
+     */
+    protected isLiveNode(node: CalcNode): boolean;
+    /**
+     * @internal
+     * A copy of the last pass's circular roster — see {@link _circularNodesLength} — each node
+     * carrying the {@link CycleRole} its reads gave it. Describes the last pass only.
      */
-    protected reportCircular(): void;
+    getCircularNodes(): readonly CalcNode[];
+    /** @internal Demand-pass counters since construction: evaluations and `NeedsFirst` retries. */
+    getDemandStats(): {
+        evaluations: number;
+        retries: number;
+    };
     /**
      * Collects and marks all volatile CalcNodes.
      *
@@ -79,7 +252,7 @@ export declare class CalcExecutor {
      * @remarks
      * Uses Kahn's algorithm.
      */
-    doMarkAndPlan(cycleId: number, markId: number, initial: FixedPackedArray<CalcNode>, plan: FixedPackedArray<CalcNode>): boolean;
+    doMarkAndPlan(cycleId: number, markId: number, initial: FixedPackedArray<CalcNode>, plan: FixedPackedArray<CalcNode>, forceDemand?: boolean): boolean;
     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 {
@@ -96,6 +269,24 @@ export declare namespace CalcExecutor {
          * The grid to seed the pass FROM — `ICalculation.CalculateOptions.scope`, i.e. "Calculate Sheet".
          */
         scopeGridId?: string;
+        /**
+         * Iterative calculation (design §6.3) for the pass; `null`/absent with it off.
+         */
+        iterate?: IterateOptions | null;
+    }
+    /** The two limits of `ICalculation.IterativeCalculation`. */
+    interface IterateOptions {
+        maxIterations: number;
+        maxChange: number;
+    }
+    /** How a cycle's last iterated evaluation ended — what `ICircularReference` answers. */
+    interface IterationResult {
+        /** Every member moved by less than `maxChange` in the last sweep. */
+        converged: boolean;
+        /** Sweeps run, the first evaluation included. */
+        iterationCount: number;
+        /** The largest change any member made in the last sweep. */
+        lastChange: number;
     }
     /** Snapshot of Calculation's persistent state for one pass */
     interface ExecuteState {

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

@@ -1,7 +1,38 @@
 import { IRange, Scalar } from '@sheetxl/primitives';
 import { Tuple, ISpatialMap } from '../../collections';
+import { CalcSignal } from '../../primitives/CalcSignal';
 import { CalcNode } from '../state';
 import { PrecedentSpatialValue, FormulaSpatialValue } from '../spatial';
+/**
+ * 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.
+ */
+export declare class NeedsFirstSignal extends CalcSignal {
+    readonly nodes: readonly CalcNode[];
+    readonly count: number;
+    /**
+     * @param nodes A scratch array the executor reuses across reads; only the first `count` slots
+     * belong to this read, and the catcher consumes them before the next read can overwrite them.
+     */
+    constructor(nodes: readonly CalcNode[], count: number);
+}
+/**
+ * Raised from a read that landed on a node already suspended — one that is, transitively,
+ * waiting on the reader. The in-progress stack from `node` up to the reader is a cycle.
+ */
+export declare class CircularSignal extends CalcSignal {
+    readonly node: CalcNode;
+    constructor(node: CalcNode);
+}
+/**
+ * Raised from a read that landed on a cycle member or a cell downstream of one: the reader is
+ * downstream too and writes `0` without finishing (Excel, iterative calc off — `=A1+100` beside
+ * `=A1+1` in A1 is `0`, not `100`).
+ */
+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>;
 /**
  * TODO - document and/or rationalize with visitPrecedentBlock