@sheetxl/sdk 0.7.28-beta.3 → 0.8.0-beta.1

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.
  *
@@ -15,18 +17,129 @@ 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;
     /**
-     * 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;
+    };
+    /**
+     * 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 — `__sxlCalc.mode('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;
+    /**
+     * 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);
@@ -45,14 +158,130 @@ 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
-     * 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.
+     * 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 reportCircular(): void;
+    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
+     * 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.
+     */
+    getCircularNodes(): readonly CalcNode[];
+    /**
+     * @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 (`__sxlCalc.reset()`). */
+    resetStats(): void;
     /**
      * Collects and marks all volatile CalcNodes.
      *
@@ -79,7 +308,18 @@ 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;
+    /**
+     * 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.
+     */
+    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 {
@@ -96,6 +336,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 {
@@ -105,6 +363,48 @@ export declare namespace CalcExecutor {
         /** 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;
+    }
+    /** 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;
+        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

@@ -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
  *

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

@@ -5,7 +5,7 @@ import { IListener } from '../../listener';
 import { IHistory } from '../../history';
 import { ISpatialQuery, ISpatialMap, ISparseGrid, Tuple } from '../../collections';
 import { IFormulaBlock } from '../formula';
-import { ContentfulSpatialValue, SpillEntry } from '../spatial';
+import { ContentfulSpatialValue, SpillEntry, CircularEntry } from '../spatial';
 import { ReferenceCoords, NamedReference } from '../Types';
 import { ICalculation } from '../ICalculation';
 /**
@@ -311,6 +311,14 @@ export declare namespace ICalcGrid {
          * These are guaranteed to not overlap.
          */
         pendingUpdates?: ISpatialMap.Entry<boolean>[];
+        /**
+         * Cells that entered or left a reference cycle (or the set downstream of one). A `null`
+         * value is a removal.
+         *
+         * @remarks
+         * These are guaranteed to not overlap.
+         */
+        circularUpdates?: ISpatialMap.Entry<CircularEntry | null>[];
     }
     /**
      * Returns from `ICalcGrid.beginUpdates()`.
@@ -324,13 +332,16 @@ export declare namespace 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>;
         pendingConflating: ISpatialMap.IConflatingEntries<boolean> | null;
+        circularConflating: ISpatialMap.IConflatingEntries<CircularEntry | false> | null;
         errorRemovesConflating: ISpatialMap.IConflatingEntries<null> | null;
         errorInsertsConflating: ISpatialMap.IConflatingEntries<string> | null;
         formatsConflating: ISpatialMap.IConflatingEntries | null;

package/types/src/calculation/spatial/CircularEntry.d.ts

@@ -0,0 +1,18 @@
+import { ICalculation } from '../ICalculation';
+/**
+ * What a sheet's circular index says about a cell (DESIGN-CIRCULAR-CALC.md §7.2): which
+ * reference cycle it belongs to, and whether it is in the cycle or merely downstream of it.
+ *
+ * @remarks
+ * The value stays what it is (`0`, Excel's answer with iterative calculation off); this is
+ * metadata beside it, the way `SpillEntry` marks a spill zone. Entries are interned per
+ * `(cycle, kind)` by the executor, so equal payloads are the same object and adjacent cells of
+ * one cycle coalesce into one region — and a region's payload IS the cycle, no id to look up.
+ */
+export interface CircularEntry {
+    /** The cycle; one live object per cycle, shared by every cell in it or downstream of it. */
+    readonly cycle: ICalculation.ICircularReference;
+    /** In the cycle, or a reader of it (transitively). Both evaluate to `0`. */
+    readonly kind: 'member' | 'downstream';
+}
+//# sourceMappingURL=CircularEntry.d.ts.map

package/types/src/calculation/spatial/index.d.ts

@@ -1,4 +1,5 @@
 export * from './SpillEntry';
+export * from './CircularEntry';
 export * from './ContentfulSpatialValue';
 export * from './FormulaSpatialValue';
 export * from './PrecedentSpatialValue';