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

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.
      */
@@ -783,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.
          */
@@ -868,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/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

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

@@ -0,0 +1,81 @@
+import { IRange } from '@sheetxl/primitives';
+import { ICalculation } from '../ICalculation';
+import { CalcNode } from '../state';
+import { CircularEntry } from '../spatial';
+import { CalcExecutor } from './CalcExecutor';
+/**
+ * The two graph questions a {@link CircularReference} cannot answer on its own; built once by
+ * the executor, shared by every cycle.
+ */
+export interface CycleHost {
+    /** Whether `node` is still the node registered for its own cell (a deleted formula's is not). */
+    isLiveNode(node: CalcNode): boolean;
+    /** The sheet name for a grid id, or `undefined` for a virtual grid (a named formula's body). */
+    resolveScope(gridId: string): string | undefined;
+}
+/**
+ * One reference cycle (DESIGN-CIRCULAR-CALC.md §7.3): the executor's record of it and its public
+ * face in one — the object a `Feature.Circular` region carries as its payload and
+ * `ICell.getCircularReference()` answers. It holds the nodes the sheet index currently shows as
+ * its members and as downstream of it, the interned index payloads, and how the sweep that
+ * settled it ended. It persists across passes — a node moves between cycles when a commit writes
+ * its delta (`_trackCircular`) — and is dropped when its last node leaves.
+ *
+ * @remarks
+ * Every read filters through {@link CycleHost.isLiveNode}: a pass that deletes the offending
+ * formula never plans, so the sets cannot clear themselves, and a member is counted only while
+ * its cell still holds the block the cycle was found in (design §7.3, trap 5).
+ *
+ * The iteration answers come from the sweep that settled the cycle (design §6.3). A cycle id is
+ * minted by the pass that finds it, so a cycle evaluated with iteration off is a different object
+ * with no record — `isIterative()` is exactly "a sweep settled this one".
+ */
+export declare class CircularReference implements ICalculation.ICircularReference {
+    protected readonly _host: CycleHost;
+    protected readonly _cycleId: number;
+    /** @internal The nodes the sheet index shows in the cycle; maintained by the executor. */
+    readonly members: Set<CalcNode>;
+    /** @internal The nodes the sheet index shows downstream of the cycle; maintained by the executor. */
+    readonly downstream: Set<CalcNode>;
+    /** One payload per kind, so equal payloads are one object and adjacent cells one region. */
+    protected _memberEntry: CircularEntry | null;
+    protected _downstreamEntry: CircularEntry | null;
+    protected _iteration: CalcExecutor.IterationResult | null;
+    constructor(host: CycleHost, cycleId: number);
+    /** @internal The executor's key for this cycle. */
+    getCycleId(): number;
+    /** @internal Whether the sheet index shows no cell in or downstream of the cycle any more. */
+    isEmpty(): boolean;
+    /** @internal The index payload for the cycle's members or for its downstream cells. */
+    getEntry(isMember: boolean): CircularEntry;
+    /** @internal How the sweep that settled this cycle ended; written by the executor. */
+    setIteration(result: CalcExecutor.IterationResult): void;
+    /** @inheritdoc ICalculation.ICircularReference.getRepresentative */
+    getRepresentative(): IRange.CellCoords | null;
+    /** @inheritdoc ICalculation.ICircularReference.getMembers */
+    getMembers(): readonly IRange.CellCoords[];
+    /** @inheritdoc ICalculation.ICircularReference.getMemberCount */
+    getMemberCount(): number;
+    /** @inheritdoc ICalculation.ICircularReference.getDownstreamCount */
+    getDownstreamCount(): number;
+    /** @inheritdoc ICalculation.ICircularReference.isMember */
+    isMember(coords: IRange.CellCoords): boolean;
+    /** @inheritdoc ICalculation.ICircularReference.getPath */
+    getPath(from: IRange.CellCoords): readonly IRange.CellCoords[];
+    /** The live member at `coords`, or `null`. */
+    protected _memberAt(coords: IRange.CellCoords): CalcNode | null;
+    /** @inheritdoc ICalculation.ICircularReference.isIterative */
+    isIterative(): boolean;
+    /** @inheritdoc ICalculation.ICircularReference.isConverged */
+    isConverged(): boolean;
+    /** @inheritdoc ICalculation.ICircularReference.getIterationCount */
+    getIterationCount(): number;
+    /** @inheritdoc ICalculation.ICircularReference.getLastChange */
+    getLastChange(): 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;
+    protected _scopeOf(node: CalcNode): string | null;
+    protected _toCoords(node: CalcNode): IRange.CellCoords;
+}
+//# sourceMappingURL=CircularReference.d.ts.map

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

@@ -3,7 +3,7 @@ import { IListener } from '../../listener';
 import { ListenerEmitter } from '../../listener/ListenerEmitter';
 import { Tuple, ISpatialQuery, ISparseGrid, ISpatialMap, ISpatialMap3D } from '../../collections';
 import { IContextContainer, CalcNode } from '../state';
-import { SpillEntry, FormulaSpatialValue, ContentfulSpatialValue, PrecedentSpatialValue } from '../spatial';
+import { SpillEntry, FormulaSpatialValue, ContentfulSpatialValue, PrecedentSpatialValue, CircularEntry } from '../spatial';
 import { IFormulaBlock } from '../formula';
 import { ReferenceCoords } from '../Types';
 import { ICalculation } from '../ICalculation';
@@ -20,12 +20,14 @@ export declare class CalcGrid implements ICalcGrid {
     _spillSpatial: ISpatialMap<SpillEntry>;
     _errorSpatial: ISpatialMap<string>;
     _pendingSpatial: ISpatialMap<boolean>;
+    _circularSpatial: ISpatialMap<CircularEntry>;
     _contentfulSpatial: ISpatialMap<ContentfulSpatialValue>;
     _notifyValues: ISpatialMap;
     _notifySpillsInsert: ISpatialMap.Entry<SpillEntry>[];
     _notifySpillsRemove: IRange.Coords[];
     _notifyFormats: ISpatialMap;
     _notifyPending: ISpatialMap<boolean>;
+    _notifyCircular: ISpatialMap<CircularEntry | false>;
     _cloneKey?: CalcGrid;
     _version: number;
     _iterationId: number;

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

@@ -1,7 +1,7 @@
 import { IRange, Scalar } from '@sheetxl/primitives';
 import { Tuple, ISparseGrid, ISpatialMap, ISpatialMap3D } from '../../collections';
 import { CalcNode } from '../state';
-import { ContentfulSpatialValue, FormulaSpatialValue, SpillEntry, PrecedentSpatialValue, PrecedentKind } from '../spatial';
+import { ContentfulSpatialValue, FormulaSpatialValue, SpillEntry, PrecedentSpatialValue, CircularEntry, PrecedentKind } from '../spatial';
 import { ReferenceCoords } from '../Types';
 export declare function anchorCompareValues(a: ISpatialMap.Entry<FormulaSpatialValue>, removing: ISpatialMap.Entry<FormulaSpatialValue>): boolean;
 /**
@@ -19,7 +19,8 @@ export declare function isTopLeft(rowIndex: number, colIndex: number, range: IRa
  * This code will inline spill errors but spill results are handled in calculations.
  */
 export declare function applyContentful(cycleId: number, removes: readonly IRange.Coords[] | null | undefined, inserts: ISpatialMap.Entry[] | null | undefined, contentfulSpatial: ISpatialMap<ContentfulSpatialValue>, spillSpatial: ISpatialMap<SpillEntry>, values: ISparseGrid<Scalar>, addDirty?: (colStart: number, rowStart: number, colEnd: number, rowEnd: number) => void, notifyValuesSpatial?: ISpatialMap, notifySpills?: (insert: ISpatialMap.Entry<SpillEntry>, remove: ISpatialMap.Entry<SpillEntry>) => void, notifyPending?: ISpatialMap<boolean>, errorSpatial?: ISpatialMap<string>, // notifyErrorSpatial,
-isColumn?: boolean, notifyCalc?: boolean): IRange.Coords | null;
+isColumn?: boolean, notifyCalc?: boolean, // should notify. this is to differentiate between user set values and calc set values
+circularSpatial?: ISpatialMap<CircularEntry>): IRange.Coords | null;
 /**
  * Creates a map from tuples
  *